Registry /
observability / opentelemetry-instrumentation-aws-lambda
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.5s · import 0.000s · 23MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
configure_lambda_handler
✓ from opentelemetry.instrumentation.aws_lambda import configure_lambda_handler
✗ from opentelemetry.instrumentation.aws_lambda import configure_lambda_handler
This quickstart demonstrates how to instrument an AWS Lambda handler using the `@configure_lambda_handler` decorator. In a production AWS Lambda environment, you typically deploy with an AWS Distro for OpenTelemetry (ADOT) Lambda Layer, which configures the OpenTelemetry SDK and exporters. For local testing, you might manually set up a `TracerProvider` and a `ConsoleSpanExporter` as shown in the commented section.
import os
from opentelemetry.instrumentation.aws_lambda import configure_lambda_handler
from opentelemetry import trace
# For production in AWS Lambda, typically an ADOT Layer handles OTel SDK setup.
# For local testing, you might set up a basic console exporter (uncomment below):
# from opentelemetry.sdk.resources import Resource
# from opentelemetry.sdk.trace import TracerProvider
# from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# resource = Resource.create({"service.name": os.environ.get("OTEL_SERVICE_NAME", "my-lambda-service")})
# trace.set_tracer_provider(TracerProvider(resource=resource))
# trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
@configure_lambda_handler
def my_lambda_handler(event, context):
"""
An example AWS Lambda handler.
The `@configure_lambda_handler` decorator automatically instruments
incoming requests, creating a span for the Lambda invocation.
"""
current_span = trace.get_current_span()
current_span.set_attribute("lambda.event_keys", str(list(event.keys())))
print(f"Processing event with keys: {list(event.keys())}")
# Simulate some work
import time
time.sleep(0.05)
return {
'statusCode': 200,
'body': 'Handler processed successfully!'
}
# To run locally for testing (optional, not part of typical Lambda deployment):
if __name__ == '__main__':
mock_event = {"message": "hello world", "data": 123}
mock_context = type('Context', (object,), {
'aws_request_id': 'local-test-id',
'function_name': 'test-func',
'invoked_function_arn': 'arn:aws:lambda:us-east-1:123456789012:function:test-func',
'memory_limit_in_mb': 128,
'get_remaining_time_in_millis': lambda: 30000,
'function_version': '$LATEST',
'log_group_name': '/aws/lambda/test-func',
'log_stream_name': '2023/10/26/[LATEST]xxxxxxxxxxxx',
'identity': None,
'client_context': None
})()
os.environ["OTEL_SERVICE_NAME"] = "my-local-lambda"
# If uncommenting SDK setup above, ensure this is also uncommented for local testing output
# from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
response = my_lambda_handler(mock_event, mock_context)
print(f"Local test response: {response}")
Debug
Known issues
gotchaThis library is currently in beta (`0.x.xb0` versioning). APIs and behavior may change significantly between minor versions without strict adherence to semantic versioning. Always pin exact versions.fixPin exact versions (e.g., `opentelemetry-instrumentation-aws-lambda==0.62b0`) in `requirements.txt` and review changelogs carefully when upgrading.
affects: 0.x.xb0 (all beta versions)
gotchaFor production AWS Lambda environments, rely on AWS Distro for OpenTelemetry (ADOT) Lambda Layers or custom Docker images. Simply `pip install`ing this package is not sufficient for full instrumentation and exporting in a typical Lambda deployment, as it requires OpenTelemetry SDK setup (providers, exporters).fixRefer to the ADOT Lambda documentation for Python for proper deployment instructions. For manual setup, ensure `OTEL_PYTHON_CONFIGURATOR` is set or the OpenTelemetry SDK is initialized correctly with a `TracerProvider` and `SpanProcessor`.
affects: All
gotchaWhile this instrumentation works with the OpenTelemetry Python SDK, it also depends on `aws-xray-sdk` and `opentelemetry-sdk-extension-aws`. Ensure there are no conflicts or unexpected behaviors if `aws-xray-sdk` is directly used elsewhere in your application, as OpenTelemetry generally aims to replace direct X-Ray SDK usage.fixPrefer OpenTelemetry for all tracing needs. If `aws-xray-sdk` is present, monitor traces closely to ensure correct behavior and avoid duplicate or malformed spans.
affects: All
gotchaInstrumentation adds overhead, which can impact Lambda cold start times and overall execution duration. Monitor your Lambda performance metrics (duration, memory usage) after deploying OpenTelemetry.fixBenchmark your Lambda functions with and without instrumentation. Optimize your code and OpenTelemetry configuration (e.g., sampler, batching settings) to minimize overhead. Consider using Provisioned Concurrency for latency-sensitive functions if overhead is critical.
affects: All
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for tracing context.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for trace and metric processing.
opentelemetry-instrumentationrequiredBase classes and utilities for instrumentations.
aws-xray-sdkrequiredUsed for parsing AWS X-Ray trace headers and propagating context within AWS services.
opentelemetry-sdk-extension-awsrequiredProvides AWS-specific resource detectors and utilities for the OpenTelemetry SDK.