Datadog Lambda Library
Security Monitoring is now available Security Monitoring is now available

Datadog Lambda Library

The Datadog Lambda Library is responsible for:

  • Generating real-time enhanced Lambda metrics for invocations, errors, cold starts, etc.
  • Submitting custom metrics (synchronously and asynchronously).
  • Automatically propagating tracing headers from upstream requests to downstream services. This enables full distributed tracing across Lambda functions, hosts, containers, and other infrastructure running the Datadog Agent.
  • Packaging the dd-trace library, letting customers trace their Lambda functions with Datadog’s tracing libraries, currently available for Node.js, Python, and Ruby with more runtimes coming soon.

Datadog distributes the Lambda Library as a Lambda Layer and open-source package for Python, Node.js, and Ruby. Go is also supported with a package to include in your project. Datadog is working on support for new languages and runtimes; if there is another runtime you would like Datadog to support, reach out to the Datadog support team.


AWS Console

The Datadog Lambda Layer ARN includes a region, language runtime, and version. Construct yours in the following format:


For example:

PythonPython27, Python36, Python37, Python38Latest release
Node.jsNode8-10, Node10-x, Node12-xLatest release
RubyRubyLatest release

Golang: Since Go binaries are statically linked, Datadog offers a package you can import into your project. No Lambda Layer is required.

Java: Datadog offers a library you can import into your project. No Lambda Layer is required.

Note: The Datadog Lambda Layer and client libraries include the X-Ray SDK as a dependency, so you don’t need to explicitly install it in your projects.

Installation steps:

  1. Navigate to the Lambda function to which you want to add the Layer in your AWS console.
  2. Click on Layers on the main page of your function.
  3. Scroll down, and click on Add a Layer.
  4. Select the option to Provide a layer version ARN.
  5. Enter the Datadog Lambda Layer ARN from the table above.
  6. Navigate to the Environment Variables section of your function to configure your Datadog API key, and any other options (see table below).

Serverless Framework

This plugin attaches the Datadog Lambda Library for Node.js and Python to your functions using layers. At deploy time, it generates new handler functions that wrap your existing functions and initializes the Lambda Library.

You can install the plugin with one of the following commands.

npm install --save-dev serverless-plugin-datadog  # for NPM users
yarn add --dev serverless-plugin-datadog          # for Yarn users

Then, in your serverless.yml, add the following:

    - serverless-plugin-datadog

Configure the library by adding the following section to your serverless.yml. The default values are listed, as well as whether the field is required.

    # Whether to add the Lambda Layers, or expect the user to bring their own. Defaults to true.
    addLayers: true

    # The log level, set to DEBUG for extended logging. Defaults to info.
    logLevel: "info"

    # Send custom metrics via logs with the help of Datadog Forwarder Lambda function (recommended). Defaults to false.
    flushMetricsToLogs: false

    # Which Datadog Site to send data to, only needed when flushMetricsToLogs is false. Defaults to
    site: # for Datadog EU

    # Datadog API Key, only needed when flushMetricsToLogs is false
    apiKey: ""

    # Datadog API Key encrypted using KMS, only needed when flushMetricsToLogs is false
    apiKMSKey: ""

    # Enable tracing on Lambda functions and API Gateway integrations. Defaults to true
    enableXrayTracing: true

    # Enable tracing on Lambda function using dd-trace, datadog's APM library. Requires datadog log forwarder to be set up. Defaults to true.
    enableDDTracing: true

    # When set, the plugin will try to subscribe the lambda's cloudwatch log groups to the forwarder with the given arn.
    forwarder: arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder

Setting flushMetricsToLogs: true is recommended for submitting custom metrics via CloudWatch logs with the help of Datadog Forwarder.

Serverless Framework docs

<!–## AWS SAM

To enable X-Ray tracing by default for your Lambda functions and API Gateways, add the Function::Tracing and Api::TracingEnabled keys to the Globals section of your template.yaml. Also, add your Datadog API key and any other environment variables (see table below):

        Tracing: Active
        TracingEnabled: true

AWS SAM docs

Local Development

You can also include the Datadog Lambda Library directly in your project either from source or with the standard package manager for your runtime.

LanguageRepositoryApproximate Size
Node.jsGitHub2.6 MB
PythonGitHub10 MB
RubyGitHub2.3 MB
GoGitHub68 KB
JavaGitHub51 KB

Note: AWS SAM supports downloading Lambda Layers for local development.

Environment Variables

You can configure the Datadog Lambda Library by adding environment variables to your Lambda functions:

Environment VariableDescriptionRequiredDefaultAccepted Values
DD_API_KEYYour Datadog API keyYesDatadog API key
DD_KMS_API_KEYUse instead of DD_API_KEY if using KMSNoKMS-encrypted Datadog API key
DD_SITESet if using the EU instance of,
DD_FLUSH_TO_LOGEnable zero latency asynchronous custom metricsNoFalseTrue, False
DD_LOG_LEVELEnable detailed logs for the Datadog Lambda LayerNoINFOINFO, DEBUG

Further Reading

Additional helpful documentation, links, and articles: