[xpdata] Add high-level API for managing entities attached to resources (#14039)

Introduce `Entity`, `EntitySlice`, and `EntityAttributeMap` types that
provide a user-friendly interface for working with resource entities.
The new API ensures consistency between entity and resource attributes
by sharing the underlying attribute map, and prevents attribute
conflicts between entities. This API should eventually replace the
generated protobuf-based API for better usability.

Resolves
#14042

Author: dmitryax

.chloggen/pdata-entity-high-level-api.yaml

@@ -0,0 +1,29 @@
+# Use this changelog template to create an entry for release notes.
+
+# 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/xpdata
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add high-level Entity API for managing entities attached to resources
+
+# One or more tracking issues or pull requests related to the change
+issues: [14042]
+
+# (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: |
+  Introduces `Entity`, `EntitySlice`, and `EntityAttributeMap` types that provide a user-friendly interface
+  for working with resource entities. The new API ensures consistency between entity and resource attributes
+  by sharing the underlying attribute map, and prevents attribute conflicts between entities. This API may
+  eventually replace the generated protobuf-based API for better usability.
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

pdata/xpdata/entity/entity.go

@@ -0,0 +1,45 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package entity // import "go.opentelemetry.io/collector/pdata/xpdata/entity"
+
+import (
+	"go.opentelemetry.io/collector/pdata/pcommon"
+)
+
+// Entity is a helper struct that represents an entity in a more user-friendly way than the underlying
+// EntityRef protobuf message. After adding an entity to a resource, the entity shares the resource's
+// attributes map, so modifications to the entity's attributes are immediately reflected in the resource.
+// To create an Entity, use the EntityMap's PutEmpty method.
+type Entity struct {
+	ref        EntityRef
+	attributes pcommon.Map
+}
+
+func (e Entity) Type() string {
+	return e.ref.Type()
+}
+
+func (e Entity) SchemaURL() string {
+	return e.ref.SchemaUrl()
+}
+
+func (e Entity) SetSchemaURL(schemaURL string) {
+	e.ref.SetSchemaUrl(schemaURL)
+}
+
+// IDAttributes returns an EntityAttributeMap for managing the entity's id attributes.
+func (e Entity) IDAttributes() EntityAttributeMap {
+	return EntityAttributeMap{
+		keys:       e.ref.IdKeys(),
+		attributes: e.attributes,
+	}
+}
+
+// DescriptionAttributes returns an EntityAttributeMap for managing the entity's description attributes.
+func (e Entity) DescriptionAttributes() EntityAttributeMap {
+	return EntityAttributeMap{
+		keys:       e.ref.DescriptionKeys(),
+		attributes: e.attributes,
+	}
+}

pdata/xpdata/entity/entity_attribute_map.go

@@ -0,0 +1,103 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package entity // import "go.opentelemetry.io/collector/pdata/xpdata/entity"
+
+import "go.opentelemetry.io/collector/pdata/pcommon"
+
+// EntityAttributeMap is a wrapper around pcommon.Map that restricts operations to only the keys
+// that belong to a specific set of entity attributes (either ID or Description attributes).
+type EntityAttributeMap struct {
+	keys       pcommon.StringSlice
+	attributes pcommon.Map
+}
+
+// Get returns the Value associated with the key and true. Returned
+// Value is not a copy, it is a reference to the value stored in this map. It is
+// allowed to modify the returned value using Value.Set* functions.
+//
+// If the key does not exist in the entity's key list or in the underlying map,
+// returns an invalid instance and false. Calling any functions on the returned
+// invalid instance will cause a panic.
+func (m EntityAttributeMap) Get(key string) (pcommon.Value, bool) {
+	if !m.containsKey(key) {
+		return pcommon.Value{}, false
+	}
+	return m.attributes.Get(key)
+}
+
+// CanPut returns true if it's safe to call Put methods on the given key.
+// Returns true if:
+//   - The key is already owned by this entity (in the entity's key list), OR
+//   - The key doesn't exist in the shared attributes map (available to claim)
+//
+// Returns false if the key exists in the shared map but belongs to another entity.
+//
+// Use this method before calling Put* methods to avoid conflicts:
+//
+//	if entity.IDAttributes().CanPut("service.name") {
+//	    entity.IDAttributes().PutStr("service.name", "my-service")
+//	}
+func (m EntityAttributeMap) CanPut(key string) bool {
+	if m.containsKey(key) {
+		return true
+	}
+	_, exists := m.attributes.Get(key)
+	return !exists
+}
+
+// PutEmpty inserts or updates an empty value to the map under given key
+// and returns the updated/inserted value.
+// The key is also added to the entity's key list if not already present.
+//
+// WARNING: This method is destructive and will overwrite any existing value in the shared
+// attributes map, even if it belongs to another entity. Use CanPut() to check safety first
+// if you need to avoid conflicts with other entities.
+func (m EntityAttributeMap) PutEmpty(k string) pcommon.Value {
+	if !m.containsKey(k) {
+		m.keys.Append(k)
+	}
+	return m.attributes.PutEmpty(k)
+}
+
+// PutStr performs the Insert or Update action. The Value is
+// inserted to the map that did not originally have the key. The key/value is
+// updated to the map where the key already existed.
+// The key is also added to the entity's key list if not already present.
+//
+// WARNING: This method is destructive and will overwrite any existing value in the shared
+// attributes map, even if it belongs to another entity. Use CanPut() to check safety first
+// if you need to avoid conflicts with other entities.
+func (m EntityAttributeMap) PutStr(k, v string) {
+	if !m.containsKey(k) {
+		m.keys.Append(k)
+	}
+	m.attributes.PutStr(k, v)
+}
+
+// Remove removes the entry associated with the key and returns true if the key existed.
+// The key is also removed from the entity's key list.
+func (m EntityAttributeMap) Remove(key string) bool {
+	var keyFound bool
+	m.keys.RemoveIf(func(k string) bool {
+		if k == key {
+			keyFound = true
+			return true
+		}
+		return false
+	})
+	if !keyFound {
+		return false
+	}
+	m.attributes.Remove(key)
+	return true
+}
+
+func (m EntityAttributeMap) containsKey(key string) bool {
+	for _, k := range m.keys.All() {
+		if k == key {
+			return true
+		}
+	}
+	return false
+}

pdata/xpdata/entity/entity_attribute_map_test.go

@@ -0,0 +1,158 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package entity
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+)
+
+func TestEntityAttributeMap(t *testing.T) {
+	m := newTestEntityAttributeMap()
+
+	val, ok := m.Get("non-existent")
+	assert.False(t, ok)
+	assert.Equal(t, pcommon.Value{}, val)
+
+	m.PutStr("k1", "v1")
+	val, ok = m.Get("k1")
+	assert.True(t, ok)
+	assert.Equal(t, "v1", val.Str())
+
+	assert.True(t, m.Remove("k1"))
+	_, ok = m.Get("k1")
+	assert.False(t, ok)
+
+	assert.False(t, m.Remove("non-existent"))
+}
+
+func TestEntityAttributeMap_Get(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.attributes.PutStr("owned", "value1")
+	m.attributes.PutStr("not-owned", "value2")
+	m.keys.Append("owned")
+
+	val, ok := m.Get("owned")
+	assert.True(t, ok)
+	assert.Equal(t, "value1", val.Str())
+
+	_, ok = m.Get("not-owned")
+	assert.False(t, ok)
+
+	_, ok = m.Get("non-existent")
+	assert.False(t, ok)
+}
+
+func TestEntityAttributeMap_PutStr(t *testing.T) {
+	m := newTestEntityAttributeMap()
+
+	m.PutStr("k1", "v1")
+	assert.Equal(t, 1, m.keys.Len())
+	assert.Equal(t, "k1", m.keys.At(0))
+	val, ok := m.attributes.Get("k1")
+	assert.True(t, ok)
+	assert.Equal(t, "v1", val.Str())
+
+	m.PutStr("k1", "v2")
+	assert.Equal(t, 1, m.keys.Len())
+	val, ok = m.attributes.Get("k1")
+	assert.True(t, ok)
+	assert.Equal(t, "v2", val.Str())
+}
+
+func TestEntityAttributeMap_PutStr_Overwrites(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.attributes.PutStr("existing", "old-value")
+
+	m.PutStr("existing", "new-value")
+
+	assert.Equal(t, 1, m.keys.Len())
+	assert.Equal(t, "existing", m.keys.At(0))
+	val, ok := m.attributes.Get("existing")
+	assert.True(t, ok)
+	assert.Equal(t, "new-value", val.Str())
+}
+
+func TestEntityAttributeMap_PutEmpty(t *testing.T) {
+	m := newTestEntityAttributeMap()
+
+	val := m.PutEmpty("k1")
+	val.SetStr("v1")
+
+	assert.Equal(t, 1, m.keys.Len())
+	assert.Equal(t, "k1", m.keys.At(0))
+	resVal, ok := m.attributes.Get("k1")
+	assert.True(t, ok)
+	assert.Equal(t, "v1", resVal.Str())
+}
+
+func TestEntityAttributeMap_PutEmpty_Overwrites(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.attributes.PutStr("existing", "old-value")
+
+	val := m.PutEmpty("existing")
+	val.SetStr("new-value")
+
+	assert.Equal(t, 1, m.keys.Len())
+	assert.Equal(t, "existing", m.keys.At(0))
+	resVal, ok := m.attributes.Get("existing")
+	assert.True(t, ok)
+	assert.Equal(t, "new-value", resVal.Str())
+}
+
+func TestEntityAttributeMap_Remove(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.keys.Append("k1")
+	m.keys.Append("k2")
+	m.attributes.PutStr("k1", "v1")
+	m.attributes.PutStr("k2", "v2")
+
+	assert.True(t, m.Remove("k1"))
+	assert.Equal(t, 1, m.keys.Len())
+	assert.Equal(t, "k2", m.keys.At(0))
+	_, ok := m.attributes.Get("k1")
+	assert.False(t, ok)
+
+	val, ok := m.attributes.Get("k2")
+	assert.True(t, ok)
+	assert.Equal(t, "v2", val.Str())
+}
+
+func TestEntityAttributeMap_Remove_NotOwned(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.attributes.PutStr("not-owned", "value")
+
+	assert.False(t, m.Remove("not-owned"))
+
+	val, ok := m.attributes.Get("not-owned")
+	assert.True(t, ok)
+	assert.Equal(t, "value", val.Str())
+}
+
+func TestEntityAttributeMap_Remove_NonExistent(t *testing.T) {
+	m := newTestEntityAttributeMap()
+
+	assert.False(t, m.Remove("non-existent"))
+}
+
+func TestEntityAttributeMap_CanPut(t *testing.T) {
+	m := newTestEntityAttributeMap()
+	m.keys.Append("owned")
+	m.attributes.PutStr("owned", "value")
+	m.attributes.PutStr("other", "value")
+
+	assert.True(t, m.CanPut("owned"))
+	assert.False(t, m.CanPut("other"))
+	assert.True(t, m.CanPut("new-key"))
+}
+
+func newTestEntityAttributeMap() EntityAttributeMap {
+	return EntityAttributeMap{
+		keys:       pcommon.NewStringSlice(),
+		attributes: pcommon.NewMap(),
+	}
+}