OpenTelemetry.Instrumentation.AWSLambda 1.12.1

AWS OTel .NET SDK for Lambda

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:

• DisableAwsXRayContextExtraction
• SetParentFromBatch

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).

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:

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 Telemetery - 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

• OpenTelemetry Project
• OpenTelemetry Lambda
• AWS OpenTelemetry Lambda