[pdata] Deprecate Map.Insert* methods (#6051)

CHANGELOG.md

@@ -38,6 +38,7 @@
   - Deprecate `pcommon.Map.UpsertBytes` in favor of `pcommon.Map.UpsertEmptyBytes`
   - Deprecate `pcommon.Value.SetBytesVal` in favor of `pcommon.Value.SetEmptyBytesVal`
   - Deprecate `pcommon.New[Slice|Map]FromRaw` functions in favor of `New[Slice|Map]().FromRaw` (#6045)
+- Deprecate `pcommon.Map.Insert*` methods (#6051)
 
 ### 💡 Enhancements 💡
 

exporter/exporterhelper/internal/persistent_queue_test.go

@@ -164,9 +164,9 @@ func TestPersistentQueue_ConsumersProducers(t *testing.T) {
 func newTraces(numTraces int, numSpans int) ptrace.Traces {
 	traces := ptrace.NewTraces()
 	batch := traces.ResourceSpans().AppendEmpty()
-	batch.Resource().Attributes().InsertString("resource-attr", "some-resource")
-	batch.Resource().Attributes().InsertInt("num-traces", int64(numTraces))
-	batch.Resource().Attributes().InsertInt("num-spans", int64(numSpans))
+	batch.Resource().Attributes().UpsertString("resource-attr", "some-resource")
+	batch.Resource().Attributes().UpsertInt("num-traces", int64(numTraces))
+	batch.Resource().Attributes().UpsertInt("num-spans", int64(numSpans))
 
 	for i := 0; i < numTraces; i++ {
 		traceID := pcommon.TraceID([16]byte{1, 2, 3, byte(i)})
@@ -176,12 +176,12 @@ func newTraces(numTraces int, numSpans int) ptrace.Traces {
 			span.SetTraceID(traceID)
 			span.SetSpanID([8]byte{1, 2, 3, byte(j)})
 			span.SetName("should-not-be-changed")
-			span.Attributes().InsertInt("int-attribute", int64(j))
-			span.Attributes().InsertString("str-attribute-1", "foobar")
-			span.Attributes().InsertString("str-attribute-2", "fdslafjasdk12312312jkl")
-			span.Attributes().InsertString("str-attribute-3", "AbcDefGeKKjkfdsafasdfsdasdf")
-			span.Attributes().InsertString("str-attribute-4", "xxxxxx")
-			span.Attributes().InsertString("str-attribute-5", "abcdef")
+			span.Attributes().UpsertInt("int-attribute", int64(j))
+			span.Attributes().UpsertString("str-attribute-1", "foobar")
+			span.Attributes().UpsertString("str-attribute-2", "fdslafjasdk12312312jkl")
+			span.Attributes().UpsertString("str-attribute-3", "AbcDefGeKKjkfdsafasdfsdasdf")
+			span.Attributes().UpsertString("str-attribute-4", "xxxxxx")
+			span.Attributes().UpsertString("str-attribute-5", "abcdef")
 		}
 	}
 

internal/testdata/common.go

@@ -25,40 +25,40 @@ const (
 
 func initResourceAttributes1(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString("resource-attr", "resource-attr-val-1")
+	dest.UpsertString("resource-attr", "resource-attr-val-1")
 }
 
 func initSpanEventAttributes(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString("span-event-attr", "span-event-attr-val")
+	dest.UpsertString("span-event-attr", "span-event-attr-val")
 }
 
 func initSpanLinkAttributes(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString("span-link-attr", "span-link-attr-val")
+	dest.UpsertString("span-link-attr", "span-link-attr-val")
 }
 
 func initMetricExemplarAttributes(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString("exemplar-attachment", "exemplar-attachment-value")
+	dest.UpsertString("exemplar-attachment", "exemplar-attachment-value")
 }
 
 func initMetricAttributes1(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString("label-1", "label-value-1")
+	dest.UpsertString("label-1", "label-value-1")
 }
 
 func initMetricAttributes12(dest pcommon.Map) {
 	initMetricAttributes1(dest)
-	dest.InsertString(testLabelKey2, testLabelValue2)
+	dest.UpsertString(testLabelKey2, testLabelValue2)
 }
 
 func initMetricAttributes13(dest pcommon.Map) {
 	initMetricAttributes1(dest)
-	dest.InsertString("label-3", "label-value-3")
+	dest.UpsertString("label-3", "label-value-3")
 }
 
 func initMetricAttributes2(dest pcommon.Map) {
 	dest.Clear()
-	dest.InsertString(testLabelKey2, testLabelValue2)
+	dest.UpsertString(testLabelKey2, testLabelValue2)
 }

internal/testdata/log.go

@@ -50,8 +50,8 @@ func fillLogOne(log plog.LogRecord) {
 	log.SetTraceID([16]byte{0x08, 0x04, 0x02, 0x01})
 
 	attrs := log.Attributes()
-	attrs.InsertString("app", "server")
-	attrs.InsertInt("instance_num", 1)
+	attrs.UpsertString("app", "server")
+	attrs.UpsertInt("instance_num", 1)
 
 	log.Body().SetStringVal("This is a log message")
 }
@@ -63,8 +63,8 @@ func fillLogTwo(log plog.LogRecord) {
 	log.SetSeverityText("Info")
 
 	attrs := log.Attributes()
-	attrs.InsertString("customer", "acme")
-	attrs.InsertString("env", "dev")
+	attrs.UpsertString("customer", "acme")
+	attrs.UpsertString("env", "dev")
 
 	log.Body().SetStringVal("something happened")
 }

pdata/pcommon/common.go

@@ -675,7 +675,7 @@ func (m Map) RemoveIf(f func(string, Value) bool) {
 // Important: this function should not be used if the caller has access to
 // the raw value to avoid an extra allocation.
 //
-// NOTE: The method will be deprecated in 0.60.0. Replace it with the following function calls:
+// Deprecated: [0.60.0] Replace it with the following function calls:
 // For primitive types, use Insert<Type> methods, e.g. InsertString.
 // For complex and unknown types, use:
 //
@@ -691,6 +691,14 @@ func (m Map) Insert(k string, v Value) {
 
 // InsertString adds the string Value to the map when the key does not exist.
 // No action is applied to the map where the key already exists.
+//
+// Deprecated: [0.60.0] Replace it with the following function calls if you need to make sure that existing value is
+// not overridden, otherwise just use UpsertString.
+//
+//	_, ok := m.Get(k)
+//	if !ok {
+//		m.UpsertString(k)
+//	}
 func (m Map) InsertString(k string, v string) {
 	if _, existing := m.Get(k); !existing {
 		*m.getOrig() = append(*m.getOrig(), newAttributeKeyValueString(k, v))
@@ -699,6 +707,14 @@ func (m Map) InsertString(k string, v string) {
 
 // InsertInt adds the int Value to the map when the key does not exist.
 // No action is applied to the map where the key already exists.
+//
+// Deprecated: [0.60.0] Replace it with the following function calls if you need to make sure that existing value is
+// not overridden, otherwise just use UpsertInt.
+//
+//	_, ok := m.Get(k)
+//	if !ok {
+//		m.UpsertInt(k)
+//	}
 func (m Map) InsertInt(k string, v int64) {
 	if _, existing := m.Get(k); !existing {
 		*m.getOrig() = append(*m.getOrig(), newAttributeKeyValueInt(k, v))
@@ -707,6 +723,14 @@ func (m Map) InsertInt(k string, v int64) {
 
 // InsertDouble adds the double Value to the map when the key does not exist.
 // No action is applied to the map where the key already exists.
+//
+// Deprecated: [0.60.0] Replace it with the following function calls if you need to make sure that existing value is
+// not overridden, otherwise just use UpsertDouble.
+//
+//	_, ok := m.Get(k)
+//	if !ok {
+//		m.UpsertDouble(k)
+//	}
 func (m Map) InsertDouble(k string, v float64) {
 	if _, existing := m.Get(k); !existing {
 		*m.getOrig() = append(*m.getOrig(), newAttributeKeyValueDouble(k, v))
@@ -715,6 +739,14 @@ func (m Map) InsertDouble(k string, v float64) {
 
 // InsertBool adds the bool Value to the map when the key does not exist.
 // No action is applied to the map where the key already exists.
+//
+// Deprecated: [0.60.0] Replace it with the following function calls if you need to make sure that existing value is
+// not overridden, otherwise just use UpsertBool.
+//
+//	_, ok := m.Get(k)
+//	if !ok {
+//		m.UpsertBool(k)
+//	}
 func (m Map) InsertBool(k string, v bool) {
 	if _, existing := m.Get(k); !existing {
 		*m.getOrig() = append(*m.getOrig(), newAttributeKeyValueBool(k, v))