Introduce experimental entity event data types

.chloggen/introduce-entity-events-as-logs.yaml

@@ -0,0 +1,20 @@
+# Use this changelog template to create an entry for release notes.
+# If your change doesn't affect end users, such as a test fix or a tooling change,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+
+# 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. filelogreceiver)
+component: experimentalmetricmetadata
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Introduce experimental entity event data types
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [23565]
+
+# (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:

pkg/experimentalmetricmetadata/entity_events.go

@@ -0,0 +1,151 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package experimentalmetricmetadata // import "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/experimentalmetricmetadata"
+
+import (
+	"go.opentelemetry.io/collector/pdata/pcommon"
+	"go.opentelemetry.io/collector/pdata/plog"
+)
+
+// See entity event design document:
+// https://docs.google.com/document/d/1Tg18sIck3Nakxtd3TFFcIjrmRO_0GLMdHXylVqBQmJA/edit#heading=h.pokdp8i2dmxy
+
+const (
+	semconvOtelEntityEventName    = "otel.entity.event.type"
+	semconvEventEntityEventState  = "entity_state"
+	semconvEventEntityEventDelete = "entity_delete"
+
+	semconvOtelEntityID         = "otel.entity.id"
+	semconvOtelEntityType       = "otel.entity.type"
+	semconvOtelEntityAttributes = "otel.entity.attributes"
+)
+
+// EntityEventsSlice is a slice of EntityEvent.
+type EntityEventsSlice struct {
+	orig plog.LogRecordSlice
+}
+
+// NewEntityEventsSlice creates an empty EntityEventsSlice.
+func NewEntityEventsSlice() EntityEventsSlice {
+	return EntityEventsSlice{orig: plog.NewLogRecordSlice()}
+}
+
+// AppendEmpty will append to the end of the slice an empty EntityEvent.
+// It returns the newly added EntityEvent.
+func (s EntityEventsSlice) AppendEmpty() EntityEvent {
+	return EntityEvent{orig: s.orig.AppendEmpty()}
+}
+
+// Len returns the number of elements in the slice.
+func (s EntityEventsSlice) Len() int {
+	return s.orig.Len()
+}
+
+// EnsureCapacity is an operation that ensures the slice has at least the specified capacity.
+func (s EntityEventsSlice) EnsureCapacity(newCap int) {
+	s.orig.EnsureCapacity(newCap)
+}
+
+// At returns the element at the given index.
+func (s EntityEventsSlice) At(i int) EntityEvent {
+	return EntityEvent{orig: s.orig.At(i)}
+}
+
+// EntityEvent is an entity event.
+type EntityEvent struct {
+	orig plog.LogRecord
+}
+
+// ID of the entity.
+func (e EntityEvent) ID() pcommon.Map {
+	m, ok := e.orig.Attributes().Get(semconvOtelEntityID)
+	if !ok {
+		return e.orig.Attributes().PutEmptyMap(semconvOtelEntityID)
+	}
+	return m.Map()
+}
+
+// SetEntityState makes this an EntityStateDetails event.
+func (e EntityEvent) SetEntityState() EntityStateDetails {
+	e.orig.Attributes().PutStr(semconvOtelEntityEventName, semconvEventEntityEventState)
+	return e.EntityStateDetails()
+}
+
+// EntityStateDetails returns the entity state details of this event.
+func (e EntityEvent) EntityStateDetails() EntityStateDetails {
+	return EntityStateDetails(e)
+}
+
+// SetEntityDelete makes this an EntityDeleteDetails event.
+func (e EntityEvent) SetEntityDelete() EntityDeleteDetails {
+	e.orig.Attributes().PutStr(semconvOtelEntityEventName, semconvEventEntityEventDelete)
+	return e.EntityDeleteDetails()
+}
+
+// EntityDeleteDetails return the entity delete details of this event.
+func (e EntityEvent) EntityDeleteDetails() EntityDeleteDetails {
+	return EntityDeleteDetails(e)
+}
+
+// EventType is the type of the entity event.
+type EventType int
+
+const (
+	// EventTypeNone indicates an invalid or unknown event type.
+	EventTypeNone EventType = iota
+	// EventTypeState is the "entity state" event.
+	EventTypeState
+	// EventTypeDelete is the "entity delete" event.
+	EventTypeDelete
+)
+
+// EventType returns the type of the event.
+func (e EntityEvent) EventType() EventType {
+	eventType, ok := e.orig.Attributes().Get(semconvOtelEntityEventName)
+	if !ok {
+		return EventTypeNone
+	}
+
+	switch eventType.Str() {
+	case semconvEventEntityEventState:
+		return EventTypeState
+	case semconvEventEntityEventDelete:
+		return EventTypeDelete
+	default:
+		return EventTypeNone
+	}
+}
+
+// EntityStateDetails represents the details of an EntityState event.
+type EntityStateDetails struct {
+	orig plog.LogRecord
+}
+
+// Attributes returns the attributes of the entity.
+func (s EntityStateDetails) Attributes() pcommon.Map {
+	m, ok := s.orig.Attributes().Get(semconvOtelEntityAttributes)
+	if !ok {
+		return s.orig.Attributes().PutEmptyMap(semconvOtelEntityAttributes)
+	}
+	return m.Map()
+}
+
+// EntityType returns the type of the entity.
+func (s EntityStateDetails) EntityType() string {
+	t, ok := s.orig.Attributes().Get(semconvOtelEntityType)
+	if !ok {
+		return ""
+	}
+	return t.Str()
+}
+
+// SetEntityType sets the type of the entity.
+func (s EntityStateDetails) SetEntityType(t string) {
+	s.orig.Attributes().PutStr(semconvOtelEntityType, t)
+}
+
+// EntityDeleteDetails represents the details of an EntityDelete event.
+type EntityDeleteDetails struct {
+	orig plog.LogRecord
+}

pkg/experimentalmetricmetadata/entity_events_test.go

@@ -0,0 +1,74 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package experimentalmetricmetadata
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"go.opentelemetry.io/collector/pdata/plog"
+)
+
+func Test_Entity_State(t *testing.T) {
+	slice := NewEntityEventsSlice()
+	event := slice.AppendEmpty()
+
+	event.ID().PutStr("k8s.pod.uid", "123")
+	state := event.SetEntityState()
+	state.SetEntityType("k8s.pod")
+	state.Attributes().PutStr("label1", "value1")
+
+	actual := slice.At(0)
+
+	assert.Equal(t, EventTypeState, actual.EventType())
+
+	v, ok := actual.ID().Get("k8s.pod.uid")
+	assert.True(t, ok)
+	assert.Equal(t, "123", v.Str())
+
+	v, ok = actual.EntityStateDetails().Attributes().Get("label1")
+	assert.True(t, ok)
+	assert.Equal(t, "value1", v.Str())
+
+	assert.Equal(t, "k8s.pod", actual.EntityStateDetails().EntityType())
+}
+
+func Test_Entity_Delete(t *testing.T) {
+	slice := NewEntityEventsSlice()
+
+	event := slice.AppendEmpty()
+	event.ID().PutStr("k8s.node.uid", "abc")
+	event.SetEntityDelete()
+
+	actual := slice.At(0)
+
+	assert.Equal(t, EventTypeDelete, actual.EventType())
+	v, ok := actual.ID().Get("k8s.node.uid")
+	assert.True(t, ok)
+	assert.Equal(t, "abc", v.Str())
+}
+
+func Test_EntityEventsSlice(t *testing.T) {
+	slice := NewEntityEventsSlice()
+	slice.AppendEmpty()
+	assert.Equal(t, 1, slice.Len())
+
+	slice.EnsureCapacity(10)
+	assert.Equal(t, 1, slice.Len())
+}
+
+func Test_EntityEventType(t *testing.T) {
+	lr := plog.NewLogRecord()
+	e := EntityEvent{lr}
+	assert.Equal(t, EventTypeNone, e.EventType())
+
+	lr.Attributes().PutStr(semconvOtelEntityEventName, "invalidtype")
+	assert.Equal(t, EventTypeNone, e.EventType())
+}
+
+func Test_EntityTypeEmpty(t *testing.T) {
+	lr := plog.NewLogRecord()
+	e := EntityStateDetails{lr}
+	assert.Equal(t, "", e.EntityType())
+}

pkg/experimentalmetricmetadata/go.mod

@@ -2,13 +2,27 @@ module github.com/open-telemetry/opentelemetry-collector-contrib/pkg/experimenta
 
 go 1.19
 
-require github.com/stretchr/testify v1.8.4
+require (
+	github.com/stretchr/testify v1.8.4
+	go.opentelemetry.io/collector/pdata v1.0.0-rcv0013
+)
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/kr/text v0.2.0 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/net v0.11.0 // indirect
+	golang.org/x/sys v0.9.0 // indirect
+	golang.org/x/text v0.10.0 // indirect
+	google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1 // indirect
+	google.golang.org/grpc v1.56.0 // indirect
+	google.golang.org/protobuf v1.30.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )