Datadog AWS Lambda Library

Warnings

• breaking Profiling 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.
• gotcha The 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.
• gotcha Many 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.
• gotcha While `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.
• gotcha Previous 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.

Install

• pip install datadog-lambda Install library locally

Imports

• datadog_lambda_wrapper

  from datadog_lambda.wrapper import datadog_lambda_wrapper

• extract_trigger_tags

  from datadog_lambda.trigger import extract_trigger_tags

Quickstart

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()))