Registry / observability / datadog-lambda

datadog-lambda

JSON →
library8.127.0pypypi✓ verified 25d ago

The `datadog-lambda` library enables comprehensive monitoring, tracing, and logging for AWS Lambda functions in Datadog. It provides a Python wrapper to automatically instrument Lambda handlers, collect metrics, send traces, and forward logs to Datadog. The current version is 8.123.0 and it maintains a rapid release cadence, often several times a week, to keep pace with new features and bug fixes, typically bundling updates from `dd-trace-py`.

pip install datadog-lambda
INSTALL
IMPORT
SIG · DATADOG-LAMBDA
D
datadog-lambda
observabilitypythonv8.127.0
Install
8.7s avg
Import
1255ms
Disk
65MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.127.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.304s · 70.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 8.7s · import 1.206s · 63MB
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

datadog_lambda_wrapper
from datadog_lambda.wrapper import datadog_lambda_wrapper
extract_trigger_tags
from datadog_lambda.trigger import extract_trigger_tags

To instrument an AWS Lambda function, import `datadog_lambda_wrapper` and apply it as a decorator to your handler function. The library automatically captures metrics, logs, and traces. Remember that for actual deployment, using the Datadog AWS Lambda Layer is the recommended and most common approach, rather than `pip installing` the library into your deployment package, as the layer includes the necessary dependencies and potentially the Datadog Agent extension.

import json import os from datadog_lambda.trigger import extract_trigger_tags from datadog_lambda.wrapper import datadog_lambda_wrapper # Datadog API Key is typically set as an environment variable or handled by the Datadog Lambda Extension. # No direct in-code API key needed for basic wrapping. @datadog_lambda_wrapper def lambda_handler(event, context): # Extract tags specific to the trigger (e.g., SQS queue name, API Gateway details) trigger_tags = extract_trigger_tags(event) print(f"Trigger tags: {trigger_tags}") # Example of adding a custom tag to the trace span if os.environ.get('DD_TRACE_ENABLED', 'true').lower() == 'true': try: from ddtrace import tracer span = tracer.current_span() if span: # Span might be None if tracing is not enabled or not yet started span.set_tag('my_custom_tag', 'hello_datadog') except ImportError: pass # ddtrace is not installed or available response_body = { "message": "Hello from Datadog Lambda!", "input": event } return { "statusCode": 200, "body": json.dumps(response_body) } # To test locally (requires dummy event and context): # if __name__ == "__main__": # class MockContext: # aws_request_id = "test-request-id-123" # function_name = "test-function" # invoked_function_arn = "arn:aws:lambda:us-east-1:123456789012:function:test-function" # memory_limit_in_mb = 128 # get_remaining_time_in_millis = lambda: 10000 # test_event = { # "httpMethod": "GET", # "path": "/test", # "queryStringParameters": {"param1": "value1"} # } # os.environ['DD_SERVICE'] = 'my-lambda-service' # os.environ['DD_ENV'] = 'dev' # os.environ['DD_VERSION'] = '1.0.0' # os.environ['DD_TRACE_ENABLED'] = 'true' # print(lambda_handler(test_event, MockContext()))
Debug
Known issues
breakingProfiling is not supported on Python 3.14 Lambdas and enabling it (`DD_PROFILING_ENABLED=true`) will result in application crashes. This was first noted in v8.118.0.
fix
Disable profiling (`DD_PROFILING_ENABLED=false`) or use a Python runtime of 3.13 or older if profiling is critical. Monitor future releases for Python 3.14 support.
affects: >=8.118.0 for Python 3.14 runtime
gotchaThe internal `dd-trace-py` dependency's version varies based on your Lambda's Python runtime. Python 3.8 and 3.9 runtimes use an older `dd-trace-py` version (e.g., v3.19.5 with `datadog-lambda` v8.122.0), while Python >= 3.10 uses a newer one. This can lead to unexpected behavior or API differences if not accounted for.
fix
Be aware of your runtime's bundled `dd-trace-py` version when developing. Check the release notes of `datadog-lambda` for the exact `dd-trace-py` version bundled for your target Python runtime.
affects: All versions, due to runtime-specific bundling
gotchaMany critical configurations for `datadog-lambda` are controlled via environment variables (e.g., `DD_API_KEY`, `DD_SITE`, `DD_TRACE_ENABLED`, `DD_LAMBDA_HANDLER`). Misconfiguring or omitting these can prevent data from appearing in Datadog.
fix
Always review the Datadog documentation for a comprehensive list of required and optional environment variables and ensure they are correctly set in your Lambda function configuration.
affects: All versions
gotchaWhile `pip install datadog-lambda` can be used for local development, the recommended and most robust deployment method for AWS Lambda is to use the official Datadog AWS Lambda Layer. The layer bundles the library, its dependencies, and sometimes the Datadog Agent Extension, ensuring compatibility and reducing deployment package size.
fix
For production deployments, utilize the Datadog AWS Lambda Layer. Consult the Datadog documentation for the latest ARN for your region and desired Python runtime. Avoid mixing `pip install` with the Lambda layer unless specifically instructed.
affects: All versions
gotchaPrevious versions might have had inconsistencies or issues in how cold start metrics were reported, especially when using Lambda Managed Runtimes (LMI). Version 8.123.0 includes a fix to 'omit creating cold start on LMI'.
fix
Upgrade to version 8.123.0 or newer to ensure more accurate cold start reporting with Lambda Managed Runtimes. Users upgrading might observe changes in their cold start metric trends.
affects: <8.123.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'datadog_lambda'
The `datadog_lambda` library is not correctly installed or packaged within the Lambda deployment bundle, or the associated Lambda layer is not properly configured or attached to the function.
fix
Ensure the `datadog-lambda` package is included in your Lambda deployment package (e.g., by running `pip install -t . datadog-lambda` and zipping, or using a build tool that includes dependencies) or that the correct Datadog Lambda layer ARN is attached to your function in the AWS console or IaC definition.
DD_EXTENSION | ERROR | Unable to load trace agent config: you must specify an API Key, either via a configuration file or the DD_API_KEY env var.
The Datadog API key is not provided in the Lambda function's environment variables (`DD_API_KEY`, `DD_KMS_API_KEY`, or `DD_API_KEY_SECRET_ARN`), which is required for the Datadog Extension to send data.
fix
Set one of the required Datadog API key environment variables (e.g., `DD_API_KEY` with your API key, `DD_KMS_API_KEY` for a KMS-encrypted key, or `DD_API_KEY_SECRET_ARN` for a Secrets Manager ARN) on your AWS Lambda function. If using KMS or Secrets Manager, ensure the Lambda's IAM role has the necessary `kms:Decrypt` or `secretsmanager:GetSecretValue` permissions.
AttributeError: 'str' object has no attribute 'get'
This error occurs when the AWS Lambda function's handler returns a plain string instead of a dictionary (which AWS Lambda serializes to JSON), but the `datadog-lambda` wrapper expects a dictionary to process for context or tags.
fix
Modify your Lambda function to return a dictionary (JSON object) instead of a raw string. For example, instead of `return 'Hello'`, use `return {'statusCode': 200, 'body': 'Hello from Lambda!'}`.
ModuleNotFoundError: No module named 'openai.api_requestor'
This specific `ModuleNotFoundError` indicates an incompatibility between the version of `dd-trace-py` bundled with `datadog-lambda` and the installed `openai` library version, where `dd-trace-py` is trying to patch a module (`openai.api_requestor`) that no longer exists in newer `openai` versions.
fix
Upgrade the `dd-trace-py` library to a version that supports your `openai` library version (e.g., `ddtrace==2.2` or newer for `openai>=1.0`). This usually means updating the `datadog-lambda` layer to its latest version, which typically bundles an updated `dd-trace-py`.
Upgrade
Version history
8.127.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
2
Resources
datadog-lambda — pip install datadog-lambda · libregistry