Converting Lambda Telemetry API Event objects to OpenTelemetry Spans - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Converting Lambda Telemetry API Event objects to OpenTelemetry Spans

The Amazon Lambda Telemetry API schema is semantically compatible with OpenTelemetry (OTel). This means that you can convert your Amazon Lambda Telemetry API Event objects to OpenTelemetry (OTel) Spans. When converting, you shouldn't map a single Event object to a single OTel Span. Instead, you should present all three events related to a lifecycle phase in a single OTel Span. For example, the start, runtimeDone, and runtimeReport events represent a single function invocation. Present all three of these events as a single OTel Span.

You can convert your events using Span Events or Child (nested) Spans. The tables on this page describe the mappings between Telemetry API schema properties and OTel Span properties for both approaches. For more information about OTel Spans, see Span on the Tracing API page of the OpenTelemetry Docs website.

Map to OTel Spans with Span Events

In the following tables, e represents the event coming from the telemetry source.

Mapping the *Start events
OpenTelemetry Lambda Telemetry API schema

Span.Name

Your extension generates this value based on the type field.

Span.StartTime

Use e.time.

Span.EndTime

N/A, because the event hasn't completed yet.

Span.Kind

Set to Server.

Span.Status

Set to Unset.

Span.TraceId

Parse the Amazon X-Ray header found in e.tracing.value, then use the TraceId value.

Span.ParentId

Parse the X-Ray header found in e.tracing.value, then use the Parent value.

Span.SpanId

Use e.tracing.spanId if available. Otherwise, generate a new SpanId.

Span.SpanContext.TraceState

N/A for an X-Ray trace context.

Span.SpanContext.TraceFlags

Parse the X-Ray header found in e.tracing.value, then use the Sampled value.

Span.Attributes

Your extension can add any custom values here.

Mapping the *RuntimeDone events
OpenTelemetry Lambda Telemetry API schema

Span.Name

Your extension generates the value based on the type field.

Span.StartTime

Use e.time from the matching *Start event.

Alternatively, use e.time - e.metrics.durationMs.

Span.EndTime

N/A, because the event hasn't completed yet.

Span.Kind

Set to Server.

Span.Status

If e.status doesn't equal success, then set to Error.

Otherwise, set to Ok.

Span.Events[]

Use e.spans[].

Span.Events[i].Name

Use e.spans[i].name.

Span.Events[i].Time

Use e.spans[i].start.

Span.TraceId

Parse the Amazon X-Ray header found in e.tracing.value, then use the TraceId value.

Span.ParentId

Parse the X-Ray header found in e.tracing.value, then use the Parent value.

Span.SpanId

Use the same SpanId from the *Start event. If unavailable, then use e.tracing.spanId, or generate a new SpanId.

Span.SpanContext.TraceState

N/A for an X-Ray trace context.

Span.SpanContext.TraceFlags

Parse the X-Ray header found in e.tracing.value, then use the Sampled value.

Span.Attributes

Your extension can add any custom values here.

Mapping the *Report events
OpenTelemetry Lambda Telemetry API schema

Span.Name

Your extension generates the value based on the type field.

Span.StartTime

Use e.time from the matching *Start event.

Alternatively, use e.time - e.metrics.durationMs.

Span.EndTime

Use e.time.

Span.Kind

Set to Server.

Span.Status

Use the same value as the *RuntimeDone event.

Span.TraceId

Parse the Amazon X-Ray header found in e.tracing.value, then use the TraceId value.

Span.ParentId

Parse the X-Ray header found in e.tracing.value, then use the Parent value.

Span.SpanId

Use the same SpanId from the *Start event. If unavailable, then use e.tracing.spanId, or generate a new SpanId.

Span.SpanContext.TraceState

N/A for an X-Ray trace context.

Span.SpanContext.TraceFlags

Parse the X-Ray header found in e.tracing.value, then use the Sampled value.

Span.Attributes

Your extension can add any custom values here.

Map to OTel Spans with Child Spans

The following table describes how to convert Lambda Telemetry API events into OTel Spans with Child (nested) Spans for *RuntimeDone Spans. For *Start and *Report mappings, refer to the tables in Map to OTel Spans with Span Events, as they're the same for Child Spans. In this table, e represents the event coming from the telemetry source.

Mapping the *RuntimeDone events
OpenTelemetry Lambda Telemetry API schema

Span.Name

Your extension generates the value based on the type field.

Span.StartTime

Use e.time from the matching *Start event.

Alternatively, use e.time - e.metrics.durationMs.

Span.EndTime

N/A, because the event hasn't completed yet.

Span.Kind

Set to Server.

Span.Status

If e.status doesn't equal success, then set to Error.

Otherwise, set to Ok.

Span.TraceId

Parse the Amazon X-Ray header found in e.tracing.value, then use the TraceId value.

Span.ParentId

Parse the X-Ray header found in e.tracing.value, then use the Parent value.

Span.SpanId

Use the same SpanId from the *Start event. If unavailable, then use e.tracing.spanId, or generate a new SpanId.

Span.SpanContext.TraceState

N/A for an X-Ray trace context.

Span.SpanContext.TraceFlags

Parse the X-Ray header found in e.tracing.value, then use the Sampled value.

Span.Attributes

Your extension can add any custom values here.

ChildSpan[i].Name

Use e.spans[i].name.

ChildSpan[i].StartTime

Use e.spans[i].start.

ChildSpan[i].EndTime

Use e.spans[i].start + e.spans[i].durations.

ChildSpan[i].Kind

Same as parent Span.Kind.

ChildSpan[i].Status

Same as parent Span.Status.

ChildSpan[i].TraceId

Same as parent Span.TraceId.

ChildSpan[i].ParentId

Use parent Span.SpanId.

ChildSpan[i].SpanId

Generate a new SpanId.

ChildSpan[i].SpanContext.TraceState

N/A for an X-Ray trace context.

ChildSpan[i].SpanContext.TraceFlags

Same as parent Span.SpanContext.TraceFlags.