[pdata] Introduce runtime safeguards to catch incorrect pdata mutations

This change introduces an option to enable runtime assertions to catch unintentional pdata mutations in components that are claimed as non-mutating pdata. Without these assertions, runtime errors may still occur, but thrown by unrelated components, making it difficult to troubleshoot the problem.

For now, this doesn't change the default behavior. It just introduces a new method on [Metrics/Traces|Logs].Shared. The method will be applied to fan out consumers in the next PR.

This change unblocks the 1.0 release of pdata. Going-forward we may introduce copy-on-write solution which won't require the runtime assertions. That will be likely part of 2.0 release.

Author: dmitryax

.chloggen/pdata-mutation-assertions.yaml

@@ -0,0 +1,19 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: pdata
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Introduce runtime assertions to catch incorrect pdata mutations
+
+# One or more tracking issues or pull requests related to the change
+issues: [6794]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  This change introduces an option to enable runtime assertions to catch unintentional pdata mutations in components
+  that are claimed as non-mutating pdata. Without these assertions, runtime errors may still occur, but thrown by
+  unrelated components, making it very difficult to troubleshoot.

pdata/internal/cmd/pdatagen/internal/base_fields.go

@@ -12,9 +12,15 @@ import (
 const accessorSliceTemplate = `// {{ .fieldName }} returns the {{ .fieldName }} associated with this {{ .structName }}.
 func (ms {{ .structName }}) {{ .fieldName }}() {{ .packageName }}{{ .returnType }} {
 	{{- if .isCommon }}
-	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}))
+	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}
+	{{- if .isBaseStructCommon -}}
+	, internal.Get{{ .structName }}State(internal.{{ .structName }}(ms))
+	{{- else -}}
+	, ms.state
+	{{- end -}}
+	))
 	{{- else }}
-	return new{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }})
+	return new{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}, ms.state)
 	{{- end }}
 }`
 
@@ -36,14 +42,14 @@ const setTestValueTemplate = `{{ if .isCommon -}}
 	{{- else -}}
 	fillTest{{ .returnType }}(new
 	{{-	end -}}
-	{{ .returnType }}(&tv.orig.{{ .fieldName }}))`
+	{{ .returnType }}(&tv.orig.{{ .fieldName }}, tv.state))`
 
 const accessorsMessageValueTemplate = `// {{ .fieldName }} returns the {{ .lowerFieldName }} associated with this {{ .structName }}.
 func (ms {{ .structName }}) {{ .fieldName }}() {{ .packageName }}{{ .returnType }} {
 	{{- if .isCommon }}
-	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}))
+	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}, ms.state))
 	{{- else }}
-	return new{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }})
+	return new{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}, ms.state)
 	{{- end }}
 }`
 
@@ -65,12 +71,13 @@ func (ms {{ .structName }}) {{ .fieldName }}() {{ .packageName }}{{ .returnType
 
 // Set{{ .fieldName }} replaces the {{ .lowerFieldName }} associated with this {{ .structName }}.
 func (ms {{ .structName }}) Set{{ .fieldName }}(v {{ .returnType }}) {
+	ms.assertMutable()
 	ms.{{ .origAccessor }}.{{ .fieldName }} = v
 }`
 
 const accessorsPrimitiveSliceTemplate = `// {{ .fieldName }} returns the {{ .lowerFieldName }} associated with this {{ .structName }}.
 func (ms {{ .structName }}) {{ .fieldName }}() {{ .packageName }}{{ .returnType }} {
-	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}))
+	return {{ .packageName }}{{ .returnType }}(internal.New{{ .returnType }}(&ms.{{ .origAccessor }}.{{ .fieldName }}, ms.state))
 }`
 
 const oneOfTypeAccessorTemplate = `// {{ .typeFuncName }} returns the type of the {{ .lowerOriginFieldName }} for this {{ .structName }}.
@@ -108,7 +115,7 @@ func (ms {{ .structName }}) {{ .fieldName }}() {{ .returnType }} {
 	if !ok {
 		return {{ .returnType }}{}
 	}
-	return new{{ .returnType }}(v.{{ .fieldName }})
+	return new{{ .returnType }}(v.{{ .fieldName }}, ms.state)
 }
 
 // SetEmpty{{ .fieldName }} sets an empty {{ .lowerFieldName }} to this {{ .structName }}.
@@ -119,7 +126,7 @@ func (ms {{ .structName }}) {{ .fieldName }}() {{ .returnType }} {
 func (ms {{ .structName }}) SetEmpty{{ .fieldName }}() {{ .returnType }} {
 	val := &{{ .originFieldPackageName }}.{{ .fieldName }}{}
 	ms.orig.{{ .originOneOfFieldName }} = &{{ .originStructType }}{{ "{" }}{{ .fieldName }}: val}
-	return new{{ .returnType }}(val)
+	return new{{ .returnType }}(val, ms.state)
 }`
 
 const accessorsOneOfMessageTestTemplate = `func Test{{ .structName }}_{{ .fieldName }}(t *testing.T) {
@@ -147,6 +154,7 @@ func (ms {{ .structName }}) {{ .accessorFieldName }}() {{ .returnType }} {
 
 // Set{{ .accessorFieldName }} replaces the {{ .lowerFieldName }} associated with this {{ .structName }}.
 func (ms {{ .structName }}) Set{{ .accessorFieldName }}(v {{ .returnType }}) {
+	ms.assertMutable()
 	ms.orig.{{ .originOneOfFieldName }} = &{{ .originStructType }}{
 		{{ .originFieldName }}: v,
 	}
@@ -688,7 +696,7 @@ func (omv *oneOfMessageValue) GenerateTests(ms baseStruct, of *oneOfField) strin
 func (omv *oneOfMessageValue) GenerateSetWithTestValue(of *oneOfField) string {
 	return "\ttv.orig." + of.originFieldName + " = &" + of.originTypePrefix + omv.fieldName + "{" + omv.
 		fieldName + ": &" + omv.originFieldPackageName + "." + omv.fieldName + "{}}\n" +
-		"\tfillTest" + omv.returnMessage.structName + "(new" + omv.fieldName + "(tv.orig.Get" + omv.fieldName + "()))"
+		"\tfillTest" + omv.returnMessage.structName + "(new" + omv.fieldName + "(tv.orig.Get" + omv.fieldName + "(), tv.state))"
 }
 
 func (omv *oneOfMessageValue) GenerateCopyToValue(ms baseStruct, of *oneOfField, sb *bytes.Buffer) {

pdata/internal/cmd/pdatagen/internal/base_slices.go

@@ -17,17 +17,24 @@ const sliceTemplate = `// {{ .structName }} logically represents a slice of {{ .
 // Important: zero-initialized instance is not valid for use.
 type {{ .structName }} struct {
 	orig *[]{{ .originElementType }}
+	state internal.State
 }
 
-func new{{ .structName }}(orig *[]{{ .originElementType }}) {{ .structName }} {
-	return {{ .structName }}{orig}
+func new{{ .structName }}(orig *[]{{ .originElementType }}, state internal.State) {{ .structName }} {
+	return {{ .structName }}{orig: orig, state: state}
 }
 
 // New{{ .structName }} creates a {{ .structName }} with 0 elements.
 // Can use "EnsureCapacity" to initialize with a given capacity.
 func New{{ .structName }}() {{ .structName }} {
 	orig := []{{ .originElementType }}(nil)
-	return new{{ .structName }}(&orig)
+	return new{{ .structName }}(&orig, internal.StateExclusive)
+}
+
+func (es {{ .structName }}) assertMutable() {
+	if es.state == internal.StateShared {
+		panic("invalid access to shared data")
+	}
 }
 
 // Len returns the number of elements in the slice.
@@ -73,13 +80,16 @@ func (es {{ .structName }}) EnsureCapacity(newCap int) {
 // AppendEmpty will append to the end of the slice an empty {{ .elementName }}.
 // It returns the newly added {{ .elementName }}.
 func (es {{ .structName }}) AppendEmpty() {{ .elementName }} {
+	es.assertMutable()
 	*es.orig = append(*es.orig, {{ .emptyOriginElement }})
 	return es.At(es.Len() - 1)
 }
 
 // MoveAndAppendTo moves all elements from the current slice and appends them to the dest.
 // The current slice will be cleared.
 func (es {{ .structName }}) MoveAndAppendTo(dest {{ .structName }}) {
+	es.assertMutable()
+	dest.assertMutable()
 	if *dest.orig == nil {
 		// We can simply move the entire vector and avoid any allocations.
 		*dest.orig = *es.orig
@@ -92,6 +102,7 @@ func (es {{ .structName }}) MoveAndAppendTo(dest {{ .structName }}) {
 // RemoveIf calls f sequentially for each element present in the slice.
 // If f returns true, the element is removed from the slice.
 func (es {{ .structName }}) RemoveIf(f func({{ .elementName }}) bool) {
+	es.assertMutable()
 	newLen := 0
 	for i := 0; i < len(*es.orig); i++ {
 		if f(es.At(i)) {
@@ -112,22 +123,23 @@ func (es {{ .structName }}) RemoveIf(f func({{ .elementName }}) bool) {
 
 // CopyTo copies all elements from the current slice overriding the destination.
 func (es {{ .structName }}) CopyTo(dest {{ .structName }}) {
+	dest.assertMutable()
 	srcLen := es.Len()
 	destCap := cap(*dest.orig)
 	if srcLen <= destCap {
 		(*dest.orig) = (*dest.orig)[:srcLen:destCap]
 
 	{{- if eq .type "sliceOfPtrs" }}
 		for i := range *es.orig {
-			new{{ .elementName }}((*es.orig)[i]).CopyTo(new{{ .elementName }}((*dest.orig)[i]))
+			new{{ .elementName }}((*es.orig)[i], internal.StateExclusive).CopyTo(new{{ .elementName }}((*dest.orig)[i], internal.StateExclusive))
 		}
 		return
 	}
 	origs := make([]{{ .originName }}, srcLen)
 	wrappers := make([]*{{ .originName }}, srcLen)
 	for i := range *es.orig {
 		wrappers[i] = &origs[i]
-		new{{ .elementName }}((*es.orig)[i]).CopyTo(new{{ .elementName }}(wrappers[i]))
+		new{{ .elementName }}((*es.orig)[i], internal.StateExclusive).CopyTo(new{{ .elementName }}(wrappers[i], internal.StateExclusive))
 	}
 	*dest.orig = wrappers
 
@@ -136,7 +148,7 @@ func (es {{ .structName }}) CopyTo(dest {{ .structName }}) {
 		(*dest.orig) = make([]{{ .originElementType }}, srcLen)
 	}
 	for i := range *es.orig {
-		{{ .newElement }}.CopyTo(new{{ .elementName }}(&(*dest.orig)[i]))
+		{{ .newElement }}.CopyTo(new{{ .elementName }}(&(*dest.orig)[i], internal.StateExclusive))
 	}
 	{{- end }}
 }
@@ -146,14 +158,15 @@ func (es {{ .structName }}) CopyTo(dest {{ .structName }}) {
 // provided less function so that two instances of {{ .structName }}
 // can be compared.
 func (es {{ .structName }}) Sort(less func(a, b {{ .elementName }}) bool) {
+	es.assertMutable()
 	sort.SliceStable(*es.orig, func(i, j int) bool { return less(es.At(i), es.At(j)) })
 }
 {{- end }}`
 
 const sliceTestTemplate = `func Test{{ .structName }}(t *testing.T) {
 	es := New{{ .structName }}()
 	assert.Equal(t, 0, es.Len())
-	es = new{{ .structName }}(&[]{{ .originElementType }}{})
+	es = new{{ .structName }}(&[]{{ .originElementType }}{}, internal.StateExclusive)
 	assert.Equal(t, 0, es.Len())
 
 	emptyVal := New{{ .elementName }}()
@@ -324,7 +337,7 @@ func (ss *sliceOfPtrs) templateFields() map[string]any {
 		"originName":         ss.element.originFullName,
 		"originElementType":  "*" + ss.element.originFullName,
 		"emptyOriginElement": "&" + ss.element.originFullName + "{}",
-		"newElement":         "new" + ss.element.structName + "((*es.orig)[i])",
+		"newElement":         "new" + ss.element.structName + "((*es.orig)[i], es.state)",
 	}
 }
 
@@ -376,7 +389,7 @@ func (ss *sliceOfValues) templateFields() map[string]any {
 		"originName":         ss.element.originFullName,
 		"originElementType":  ss.element.originFullName,
 		"emptyOriginElement": ss.element.originFullName + "{}",
-		"newElement":         "new" + ss.element.structName + "(&(*es.orig)[i])",
+		"newElement":         "new" + ss.element.structName + "(&(*es.orig)[i], es.state)",
 	}
 }
 

pdata/internal/cmd/pdatagen/internal/base_structs.go

@@ -21,14 +21,15 @@ type {{ .structName }} internal.{{ .structName }}
 {{- else }}
 type {{ .structName }} struct {
 	orig *{{ .originName }}
+	state internal.State
 }
 {{- end }}
 
-func new{{ .structName }}(orig *{{ .originName }}) {{ .structName }} {
+func new{{ .structName }}(orig *{{ .originName }}, state internal.State) {{ .structName }} {
 	{{- if .isCommon }}
-	return {{ .structName }}(internal.New{{ .structName }}(orig))
+	return {{ .structName }}(internal.New{{ .structName }}(orig, state))
 	{{- else }}
-	return {{ .structName }}{orig}
+	return {{ .structName }}{orig: orig, state: state}
 	{{- end }}
 }
 
@@ -37,12 +38,24 @@ func new{{ .structName }}(orig *{{ .originName }}) {{ .structName }} {
 // This must be used only in testing code. Users should use "AppendEmpty" when part of a Slice,
 // OR directly access the member if this is embedded in another struct.
 func New{{ .structName }}() {{ .structName }} {
-	return new{{ .structName }}(&{{ .originName }}{})
+	return new{{ .structName }}(&{{ .originName }}{}, internal.StateExclusive)
+}
+
+func (ms {{ .structName }}) assertMutable() {
+	{{- if .isCommon }}
+	if internal.Get{{ .structName }}State(internal.{{ .structName }}(ms)) == internal.StateShared {
+	{{- else }}
+	if ms.state == internal.StateShared {
+	{{- end }}
+		panic("invalid access to shared data")
+	}
 }
 
 // MoveTo moves all properties from the current struct overriding the destination and
 // resetting the current instance to its zero value
 func (ms {{ .structName }}) MoveTo(dest {{ .structName }}) {
+	ms.assertMutable()
+	dest.assertMutable()
 	*dest.{{ .origAccessor }} = *ms.{{ .origAccessor }}
 	*ms.{{ .origAccessor }} = {{ .originName }}{}
 }
@@ -59,9 +72,10 @@ func (ms {{ .structName }}) getOrig() *{{ .originName }} {
 
 // CopyTo copies all properties from the current struct overriding the destination.
 func (ms {{ .structName }}) CopyTo(dest {{ .structName }}) {
-{{- range .fields }}
-{{ .GenerateCopyToValue $.messageStruct }}
-{{- end }}
+	dest.assertMutable()
+	{{- range .fields }}
+	{{ .GenerateCopyToValue $.messageStruct }}
+	{{- end }}
 }`
 
 const messageValueTestTemplate = `
@@ -91,7 +105,7 @@ const messageValueGenerateTestTemplate = `func {{ upperIfInternal "g" }}enerateT
 	{{- if .isCommon }}
 	orig := {{ .originName }}{}
 	{{- end }}
-	tv := New{{ .structName }}({{ if .isCommon }}&orig{{ end }})
+	tv := New{{ .structName }}({{ if .isCommon }}&orig, StateExclusive{{ end }})
 	{{ upperIfInternal "f" }}illTest{{ .structName }}(tv)
 	return tv
 }
@@ -105,14 +119,19 @@ func {{ upperIfInternal "f" }}illTest{{ .structName }}(tv {{ .structName }}) {
 const messageValueAliasTemplate = `
 type {{ .structName }} struct {
 	orig *{{ .originName }}
+	state State
 }
 
 func GetOrig{{ .structName }}(ms {{ .structName }}) *{{ .originName }} {
 	return ms.orig
 }
 
-func New{{ .structName }}(orig *{{ .originName }}) {{ .structName }} {
-	return {{ .structName }}{orig: orig}
+func Get{{ .structName }}State(ms {{ .structName }}) State {
+	return ms.state
+}
+
+func New{{ .structName }}(orig *{{ .originName }}, state State) {{ .structName }} {
+	return {{ .structName }}{orig: orig, state: state}
 }`
 
 type baseStruct interface {

pdata/internal/cmd/pdatagen/internal/primitive_slice_structs.go

@@ -23,7 +23,7 @@ func (ms {{ .structName }}) getOrig() *[]{{ .itemType }} {
 // New{{ .structName }} creates a new empty {{ .structName }}.
 func New{{ .structName }}() {{ .structName }} {
 	orig := []{{ .itemType }}(nil)
-	return {{ .structName }}(internal.New{{ .structName }}(&orig))
+	return {{ .structName }}(internal.New{{ .structName }}(&orig, internal.StateExclusive))
 }
 
 // AsRaw returns a copy of the []{{ .itemType }} slice.
@@ -33,6 +33,7 @@ func (ms {{ .structName }}) AsRaw() []{{ .itemType }} {
 
 // FromRaw copies raw []{{ .itemType }} into the slice {{ .structName }}.
 func (ms {{ .structName }}) FromRaw(val []{{ .itemType }}) {
+	internal.{{ .structName }}(ms).AssertState()
 	*ms.getOrig() = copy{{ .structName }}(*ms.getOrig(), val)
 }
 
@@ -51,6 +52,7 @@ func (ms {{ .structName }}) At(i int) {{ .itemType }} {
 // SetAt sets {{ .itemType }} item at particular index.
 // Equivalent of {{ .lowerStructName }}[i] = val
 func (ms {{ .structName }}) SetAt(i int, val {{ .itemType }}) {
+	internal.{{ .structName }}(ms).AssertState()
 	(*ms.getOrig())[i] = val
 }
 
@@ -61,6 +63,7 @@ func (ms {{ .structName }}) SetAt(i int, val {{ .itemType }}) {
 //	copy(buf, {{ .lowerStructName }})
 //	{{ .lowerStructName }} = buf
 func (ms {{ .structName }}) EnsureCapacity(newCap int) {
+	internal.{{ .structName }}(ms).AssertState()
 	oldCap := cap(*ms.getOrig())
 	if newCap <= oldCap {
 		return
@@ -74,18 +77,22 @@ func (ms {{ .structName }}) EnsureCapacity(newCap int) {
 // Append appends extra elements to {{ .structName }}.
 // Equivalent of {{ .lowerStructName }} = append({{ .lowerStructName }}, elms...) 
 func (ms {{ .structName }}) Append(elms ...{{ .itemType }}) {
+	internal.{{ .structName }}(ms).AssertState()
 	*ms.getOrig() = append(*ms.getOrig(), elms...)
 }
 
 // MoveTo moves all elements from the current slice overriding the destination and 
 // resetting the current instance to its zero value.
 func (ms {{ .structName }}) MoveTo(dest {{ .structName }}) {
+	internal.{{ .structName }}(ms).AssertState()
+	internal.{{ .structName }}(dest).AssertState()
 	*dest.getOrig() = *ms.getOrig()
 	*ms.getOrig() = nil
 }
 
 // CopyTo copies all elements from the current slice overriding the destination.
 func (ms {{ .structName }}) CopyTo(dest {{ .structName }}) {
+	internal.{{ .structName }}(dest).AssertState()
 	*dest.getOrig() = copy{{ .structName }}(*dest.getOrig(), *ms.getOrig())
 }
 
@@ -144,14 +151,21 @@ func Test{{ .structName }}EnsureCapacity(t *testing.T) {
 const primitiveSliceInternalTemplate = `
 type {{ .structName }} struct {
 	orig *[]{{ .itemType }}
+	state State
 }
 
 func GetOrig{{ .structName }}(ms {{ .structName }}) *[]{{ .itemType }} {
 	return ms.orig
 }
 
-func New{{ .structName }}(orig *[]{{ .itemType }}) {{ .structName }} {
-	return {{ .structName }}{orig: orig}
+func (ms {{ .structName }}) AssertState() {
+	if ms.state == StateShared {
+		panic("invalid access to shared data")
+	}
+}
+
+func New{{ .structName }}(orig *[]{{ .itemType }}, state State) {{ .structName }} {
+	return {{ .structName }}{orig: orig, state: state}
 }`
 
 // primitiveSliceStruct generates a struct for a slice of primitive value elements. The structs are always generated