AwsLambda.Host.OpenTelemetry 1.3.1

AwsLambda.Host.OpenTelemetry

OpenTelemetry integration for distributed tracing and observability in AWS Lambda functions.

📚 View Full Documentation

Overview

An extension package for the framework that provides comprehensive observability integration. This package enables:

• Distributed Tracing: Automatic span creation and context propagation for Lambda invocations
• Metrics Collection: Performance and business metrics exportable to standard observability backends
• OpenTelemetry Integration: Built on the OpenTelemetry SDK for vendor-neutral instrumentation
• AWS Lambda Instrumentation: Wraps OpenTelemetry.Instrumentation.AWSLambda for Lambda-specific insights
• Lifecycle Integration: Seamless integration with Lambda cold starts, warm invocations, and error tracking

Installation

This package requires to be installed and working in your project. It is an extension package and cannot function standalone.

First, install the core framework:

dotnet add package AwsLambda.Host

Then install this OpenTelemetry extension:

dotnet add package AwsLambda.Host.OpenTelemetry

Ensure your project uses C# 11 or later:

<PropertyGroup>
 <LangVersion>11</LangVersion>
 
</PropertyGroup>

You'll also need additional OpenTelemetry packages depending on your use case:

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Additional packages may include exporters (e.g., Jaeger, Datadog, AWS X-Ray), instrumentation libraries (e.g., for HTTP, database calls), and other extensions. See the AWS OTel Lambda .NET guide and OpenTelemetry.io .NET documentation for your specific observability backend and instrumentation needs.

Quick Start

Set up OpenTelemetry with the AWS Lambda instrumentation:

using AwsLambda.Host.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using OpenTelemetry.Instrumentation.AWSLambda;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = LambdaApplication.CreateBuilder();

// Configure OpenTelemetry with tracing
builder
 .Services.AddOpenTelemetry()
 .WithTracing(configure =>
 configure
 .AddAWSLambdaConfigurations()
 .SetResourceBuilder(
 ResourceBuilder.CreateDefault().AddService("MyLambda", serviceVersion: "1.0.0")
 )
 .AddOtlpExporter(options =>
 {
 options.Endpoint = new Uri("http://localhost:4317");
 })
 );

var lambda = builder.Build();

// Enable automatic tracing for Lambda invocations
lambda.UseOpenTelemetryTracing();

lambda.MapHandler(([Event] string input) => $"Hello {input}!");

// Flush traces on Lambda shutdown
lambda.OnShutdownFlushTracer();

await lambda.RunAsync();

Key Features

• Automatic Root Span – Wraps Lambda invocations with OpenTelemetry spans via source generation and compile-time interceptors
• AWS Lambda Context – Captures Lambda context information in spans (request IDs, function name, etc.)
• Custom Instrumentation – Inject ActivitySource to create spans for your business logic
• Multiple Exporters – OTLP, Jaeger, AWS X-Ray, Datadog, and more
• AOT Compatible – Works with .NET Native AOT compilation
• Graceful Shutdown – Ensures traces export before Lambda terminates

Core Concepts

Automatic Root Span Creation

When you call UseOpenTelemetryTracing(), the framework uses source generators and compile-time interceptors to inject tracing middleware into your handler pipeline. This middleware delegates to the OpenTelemetry.Instrumentation.AWSLambda wrapper functions to create root spans for each Lambda invocation. These root spans capture AWS Lambda context (request IDs, function name, etc.) and measure the entire invocation duration.

How it works:

• Compile Time: Source generators analyze your handler signature and create a compile-time interceptor that injects middleware into the pipeline
• Startup: The middleware extracts a TracerProvider from the dependency injection container
• Per Invocation: The middleware calls the appropriate AWS Lambda instrumentation wrapper function with the correct type information (event and response types), which uses the TracerProvider to create the root span

This happens at compile time with zero runtime reflection overhead. The actual span creation is delegated to the AWS Lambda OpenTelemetry instrumentation package.

Custom Instrumentation with ActivitySource

To add traces for specific operations within your handler (database queries, API calls, business logic), create a custom ActivitySource. See the OpenTelemetry.io guide on setting up an ActivitySource for detailed information.

using System.Diagnostics;

internal class Instrumentation : IDisposable
{
 public const string ActivitySourceName = "MyLambda";
 public const string ActivitySourceVersion = "1.0.0";

 public ActivitySource ActivitySource { get; } =
 new(ActivitySourceName, ActivitySourceVersion);

 public void Dispose() => ActivitySource.Dispose();
}

Register it with the TracerProvider and inject it into your handler:

builder.Services.AddSingleton<Instrumentation>();

var lambda = builder.Build();

// In your handler:
lambda.MapHandler(([Event] Request request, Instrumentation instrumentation) =>
{
 using var activity = instrumentation.ActivitySource.StartActivity("ProcessRequest");
 activity?.SetAttribute("request.name", request.Name);

 return ProcessRequest(request);
});

Custom spans created with your ActivitySource automatically link to the root Lambda invocation span, creating a complete trace of your function's execution. This is your responsibility—this package only provides the root invocation span.

Graceful Shutdown

Ensure all traces and metrics are exported before Lambda terminates:

lambda.OnShutdownFlushOpenTelemetry();

This registers shutdown handlers that force flush both the TracerProvider and MeterProvider with a configurable timeout (default: infinite):

lambda.OnShutdownFlushOpenTelemetry(timeoutMilliseconds: 5000);

You can also flush individually:

lambda.OnShutdownFlushTracer();
lambda.OnShutdownFlushMeter();

Example Project

A complete, runnable example with Docker Compose setup is available in .

The example demonstrates:

• Full OpenTelemetry configuration with OTLP export
• Custom instrumentation and metrics in a real handler
• Jaeger tracing backend setup via Docker Compose
• Running locally with AWS Lambda Test Tool
• Viewing traces and metrics in the Jaeger UI

Documentation

• AWS OTel Lambda Guide – Official AWS documentation for OpenTelemetry on Lambda with .NET

• OpenTelemetry.io – OpenTelemetry specification, APIs, and best practices

• OpenTelemetry Instrumentation AWSLambda – Source for the AWSLambda instrumentation

• Full Project Documentation – Comprehensive guides and patterns

Other Packages

Additional packages in the aws-lambda-host framework for abstractions, observability, and event source handling.

License

This project is licensed under the MIT License. See for details.