The Datadog CLI modifies existing Lambda functions’ configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog’s serverless monitoring.

1. Install the Datadog CLI client

   npm install -g @datadog/datadog-ci @datadog/datadog-ci-plugin-lambda
   

2. If you are new to Datadog serverless monitoring, launch the Datadog CLI in the interactive mode to guide your first installation for a quick start, and you can ignore the remaining steps. To permanently install Datadog for your production applications, skip this step and follow the remaining ones to run the Datadog CLI command in your CI/CD pipelines after your normal deployment.

   datadog-ci lambda instrument -i
   

3. Configure the AWS credentials

   Datadog CLI requires access to the AWS Lambda service, and depends on the AWS JavaScript SDK to resolve the credentials. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI.

4. Configure the Datadog site

   export DATADOG_SITE="<DATADOG_SITE>"
   

   Replace <DATADOG_SITE> with (ensure the correct SITE is selected on the right).

5. Configure the Datadog API key

   Datadog recommends saving the Datadog API key in AWS Secrets Manager for security and easy rotation. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda functions have the required secretsmanager:GetSecretValue IAM permission.

   export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
   

   For quick testing purposes, you can also set the Datadog API key in plaintext:

   export DATADOG_API_KEY="<DATADOG_API_KEY>"
   

6. Instrument your Lambda functions

   Note: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation result is unsatisfactory, run uninstrument with the same arguments to revert the changes.

   To instrument your Lambda functions, run the following command.

   datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 123 -e 93
   

   To fill in the placeholders:

   • Replace <functionname> and <another_functionname> with your Lambda function names. Alternatively, you can use --functions-regex to automatically instrument multiple functions whose names match the given regular expression.
   • Replace <aws_region> with the AWS region name.

   Additional parameters can be found in the CLI documentation.

The Datadog Serverless Plugin automatically configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension.

To install and configure the Datadog Serverless Plugin, follow these steps:

1. Install the Datadog Serverless Plugin:

   serverless plugin install --name serverless-plugin-datadog
   

2. Update your serverless.yml:

   custom:
     datadog:
       site: <DATADOG_SITE>
       apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
   

   To fill in the placeholders:

   • Replace <DATADOG_SITE> with (ensure the correct SITE is selected on the right).
   • Replace <DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The secretsmanager:GetSecretValue permission is required. For quick testing, you can instead use apiKey and set the Datadog API key in plaintext.

   For more information and additional settings, see the plugin documentation.

The Datadog CloudFormation macro automatically transforms your SAM application template to install Datadog on your functions using Lambda layers, and configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension.

1. Install the Datadog CloudFormation macro

   Run the following command with your AWS credentials to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro once for a given region in your account. Replace create-stack with update-stack to update the macro to the latest version.

   aws cloudformation create-stack \
     --stack-name datadog-serverless-macro \
     --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
     --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM
   

   The macro is now deployed and ready to use.

2. Instrument your Lambda functions

   Add the DatadogServerless transform after the AWS::Serverless transform under the Transform section in your template.yml file for SAM.

   Transform:
     - AWS::Serverless-2016-10-31
     - Name: DatadogServerless
       Parameters:
         stackName: !Ref "AWS::StackName"
         pythonLayerVersion: 123
         extensionLayerVersion: 93
         site: "<DATADOG_SITE>"
         apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
   

   To fill in the placeholders:

   • Replace <DATADOG_SITE> with (ensure the correct SITE is selected on the right).
   • Replace <DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The secretsmanager:GetSecretValue permission is required. For quick testing, you can use apiKey instead and set the Datadog API key in plaintext.

   More information and additional parameters can be found in the macro documentation.

The Datadog CDK construct automatically installs Datadog on your functions using Lambda layers. It configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension.

TypeScript

1. Install the Datadog CDK constructs library

   For AWS CDK v1:

   npm install datadog-cdk-constructs --save-dev
   

   For AWS CDK v2:

   npm install datadog-cdk-constructs-v2 --save-dev
   

2. Instrument your Lambda functions

   For AWS CDK v1:

   import { Datadog } from "datadog-cdk-constructs";
   
   const datadog = new Datadog(this, "Datadog", {
       pythonLayerVersion: 123,
       extensionLayerVersion: 93,
       site: "<DATADOG_SITE>",
       apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
   });
   datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
   

   For AWS CDK v2:

   import { DatadogLambda } from "datadog-cdk-constructs-v2";
   
   const datadogLambda = new DatadogLambda(this, "datadogLambda", {
       pythonLayerVersion: 123,
       extensionLayerVersion: 93,
       site: "<DATADOG_SITE>",
       apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
   });
   datadogLambda.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
   

Python

1. Install the Datadog CDK constructs library

   For AWS CDK v1:

   pip install datadog-cdk-constructs
   

   For AWS CDK v2:

   pip install datadog-cdk-constructs-v2
   

2. Instrument your Lambda functions

   For AWS CDK v1:

   from datadog_cdk_constructs import Datadog
   datadog = Datadog(self, "Datadog",
       python_layer_version=123,
       extension_layer_version=93,
       site="<DATADOG_SITE>",
       api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
     )
   datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
   

   For AWS CDK v2:

   from datadog_cdk_constructs_v2 import DatadogLambda
   
   datadog = DatadogLambda(self, "datadogLambda",
       python_layer_version=123,
       extension_layer_version=93,
       site="<DATADOG_SITE>",
       api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
     )
   datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
   

Go

Note: Go CDK constructs are only available for AWS CDK v2.

1. Install the Datadog CDK constructs library

   go get github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v3
   

2. Instrument your Lambda functions

   import (
       "github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v3"
   )
   
   datadogLambda := ddcdkconstruct.NewDatadogLambda(
       stack,
       jsii.String("Datadog"),
       &ddcdkconstruct.DatadogLambdaProps{
           PythonLayerVersion:      jsii.Number(123),
           ExtensionLayerVersion: jsii.Number(93),
           Site:                  jsii.String("<DATADOG_SITE>"),
           ApiKeySecretArn:       jsii.String("<DATADOG_API_KEY_SECRET_ARN>"),
       })
   datadogLambda.AddLambdaFunctions(&[]interface{}{<LAMBDA_FUNCTIONS>}, nil)
   

To fill in the placeholders:

• Replace <DATADOG_SITE> with (ensure the correct SITE is selected on the right).
• Replace <DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda execution role has the secretsmanager:GetSecretValue IAM permission in order to read the secret value. For quick testing, you can use apiKey instead and set the Datadog API key in plaintext.

More information and additional parameters can be found on the Datadog CDK documentation.

1. Install the Datadog Lambda Library

   If you are deploying your Lambda function as a container image, you cannot use the Datadog Lambda library as a Lambda Layer. Instead, you must install the Datadog Lambda library as a dependency of your function within the image.

   pip install datadog-lambda
   

   Note that the minor version of the datadog-lambda package always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5.

2. Install the Datadog Lambda Extension

   Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile:

   COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/
   

   Replace <TAG> with either a specific version number (for example, 93) or with latest. Alpine is also supported with specific version numbers (such as 93-alpine) or with latest-alpine. You can see a complete list of possible tags in the Amazon ECR repository.

3. Redirect the handler function

   • Set your image’s CMD value to datadog_lambda.handler.handler. You can set this in AWS or directly in your Dockerfile. Note that the value set in AWS overrides the value in the Dockerfile if you set both.
   • Set the environment variable DD_LAMBDA_HANDLER to your original handler, for example, myfunc.handler.

   Note: If you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection, you can apply the Datadog wrapper in your function code instead.

4. Configure the Datadog site, API key, and tracing in your Dockerfile

   • Set the environment variable DD_SITE to (ensure the correct SITE is selected on the right).
   • Set the environment variable DD_API_KEY_SECRET_ARN with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The secretsmanager:GetSecretValue permission is required. For quick testing, you can use DD_API_KEY instead and set the Datadog API key in plaintext.
   • Set the environment variable DD_TRACE_ENABLED to true.

The lambda-datadog Terraform module wraps the aws_lambda_function resource and automatically configures your Lambda function for Datadog Serverless Monitoring by:

• Adding the Datadog Lambda layers
• Redirecting the Lambda handler
• Enabling the collection and sending of metrics, traces, and logs to Datadog

module "lambda-datadog" {
  source  = "DataDog/lambda-datadog/aws"
  version = "4.0.0"

  environment_variables = {
    "DD_API_KEY_SECRET_ARN" : "<DATADOG_API_KEY_SECRET_ARN>"
    "DD_ENV" : "<ENVIRONMENT>"
    "DD_SERVICE" : "<SERVICE_NAME>"
    "DD_SITE": "<DATADOG_SITE>"
    "DD_VERSION" : "<VERSION>"
  }

  datadog_extension_layer_version = 93
  datadog_python_layer_version = 123

  # aws_lambda_function arguments
}

1. Replace the aws_lambda_function resource with the lambda-datadog Terraform module. Then, specify the source and version of the module.

2. Set the aws_lambda_function arguments:

   All of the arguments available in the aws_lambda_function resource are available in this Terraform module. Arguments defined as blocks in the aws_lambda_function resource are redefined as variables with their nested arguments.

   For example, in aws_lambda_function, environment is defined as a block with a variables argument. In the lambda-datadog Terraform module, the value for the environment_variables is passed to the environment.variables argument in aws_lambda_function. See inputs for a complete list of variables in this module.

3. Fill in the environment variable placeholders:

   • Replace <DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The secretsmanager:GetSecretValue permission is required. For quick testing, you can instead use the environment variable DD_API_KEY and set your Datadog API key in plaintext.
   • Replace <ENVIRONMENT> with the Lambda function’s environment, such as prod or staging
   • Replace <SERVICE_NAME> with the name of the Lambda function’s service
   • Replace <DATADOG_SITE> with . (Ensure the correct Datadog site is selected on this page).
   • Replace <VERSION> with the version number of the Lambda function

4. Select the versions of the Datadog Extension Lambda layer and Datadog Python Lambda layer to use. If left blank the latest layer versions will be used.

  datadog_extension_layer_version = 93
  datadog_python_layer_version = 123

To configure Datadog using SST v3, follow these steps:

const app = new sst.aws.Function("MyApp", {
  handler: "lambda_function.lambda_handler",
  runtime: "python3.13",
  environment: {
    DD_ENV: "<ENVIRONMENT>",
    DD_SERVICE: "<SERVICE_NAME>",
    DD_VERSION: "<VERSION>",
    DATADOG_API_KEY_SECRET_ARN: "<DATADOG_API_KEY_SECRET_ARN>",
    DD_SITE: "<DATADOG_SITE>",
  },
  layers: [
    $interpolate`arn:aws:lambda:${aws.getRegionOutput().name}:464622532012:layer:Datadog-Extension:93`,
    $interpolate`arn:aws:lambda:${aws.getRegionOutput().name}:464622532012:layer:Datadog-<RUNTIME>:123`,
  ],
});

1. Configure the Datadog Lambda Library and Datadog Lambda Extension layers

   • The available <RUNTIME> options are: Python38, Python39, Python310, Python311, Python312, Python313, Python314.

2. Fill in the environment variable placeholders:

   • Replace <DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The secretsmanager:GetSecretValue permission is required. For quick testing, you can instead use the environment variable DD_API_KEY and set your Datadog API key in plaintext.
   • Replace <ENVIRONMENT> with the Lambda function’s environment, such as prod or staging
   • Replace <SERVICE_NAME> with the name of the Lambda function’s service
   • Replace <DATADOG_SITE> with . (Ensure the correct Datadog site is selected on this page).
   • Replace <VERSION> with the version number of the Lambda function

3. Apply the Datadog wrapper in your function code

1. Install the Datadog Lambda library

   The Datadog Lambda Library can be imported either as a layer (recommended) OR as a Python package.

   The minor version of the datadog-lambda package always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5.

   • Option A: Configure the layers for your Lambda function using the ARN in the following format:

     # Use this format for x86-based Lambda deployed in AWS commercial regions
     arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:123
     
     # Use this format for arm64-based Lambda deployed in AWS commercial regions
     arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>-ARM:123
     
     # Use this format for x86-based Lambda deployed in AWS GovCloud regions
     arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:123
     
     # Use this format for arm64-based Lambda deployed in AWS GovCloud regions
     arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>-ARM:123
     

     Replace <AWS_REGION> with a valid AWS region, such as us-east-1. The available <RUNTIME> options are: Python38, Python39, Python310, Python311, Python312, Python313, Python314.

   • Option B: If you cannot use the prebuilt Datadog Lambda layer, alternatively install the datadog-lambda package and its dependencies locally to your function project folder using your favorite Python package manager, such as pip.

     pip install datadog-lambda -t ./
     

     Note: datadog-lambda depends on ddtrace, which uses native extensions; therefore it must be installed and compiled in a Linux environment on the right architecture (x86_64 or arm64). For example, you can use dockerizePip for the Serverless Framework and –use-container for AWS SAM. For more details, see how to add dependencies to your function deployment package.

     See the latest release.

2. Install the Datadog Lambda Extension

   Configure the layers for your Lambda function using the ARN in the following format:

   # Use this format for x86-based Lambda deployed in AWS commercial regions
   arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:93
   
   # Use this format for arm64-based Lambda deployed in AWS commercial regions
   arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:93
   
   # Use this format for x86-based Lambda deployed in AWS GovCloud regions
   arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:93
   
   # Use this format for arm64-based Lambda deployed in AWS GovCloud regions
   arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:93
   

   Replace <AWS_REGION> with a valid AWS region, such as us-east-1.

3. Redirect the handler function

   • Set your function’s handler to datadog_lambda.handler.handler.
   • Set the environment variable DD_LAMBDA_HANDLER to your original handler, for example, myfunc.handler.

   Note: If you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection, you can apply the Datadog wrapper in your function code instead.

4. Configure the Datadog site, API key, and tracing

   • Set the environment variable DD_SITE to (ensure the correct SITE is selected on the right).
   • Set the environment variable DD_API_KEY_SECRET_ARN with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string, instead of being inside a json blob. The secretsmanager:GetSecretValue permission is required. For quick testings, you can use DD_API_KEY instead and set the Datadog API key in plaintext.
   • Set the environment variable DD_TRACE_ENABLED to true.

5. (AWS Chalice only) Register the middleware

   If you are using AWS Chalice, you must install datadog-lambda using pip, and register datadog_lambda_wrapper as a middleware in your app.py:

   from chalice import Chalice, ConvertToMiddleware
   from datadog_lambda.wrapper import datadog_lambda_wrapper
   
   app = Chalice(app_name='hello-chalice')
   
   app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper))
   
   @app.route('/')
   def index():
       return {'hello': 'world'}