Datadog Serverless Plugin
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Datadog Serverless Plugin

serverless build Code Coverage NPM Slack License

Datadog recommends the Serverless Framework Plugin for developers using the Serverless Framework to deploy their serverless applications. The plugin automatically configures ingestion of metrics, traces, and logs from your serverless applications by:

  • Installing and configuring the Datadog Lambda library for your Python and Node.js Lambda functions.
  • Enabling the collection of enhanced Lambda metrics and custom metrics from your Lambda functions.
  • Managing subscriptions from the Datadog Forwarder to your Lambda function log groups.

Getting started

To quickly get started, follow the installation instructions for Python or Node.js, and view your function’s enhanced metrics, traces, and logs in Datadog. These instructions will get you a basic working setup.

More configuration options

To further configure your plugin, use the following custom parameters in your serverless.yml:

flushMetricsToLogsSend custom metrics by using logs with the Datadog Forwarder Lambda function (recommended). Defaults to true. If you disable this parameter, it’s required to set the parameters site and apiKey (or apiKMSKey if encrypted).
siteSet which Datadog site to send data, only needed when flushMetricsToLogs is false. Defaults to Set to for the Datadog EU site.
apiKeyDatadog API Key, only needed when flushMetricsToLogs is false. For more information about getting a Datadog API key, see the API key documentation.
apiKMSKeyDatadog API Key encrypted using KMS. Use this parameter in place of apiKey when flushMetricsToLogs is false, and you are using KMS encryption.
addLayersWhether to install the Datadog Lambda library as a layer. Defaults to true. Set to false when you plan to package the Datadog Lambda library to your function’s deployment package on your own so that you can install a specific version of the Datadog Lambda library (Python or Node.js).
logLevelThe log level, set to DEBUG for extended logging. Defaults to info.
enableXrayTracingSet true to enable X-Ray tracing on the Lambda functions and API Gateway integrations. Defaults to false.
enableDDTracingEnable Datadog tracing on the Lambda function. Defaults to true. When enabled, it’s required to set the forwarder parameter.
forwarderSetting this parameter subscribes the Lambda functions’ CloudWatch log groups to the given Datadog forwarder Lambda function. Required when enableDDTracing is set to true.
enableTagsWhen set, automatically tag the Lambda functions with the service and env tags using the service and stage values from the serverless application definition. It does NOT override if a service or env tag already exists. Defaults to true.
injectLogContextWhen set, the lambda layer will automatically patch console.log with Datadog’s tracing ids. Defaults to true.

To use any of these parameters, add a custom > datadog section to your serverless.yml similar to this example:

    flushMetricsToLogs: true
    apiKey: "{Datadog_API_Key}"
    apiKMSKey: "{Encripted_Datadog_API_Key}"
    addLayers: true
    logLevel: "info"
    enableXrayTracing: false
    enableDDTracing: true
    forwarder: arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder
    enableTags: true
    injectLogContext: true

Note: If you use webpack, Datadog recommends using the prebuilt layers by setting addLayers to true, which is the default, and add datadog-lambda-js and dd-trace to the externals section of your webpack config.


If you are using serverless-typescript, make sure that serverless-datadog is above the serverless-typescript entry in your serverless.yml. The plugin will automatically detect .ts files.

  - serverless-plugin-datadog
  - serverless-typescript

If you use TypeScript, you may encounter the error of missing type definitions. A missing type definition happens when you use the prebuilt layers (for example, set addLayers to true, which is the default) and need to import helper functions from the datadog-lambda-js and dd-trace packages to submit custom metrics or instrument a specific function. To resolve the error, add datadog-lambda-js and dd-trace to the devDependencies list of your project’s package.json.


dd-trace is known to be not compatible with webpack due to the use of conditional import and other issues. If using webpack, make sure to mark datadog-lambda-js and dd-trace as externals for webpack, so webpack knows these dependencies will be available in the runtime. You should also remove datadog-lambda-js and dd-trace from package.json and the build process to ensure you’re using the versions provided by the Datadog Lambda Layer.


If using serverless-webpack, make sure to also exclude datadog-lambda-js and dd-trace in your serverless.yml in addition to declaring them as external in your webpack config file.


var nodeExternals = require('webpack-node-externals')

module.exports = {
  // we use webpack-node-externals to excludes all node deps.
  // You can manually set the externals too.
  externals: [nodeExternals(), 'dd-trace', 'datadog-lambda-js'],


        - dd-trace
        - datadog-lambda-js

Opening Issues

If you encounter a bug with this package, let us know by filing an issue! Before opening a new issue, please search the existing issues to avoid duplicates.

When opening an issue, include your Serverless Framework version, Python/Node.js version, and stack trace if available. Also, please include the steps to reproduce when appropriate.

You can also open an issue for a feature request.


If you find an issue with this package and have a fix, please feel free to open a pull request following the procedures.


Unless explicitly stated otherwise, all files in this repository are licensed under the Apache License Version 2.0.

This product includes software developed at Datadog ( Copyright 2019 Datadog, Inc.