[pkg/ottl] add event_index to available paths in span event context (#37092)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

This PR adds the `event_index` to the available paths in the span event
context

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #35778

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Unit tests, e2e tests

<!--Describe the documentation added.-->
#### Documentation

added an entry in the list of available paths in the readme of then span
event context

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Signed-off-by: Florian Bacher <[email protected]>
Co-authored-by: Evan Bradley <[email protected]>
Co-authored-by: Tyler Helmuth <[email protected]>
Co-authored-by: Edmo Vamerlatti Costa <[email protected]>

Author: 4 people

.chloggen/ottl-span-event-index.yaml

@@ -0,0 +1,27 @@
+# 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. filelogreceiver)
+component: pkg/ottl
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add `event_index` to the available paths of the span event context
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [35778]
+
+# (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:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# 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: []

pkg/ottl/contexts/ottlspanevent/README.md

@@ -30,6 +30,7 @@ The following paths are supported.
 | spanevent.time                         | time of the span event being processed                                                                                                                                        | `time.Time`                                                             |
 | spanevent.name                         | name of the span event being processed                                                                                                                                        | string                                                                  |
 | spanevent.dropped_attributes_count     | dropped_attributes_count of the span event being processed                                                                                                                    | int64                                                                   |
+| spanevent.event_index                  | index of the span event within the span                                                                                                                                       | int64                                                                   |
 
 ## Enums
 

pkg/ottl/contexts/ottlspanevent/span_events.go

@@ -39,6 +39,7 @@ type TransformContext struct {
 	cache                pcommon.Map
 	scopeSpans           ptrace.ScopeSpans
 	resouceSpans         ptrace.ResourceSpans
+	eventIndex           *int64
 }
 
 func (tCtx TransformContext) MarshalLogObject(encoder zapcore.ObjectEncoder) error {
@@ -47,6 +48,9 @@ func (tCtx TransformContext) MarshalLogObject(encoder zapcore.ObjectEncoder) err
 	err = errors.Join(err, encoder.AddObject("span", logging.Span(tCtx.span)))
 	err = errors.Join(err, encoder.AddObject("spanevent", logging.SpanEvent(tCtx.spanEvent)))
 	err = errors.Join(err, encoder.AddObject("cache", logging.Map(tCtx.cache)))
+	if tCtx.eventIndex != nil {
+		encoder.AddInt64("event_index", *tCtx.eventIndex)
+	}
 	return err
 }
 
@@ -79,6 +83,14 @@ func WithCache(cache *pcommon.Map) TransformContextOption {
 	}
 }
 
+// WithEventIndex sets the index of the SpanEvent within the span, to make it accessible via the event_index property of its context.
+// The index must be greater than or equal to zero, otherwise the given val will not be applied.
+func WithEventIndex(eventIndex int64) TransformContextOption {
+	return func(p *TransformContext) {
+		p.eventIndex = &eventIndex
+	}
+}
+
 func (tCtx TransformContext) GetSpanEvent() ptrace.SpanEvent {
 	return tCtx.spanEvent
 }
@@ -107,6 +119,16 @@ func (tCtx TransformContext) GetResourceSchemaURLItem() internal.SchemaURLItem {
 	return tCtx.resouceSpans
 }
 
+func (tCtx TransformContext) GetEventIndex() (int64, error) {
+	if tCtx.eventIndex != nil {
+		if *tCtx.eventIndex < 0 {
+			return 0, errors.New("found invalid value for 'event_index'")
+		}
+		return *tCtx.eventIndex, nil
+	}
+	return 0, errors.New("no 'event_index' property has been set")
+}
+
 func NewParser(functions map[string]ottl.Factory[TransformContext], telemetrySettings component.TelemetrySettings, options ...Option) (ottl.Parser[TransformContext], error) {
 	pep := pathExpressionParser{telemetrySettings}
 	p, err := ottl.NewParser[TransformContext](
@@ -221,6 +243,8 @@ func (pep *pathExpressionParser) parsePath(path ottl.Path[TransformContext]) (ot
 		return accessSpanEventAttributesKey(path.Keys()), nil
 	case "dropped_attributes_count":
 		return accessSpanEventDroppedAttributeCount(), nil
+	case "event_index":
+		return accessSpanEventIndex(), nil
 	default:
 		return nil, internal.FormatDefaultErrorMessage(path.Name(), path.String(), contextNameDescription, internal.SpanEventRef)
 	}
@@ -348,3 +372,14 @@ func accessSpanEventDroppedAttributeCount() ottl.StandardGetSetter[TransformCont
 		},
 	}
 }
+
+func accessSpanEventIndex() ottl.StandardGetSetter[TransformContext] {
+	return ottl.StandardGetSetter[TransformContext]{
+		Getter: func(_ context.Context, tCtx TransformContext) (any, error) {
+			return tCtx.GetEventIndex()
+		},
+		Setter: func(_ context.Context, _ TransformContext, _ any) error {
+			return errors.New("the 'event_index' path cannot be modified")
+		},
+	}
+}

pkg/ottl/contexts/ottlspanevent/span_events_test.go

@@ -49,11 +49,12 @@ func Test_newPathGetSetter(t *testing.T) {
 	newMap["k2"] = newMap2
 
 	tests := []struct {
-		name     string
-		path     ottl.Path[TransformContext]
-		orig     any
-		newVal   any
-		modified func(spanEvent ptrace.SpanEvent, span ptrace.Span, il pcommon.InstrumentationScope, resource pcommon.Resource, cache pcommon.Map)
+		name              string
+		path              ottl.Path[TransformContext]
+		orig              any
+		newVal            any
+		expectSetterError bool
+		modified          func(spanEvent ptrace.SpanEvent, span ptrace.Span, il pcommon.InstrumentationScope, resource pcommon.Resource, cache pcommon.Map)
 	}{
 		{
 			name: "span event time",
@@ -407,6 +408,15 @@ func Test_newPathGetSetter(t *testing.T) {
 				spanEvent.SetDroppedAttributesCount(20)
 			},
 		},
+		{
+			name: "event_index",
+			path: &pathtest.Path[TransformContext]{
+				N: "event_index",
+			},
+			orig:              int64(1),
+			newVal:            int64(1),
+			expectSetterError: true,
+		},
 	}
 	// Copy all tests cases and sets the path.Context value to the generated ones.
 	// It ensures all exiting field access also work when the path context is set.
@@ -426,13 +436,17 @@ func Test_newPathGetSetter(t *testing.T) {
 
 			spanEvent, span, il, resource := createTelemetry()
 
-			tCtx := NewTransformContext(spanEvent, span, il, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans())
+			tCtx := NewTransformContext(spanEvent, span, il, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans(), WithEventIndex(1))
 
 			got, err := accessor.Get(context.Background(), tCtx)
 			assert.NoError(t, err)
 			assert.Equal(t, tt.orig, got)
 
 			err = accessor.Set(context.Background(), tCtx, tt.newVal)
+			if tt.expectSetterError {
+				assert.Error(t, err)
+				return
+			}
 			assert.NoError(t, err)
 
 			exSpanEvent, exSpan, exIl, exRes := createTelemetry()
@@ -520,8 +534,67 @@ func Test_newPathGetSetter_higherContextPath(t *testing.T) {
 	}
 }
 
+func Test_setAndGetEventIndex(t *testing.T) {
+	tests := []struct {
+		name             string
+		setEventIndex    bool
+		eventIndexValue  int64
+		expected         any
+		expectedErrorMsg string
+	}{
+		{
+			name:            "event index set",
+			setEventIndex:   true,
+			eventIndexValue: 1,
+			expected:        int64(1),
+		},
+		{
+			name:             "invalid value for event index",
+			setEventIndex:    true,
+			eventIndexValue:  -1,
+			expectedErrorMsg: "found invalid value for 'event_index'",
+		},
+		{
+			name:             "no value for event index",
+			setEventIndex:    false,
+			expectedErrorMsg: "no 'event_index' property has been set",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			spanEvent, span, il, resource := createTelemetry()
+
+			var tCtx TransformContext
+			if tt.setEventIndex {
+				tCtx = NewTransformContext(spanEvent, span, il, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans(), WithEventIndex(tt.eventIndexValue))
+			} else {
+				tCtx = NewTransformContext(spanEvent, span, il, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans())
+			}
+
+			pep := pathExpressionParser{}
+			accessor, err := pep.parsePath(&pathtest.Path[TransformContext]{
+				N: "event_index",
+			})
+			assert.NoError(t, err)
+
+			got, err := accessor.Get(context.Background(), tCtx)
+			if tt.expectedErrorMsg != "" {
+				assert.Error(t, err)
+				assert.ErrorContains(t, err, tt.expectedErrorMsg)
+				return
+			}
+			assert.NoError(t, err)
+			assert.Equal(t, tt.expected, got)
+		})
+	}
+}
+
 func createTelemetry() (ptrace.SpanEvent, ptrace.Span, pcommon.InstrumentationScope, pcommon.Resource) {
-	spanEvent := ptrace.NewSpanEvent()
+	span := ptrace.NewSpan()
+	span.SetName("test")
+
+	spanEvent := span.Events().AppendEmpty()
 
 	spanEvent.SetName("bear")
 	spanEvent.SetTimestamp(pcommon.NewTimestampFromTime(time.UnixMilli(100)))
@@ -562,9 +635,6 @@ func createTelemetry() (ptrace.SpanEvent, ptrace.Span, pcommon.InstrumentationSc
 	s := spanEvent.Attributes().PutEmptySlice("slice")
 	s.AppendEmpty().SetEmptyMap().PutStr("map", "pass")
 
-	span := ptrace.NewSpan()
-	span.SetName("test")
-
 	il := pcommon.NewInstrumentationScope()
 	il.SetName("library")
 	il.SetVersion("version")

pkg/ottl/e2e/e2e_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottllog"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottlspan"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottlspanevent"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/ottlfuncs"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatatest/plogtest"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatatest/ptracetest"
@@ -1316,6 +1317,40 @@ func Test_ProcessTraces_TraceContext(t *testing.T) {
 	}
 }
 
+func Test_ProcessSpanEvents(t *testing.T) {
+	tests := []struct {
+		statement string
+		want      func(_ ottlspanevent.TransformContext)
+	}{
+		{
+			statement: `set(attributes["index"], event_index)`,
+			want: func(tCtx ottlspanevent.TransformContext) {
+				tCtx.GetSpanEvent().Attributes().PutInt("index", 0)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.statement, func(t *testing.T) {
+			settings := componenttest.NewNopTelemetrySettings()
+			funcs := ottlfuncs.StandardFuncs[ottlspanevent.TransformContext]()
+
+			spanEventParser, err := ottlspanevent.NewParser(funcs, settings)
+			assert.NoError(t, err)
+			spanStatements, err := spanEventParser.ParseStatement(tt.statement)
+			assert.NoError(t, err)
+
+			tCtx := constructSpanEventTransformContext()
+			_, _, _ = spanStatements.Execute(context.Background(), tCtx)
+
+			exTCtx := constructSpanEventTransformContext()
+			tt.want(exTCtx)
+
+			assert.NoError(t, ptracetest.CompareSpanEvent(newSpanEvent(exTCtx), newSpanEvent(tCtx)))
+		})
+	}
+}
+
 func parseStatementWithAndWithoutPathContext(statement string) ([]*ottl.Statement[ottllog.TransformContext], error) {
 	settings := componenttest.NewNopTelemetrySettings()
 	parserWithoutPathCtx, err := ottllog.NewParser(ottlfuncs.StandardFuncs[ottllog.TransformContext](), settings)
@@ -1457,6 +1492,21 @@ func constructSpanTransformContext() ottlspan.TransformContext {
 	return ottlspan.NewTransformContext(td, scope, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans())
 }
 
+func constructSpanEventTransformContext() ottlspanevent.TransformContext {
+	resource := pcommon.NewResource()
+
+	scope := pcommon.NewInstrumentationScope()
+	scope.SetName("scope")
+
+	span := ptrace.NewSpan()
+	fillSpanOne(span)
+
+	ev1 := span.Events().AppendEmpty()
+	ev1.SetName("event-1")
+
+	return ottlspanevent.NewTransformContext(ev1, span, scope, resource, ptrace.NewScopeSpans(), ptrace.NewResourceSpans(), ottlspanevent.WithEventIndex(0))
+}
+
 func newResourceLogs(tCtx ottllog.TransformContext) plog.ResourceLogs {
 	rl := plog.NewResourceLogs()
 	tCtx.GetResource().CopyTo(rl.Resource())
@@ -1477,6 +1527,12 @@ func newResourceSpans(tCtx ottlspan.TransformContext) ptrace.ResourceSpans {
 	return rl
 }
 
+func newSpanEvent(tCtx ottlspanevent.TransformContext) ptrace.SpanEvent {
+	dst := ptrace.NewSpanEvent()
+	tCtx.GetSpanEvent().CopyTo(dst)
+	return dst
+}
+
 func fillSpanOne(span ptrace.Span) {
 	span.SetName("operationB")
 	span.SetSpanID(spanID)