OpenTelemetry.Instrumentation.AWSLambda 1.21.0

AWS OTel .NET SDK for Lambda

Status
Stability Stable
Code Owners @rypdal, @Oberon00, @normj

NuGet version badge NuGet download count badge codecov.io

This repo contains SDK to instrument Lambda handler to create incoming span.

Installation

dotnet add package OpenTelemetry.Instrumentation.AWSLambda

Configuration

Add AddAWSLambdaConfigurations() to TracerProvider.

TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
        // add other instrumentations
        .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true)
        .Build();

AWSLambdaInstrumentationOptions

AWSLambdaInstrumentationOptions contains various properties to configure AWS lambda instrumentation:

Enriching the invocation span

faas.trigger is set to http for API Gateway and Application Load Balancer requests and to pubsub for SQS and SNS events. Other event sources report other.

EnrichWithInput lets a function describe its own trigger. The action receives the invocation Activity, the function input and the ILambdaContext, and runs after the activity is created. For example, for an S3 triggered function:

using System.Net;
using Amazon.Lambda.S3Events;

TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAWSLambdaConfigurations(options => options.EnrichWithInput = (activity, input, context) =>
    {
        // S3 sends one event entry per notification.
        if (input is S3Event { Records.Count: 1 } s3Event)
        {
            var record = s3Event.Records[0];

            activity.SetTag("faas.trigger", "datasource");
            activity.SetTag("faas.document.collection", record.S3.Bucket.Name);
            activity.SetTag("faas.document.operation", "insert");

            // S3 URL encodes the object key in the notification.
            activity.SetTag("faas.document.name", WebUtility.UrlDecode(record.S3.Object.Key));
            activity.SetTag("faas.document.time", record.EventTime.ToUniversalTime().ToString("o"));
        }

        activity.SetTag("aws.lambda.log_stream", context.LogStreamName);
    })
    .Build();

Note

The action runs after the activity is created, so attributes it sets are not visible to samplers.

Query string redaction

For HTTP triggered functions the request query string is supplied by the caller and may contain sensitive data. By default the query string values recorded in the url.query and http.target span attributes are redacted (replaced with Redacted), as specified by the Semantic conventions for HTTP spans. To record the raw query string values instead, set the environment variable OTEL_DOTNET_EXPERIMENTAL_AWS_LAMBDA_DISABLE_URL_QUERY_REDACTION to true.

Instrumentation

AWSLambdaWrapper contains tracing methods covering different types of function handler method signatures. AWSLambdaWrapper.Trace() and AWSLambdaWrapper.TraceAsync() are used for wrapping synchronous and asynchronous function handlers respectively. The ActivityContext parentContext parameter is optional and used to pass a custom parent context. If the parent is not passed explicitly then it's either extracted from the input parameter or uses AWS X-Ray headers if AWS X-Ray context extraction is enabled (see configuration property DisableAwsXRayContextExtraction).

Note

If tracing is required when AWS X-Ray is disabled, the DisableAwsXRayContextExtraction property needs to be set to true. This will instruct the instrumentation to ignore the "not sampled" trace header automatically sent when AWS X-Ray is disabled.

The sequence of the parent extraction: explicit parent -> parent from input parameter -> AWS X-Ray headers -> default The parent extraction is supported for the input types listed in the table below:

Type Parent extraction source
APIGatewayProxyRequest, APIGatewayHttpApiV2ProxyRequest, ApplicationLoadBalancerRequest HTTP headers of the request
SQSEvent Attributes of the last SQSMessage (if SetParentFromMessageBatch is true)
SNSEvent Attributes of the last SNSRecord

Lambda Function

  1. Create a wrapper function with the same signature as the original Lambda function but an added ILambdaContext parameter if it was not already present. Call AWSLambdaWrapper.Trace() or AWSLambdaWrapper.TraceAsync() API and pass TracerProvider, original Lambda function and its parameters.

  2. Set the wrapper function as the Lambda handler input.

// new Lambda function handler passed in
public string TracingFunctionHandler(JObject input, ILambdaContext context)
=> AWSLambdaWrapper.Trace(tracerProvider, OriginalFunctionHandler, input, context);

public string OriginalFunctionHandler(JObject input, ILambdaContext context)
{
    var S3Client = new AmazonS3Client();
    var httpClient = new HttpClient();
    _ = S3Client.ListBucketsAsync().Result;
    _ = httpClient.GetAsync("https://aws.amazon.com").Result;
    return input?.ToString();
}

Lambda Function - Asp.Net Core

For using base classes from package Amazon.Lambda.AspNetCoreServer, override the FunctionHandlerAsync function in LambdaEntryPoint.cs file. Call AWSLambdaWrapper.TraceAsync() API and pass TracerProvider, original Lambda function and its inputs as parameters. Below is an example if using APIGatewayProxyFunction as base class.

public override async Task<APIGatewayProxyResponse> FunctionHandlerAsync(
    APIGatewayProxyRequest request, ILambdaContext lambdaContext)
=> await AWSLambdaWrapper.TraceAsync(tracerProvider, base.FunctionHandlerAsync,
    request, lambdaContext);

Example

A more detailed Lambda function example that takes a JObject and ILambdaContext as inputs.

public class Function
{
    public static TracerProvider tracerProvider;

    static Function()
    {
        tracerProvider = Sdk.CreateTracerProviderBuilder()
                .AddHttpClientInstrumentation()
                .AddAWSInstrumentation()
                .AddOtlpExporter()
                .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true)
                .Build();
    }

    public string TracingFunctionHandler(JObject input, ILambdaContext context)
    => AWSLambdaWrapper.Trace(tracerProvider, FunctionHandler, input, context);

    /// <summary>
    /// A simple function that takes a JObject input and sends downstream http
    /// request to aws.amazon.com and aws request to S3.
    /// </summary>
    public string FunctionHandler(JObject input, ILambdaContext context)
    {
        var S3Client = new AmazonS3Client();
        var httpClient = new HttpClient();
        _ = S3Client.ListBucketsAsync().Result;
        _ = httpClient.GetAsync("https://aws.amazon.com").Result;
        return input?.ToString();
    }
}

Semantic Conventions

For an overview on Semantic Conventions, see Open Telemetry - Semantic Conventions.

While this library is intended for production use, it relies on several Semantic Conventions that are still considered Experimental, meaning they may undergo additional changes before becoming Stable. This can impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.

For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit "http.method" with a value of GET, while a different microservice, using a new version of Semantic Convention may instead emit the GET as "http.request.method".

Future versions of OpenTelemetry.Instrumentation.AWSLambda library will include updates to the Semantic Convention, which may break compatibility with a previous version.

The default will remain as V1_28_0 until the next major version bump.

To opt in to automatic upgrades, you can use SemanticConventionVersion.Latest or you can specify a specific version:

 using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAWSLambdaConfigurations(opt =>
    {
        // pin to a specific Semantic Convention version
        opt.SemanticConventionVersion = SemanticConventionVersion.V1_29_0;
    })
    .Build()!);

NOTE: Once a Semantic Convention becomes Stable, OpenTelemetry.Instrumentation.AWSLambda will remain on that version until the next major version bump.

Reference

No packages depend on OpenTelemetry.Instrumentation.AWSLambda.

Version Downloads Last updated
1.21.0 1 11/18/2026
1.20.3 1 11/17/2026
1.20.2 1 11/05/2026
1.20.1 3 10/24/2026
1.20.0 3 10/26/2026
1.19.1 7 09/23/2026
1.19.0 6 09/26/2026
1.18.0 5 08/26/2026
1.17.0 11 07/25/2026
1.16.0 5 06/23/2026
1.15.1 10 06/23/2026
1.15.0 14 06/23/2026
1.14.2 7 06/23/2026
1.14.1 9 06/20/2026
1.14.0 10 06/23/2026
1.13.0 9 06/20/2026
1.12.1 11 06/20/2026
1.12.0 8 06/23/2026
1.11.3 7 06/23/2026
1.11.2 9 06/23/2026
1.11.1 8 06/24/2026
1.11.0 12 06/20/2026
1.10.0-rc.2 7 06/30/2026
1.10.0-rc.1 8 06/23/2026
1.10.0-beta.3 9 06/23/2026
1.10.0-beta.2 8 06/23/2026
1.10.0-beta.1 7 06/23/2026
1.3.0-beta.1 12 04/23/2024
1.2.0-beta.1 9 06/20/2026
1.1.0-beta.3 8 07/08/2026
1.1.0-beta.2 10 07/05/2026