AWS Distro for OpenTelemetry

AWS Distro for OpenTelemetry Lambda Support For .NET

AWS Distro for OpenTelemetry Lambda Support For .NET

The OpenTelemetry Lambda instrumentation for .NET provides extension and tracing APIs you can use to instrument your Lambda function. The ADOT Lambda layer provides a reduced version of the AWS Distro for OpenTelemetry Collector, which can further export OpenTelemetry spans to back-end servers.

This chapter will walk you through the steps to manually instrument your Lambda function using the ADOT Lambda .NET SDK, and apply ADOT Lambda layer to enable end-to-end tracing.




Requirements

The OpenTelemetry Lambda SDK for .NET supports both dotnetcore3.1 and dotnet6 Lambda runtimes.

Instrumentation

Code Instrumentation

  1. Install the ADOT Lambda .NET SDK package to your Lambda function.
dotnet add package OpenTelemetry.Instrumentation.AWSLambda
  1. Add a call to AddAWSLambdaConfigurations() from TracerProvider.
TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
// add other instrumentations
.AddAWSLambdaConfigurations()
.Build();
  1. Create a wrapper function with the same signature as the original Lambda function. Call AWSLambdaWrapper.Trace() API and pass TracerProvider, the original Lambda function, and its inputs as parameters. Set the wrapper function as the Lambda handler input. See sample app for more code instrumentation details.
// 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)
{
return input?.ToString();
}

Lambda Layer

This layer includes a reduced version of the AWS Distro for OpenTelemetry Collector (ADOT Collector), which runs as a Lambda extension.

Note: Lambda layers are a regionalized resource, meaning that they can only be used in the Region in which they are published. Make sure to use the layer in the same region as your Lambda functions.

Find the supported regions and amd64/arm64 layer ARN in the table below for the ARNs to consume. Use amd64 as architecture for x86-based processors.

Supported RegionsLambda layer ARN formatContents
ap-northeast-1
ap-northeast-2
ap-south-1
ap-southeast-1
ap-southeast-2
ca-central-1
eu-central-1
eu-north-1
eu-west-1
eu-west-2
eu-west-3
sa-east-1
us-east-1
us-east-2
us-west-1
us-west-2
arn:aws:lambda:<region>:901920570463:layer:aws-otel-collector-<architecture>-ver-0-98-0:5Contains ADOT Collector v0.39.0

Enable Tracing

Once you’ve instrumented the Lambda function code and deployed to Lambda service, you can follow the instructions below to apply Lambda layer.

  1. Open the Lambda function you intend to trace in the AWS console.
  2. In the Layers section, choose Add a layer.
  3. Under Specify an ARN, paste the layer ARN, and then choose Add.

Also, remember to turn on active tracing on Lambda console so as to enable end-to-end tracing.

Tips:

  • By default, the layer is configured to export traces to AWS X-Ray. Make sure your Lambda role has the required AWS X-Ray permissions. See more on AWS X-Ray permissions for AWS Lambda.
  • To disable tracing, you’ll need to remove ADOT Lambda layer from your Lambda function and disable active tracing as described above.



Configuration

The ADOT Lambda layer contains the ADOT Collector. The configuration of the ADOT Collector follows the OpenTelemetry standard and uses the config.yaml by default, which exports telemetry data to AWS X-Ray. To customize the Collector config, see the main Lambda section for custom configuration instructions




Additional Instrumentation

For additional instrumentation, see the OpenTelemetry .NET documentation.




Service Graph

Below is a sample X-Ray service graph showing an instrumented Lambda handler (SampleLambdaHandler) firing a request to AWS S3. Note that there are three SampleLambdaHandler nodes in the service graph. The first two are X-Ray segments created by Lambda runtime, which denotes Lambda service and Lambda function respectively. The third one is created by ADOT Lambda .NET SDK, which will be eventually merged with Lambda function segment in the service graph in future.

Diagram