[pkg/ottl] add event_index to available paths in span event context

.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

@@ -7,26 +7,27 @@ In general, the Span Event Context supports accessing pdata using the field name
 
 The following paths are supported.
 
-| path                                   | field accessed                                                                                                                                                                | type                                                                    |
-|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
-| cache                                  | the value of the current transform context's temporary cache. cache can be used as a temporary placeholder for data during complex transformations                            | pcommon.Map                                                             |
-| cache\[""\]                            | the value of an item in cache. Supports multiple indexes to access nested fields.                                                                                             | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
-| resource                               | resource of the span event being processed                                                                                                                                    | pcommon.Resource                                                        |
-| resource.attributes                    | resource attributes of the span event being processed                                                                                                                         | pcommon.Map                                                             |
-| resource.attributes\[""\]              | the value of the resource attribute of the span event being processed. Supports multiple indexes to access nested fields.                                                     | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
-| instrumentation_scope                  | instrumentation scope of the span event being processed                                                                                                                       | pcommon.InstrumentationScope                                            |
-| instrumentation_scope.name             | name of the instrumentation scope of the span event being processed                                                                                                           | string                                                                  |
-| instrumentation_scope.version          | version of the instrumentation scope of the span event being processed                                                                                                        | string                                                                  |
-| instrumentation_scope.attributes       | instrumentation scope attributes of the span event being processed                                                                                                            | pcommon.Map                                                             |
-| instrumentation_scope.attributes\[""\] | the value of the instrumentation scope attribute of the span event being processed. Supports multiple indexes to access nested fields.                                        | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
-| span                                   | span of the span event being processed                                                                                                                                        | ptrace.Span                                                             |
+| path                                   | field accessed                                                                                                                                                          | type                                                                    |
+|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
+| cache                                  | the value of the current transform context's temporary cache. cache can be used as a temporary placeholder for data during complex transformations                      | pcommon.Map                                                             |
+| cache\[""\]                            | the value of an item in cache. Supports multiple indexes to access nested fields.                                                                                       | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
+| resource                               | resource of the span event being processed                                                                                                                              | pcommon.Resource                                                        |
+| resource.attributes                    | resource attributes of the span event being processed                                                                                                                   | pcommon.Map                                                             |
+| resource.attributes\[""\]              | the value of the resource attribute of the span event being processed. Supports multiple indexes to access nested fields.                                               | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
+| instrumentation_scope                  | instrumentation scope of the span event being processed                                                                                                                 | pcommon.InstrumentationScope                                            |
+| instrumentation_scope.name             | name of the instrumentation scope of the span event being processed                                                                                                     | string                                                                  |
+| instrumentation_scope.version          | version of the instrumentation scope of the span event being processed                                                                                                  | string                                                                  |
+| instrumentation_scope.attributes       | instrumentation scope attributes of the span event being processed                                                                                                      | pcommon.Map                                                             |
+| instrumentation_scope.attributes\[""\] | the value of the instrumentation scope attribute of the span event being processed. Supports multiple indexes to access nested fields.                                  | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
+| span                                   | span of the span event being processed                                                                                                                                  | ptrace.Span                                                             |
 | span.*                                 | All fields exposed by the [ottlspan context](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/ottl/contexts/ottlspan) can accessed via `span.` | varies                                                                  |
-| attributes                             | attributes of the span event being processed                                                                                                                                  | pcommon.Map                                                             |
-| attributes\[""\]                       | the value of the attribute of the span event being processed. Supports multiple indexes to access nested fields.                                                              | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
-| time_unix_nano                         | time_unix_nano of the span event being processed                                                                                                                              | int64                                                                   |
-| time                                   | time of the span event being processed                                                                                                                                        | `time.Time`                                                             |
-| name                                   | name of the span event being processed                                                                                                                                        | string                                                                  |
-| dropped_attributes_count               | dropped_attributes_count of the span event being processed                                                                                                                    | int64                                                                   |
+| attributes                             | attributes of the span event being processed                                                                                                                            | pcommon.Map                                                             |
+| attributes\[""\]                       | the value of the attribute of the span event being processed. Supports multiple indexes to access nested fields.                                                        | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
+| time_unix_nano                         | time_unix_nano of the span event being processed                                                                                                                        | int64                                                                   |
+| time                                   | time of the span event being processed                                                                                                                                  | `time.Time`                                                             |
+| name                                   | name of the span event being processed                                                                                                                                  | string                                                                  |
+| dropped_attributes_count               | dropped_attributes_count of the span event being processed                                                                                                              | int64                                                                   |
+| 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,7 @@ 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)))
+	encoder.AddInt64("eventindex", tCtx.eventIndex)
 	return err
 }
 
@@ -79,6 +81,16 @@ 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) {
+		if eventIndex >= 0 {
+			p.eventIndex = eventIndex
+		}
+	}
+}
+
 func (tCtx TransformContext) GetSpanEvent() ptrace.SpanEvent {
 	return tCtx.spanEvent
 }
@@ -107,6 +119,10 @@ func (tCtx TransformContext) GetResourceSchemaURLItem() internal.SchemaURLItem {
 	return tCtx.resouceSpans
 }
 
+func (tCtx TransformContext) GetEventIndex() int64 {
+	return tCtx.eventIndex
+}
+
 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 +237,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 +366,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.eventIndex, nil
+		},
+		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: &internal.TestPath[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()
@@ -521,7 +535,10 @@ func Test_newPathGetSetter_higherContextPath(t *testing.T) {
 }
 
 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 +579,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")