Converting Lambda Telemetry API Event objects to OpenTelemetry Spans

The AWS Lambda Telemetry API schema is semantically compatible with OpenTelemetry (OTel). This means that you can convert your AWS 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 AWS 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 AWS 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 AWS 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 AWS 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.