OpenTelemetry.Instrumentation.AWSLambda 1.21.0
AWS OTel .NET SDK for Lambda
| Status | |
|---|---|
| Stability | Stable |
| Code Owners | @rypdal, @Oberon00, @normj |
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
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()orAWSLambdaWrapper.TraceAsync()API and passTracerProvider, original Lambda function and its parameters.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.
.NET 10.0
- OpenTelemetry.Extensions.AWS (>= 1.21.0)
- Amazon.Lambda.APIGatewayEvents (>= 2.7.0)
- Amazon.Lambda.ApplicationLoadBalancerEvents (>= 2.2.0)
- Amazon.Lambda.Core (>= 2.8.0)
- Amazon.Lambda.SNSEvents (>= 2.1.0)
- Amazon.Lambda.SQSEvents (>= 2.2.0)
.NET 11.0
- OpenTelemetry.Extensions.AWS (>= 1.21.0)
- Amazon.Lambda.APIGatewayEvents (>= 2.7.0)
- Amazon.Lambda.ApplicationLoadBalancerEvents (>= 2.2.0)
- Amazon.Lambda.Core (>= 2.8.0)
- Amazon.Lambda.SNSEvents (>= 2.1.0)
- Amazon.Lambda.SQSEvents (>= 2.2.0)
.NET Standard 2.0
- OpenTelemetry.Extensions.AWS (>= 1.21.0)
- Amazon.Lambda.APIGatewayEvents (>= 2.7.0)
- Amazon.Lambda.ApplicationLoadBalancerEvents (>= 2.2.0)
- Amazon.Lambda.Core (>= 2.8.0)
- Amazon.Lambda.SNSEvents (>= 2.1.0)
- Amazon.Lambda.SQSEvents (>= 2.2.0)
- System.Text.Json (>= 10.0.0)
| 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 |