serverless-plugin-datadog

What is serverless-plugin-datadog?

The serverless-plugin-datadog npm package is designed to integrate Datadog monitoring and observability features into Serverless Framework applications. It allows you to automatically instrument your AWS Lambda functions with Datadog, enabling you to monitor performance, track metrics, and set up alerts.

What are serverless-plugin-datadog's main functionalities?

Automatic Instrumentation

This feature automatically instruments your AWS Lambda functions with Datadog. By adding the plugin to your Serverless Framework configuration and setting the appropriate custom options, you can enable Datadog layers, flush metrics to logs, and set the log level.

{
  "plugins": ["serverless-plugin-datadog"],
  "custom": {
    "datadog": {
      "addLayers": true,
      "flushMetricsToLogs": true,
      "logLevel": "info"
    }
  }
}

Custom Metrics

This feature allows you to enable custom metrics for your Lambda functions. By setting the `customMetrics` option to true, you can send custom metrics from your Lambda functions to Datadog.

{
  "custom": {
    "datadog": {
      "customMetrics": true
    }
  }
}

Tracing

This feature enables tracing for your Lambda functions. By setting `enableXrayTracing` and `enableDDTracing` to true, you can enable AWS X-Ray and Datadog tracing, respectively, to get detailed insights into your function's performance.

{
  "custom": {
    "datadog": {
      "enableXrayTracing": true,
      "enableDDTracing": true
    }
  }
}

Other packages similar to serverless-plugin-datadog

serverless-plugin-splunk

The serverless-plugin-splunk package integrates Splunk logging and monitoring with Serverless Framework applications. It provides similar functionalities to serverless-plugin-datadog, such as automatic instrumentation and custom metrics, but it is tailored for Splunk's monitoring and observability tools.

serverless-plugin-aws-alerts

The serverless-plugin-aws-alerts package allows you to set up AWS CloudWatch alerts for your Serverless Framework applications. While it does not provide the same level of integration with a third-party monitoring service like Datadog, it offers a way to monitor and alert on AWS Lambda function performance using AWS-native tools.

README

Datadog Serverless Plugin

This serverless framework plugin automatically installs Datadog Lambda layers to your Python and Node.js Lambda functions to collect custom metrics and traces.

Installation

You can install the plugin with one of the following commands or add serverless-plugin-datadog to your project's package.json.

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

Then in your serverless.yml add the following:

plugins:
  - serverless-plugin-datadog

How it works

This plugin attaches the Datadog Lambda Layers for Node.js and Python to your functions. At deploy time, it generates new handler functions that wrap your existing functions and initializes the Lambda Layers. It also enables X-Ray tracing for your Lambda functions and API Gateways.

IMPORTANT NOTE: Because the plugin automatically wraps your Lambda handler function, you do NOT need to wrap your handler function as stated in the Node.js and Python Layer documentation.

Node.js

module.exports.myHandler = datadog(
  // This wrapper is NOT needed when using this plugin
  async function myHandler(event, context) {},
);

Python

@datadog_lambda_wrapper # This wrapper is NOT needed when using this plugin
def lambda_handler(event, context):

Configuration

You can configure the library by add the following section to your serverless.yml:

custom:
  datadog:
    # 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 datadoghq.com.
    site: datadoghq.com # datadoghq.eu 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

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

FAQ

What if I want to provide my own version of datadog-lambda-layer-js or datadog-lambda-layer-python?

You can use your own version of those libraries by setting 'addLayers' to false in the datadog configuration block. Just make sure to bundle those libaries with your Lambda functions.

How do I use this with serverless-webpack?

Make sure serverless-datadog is above the serverless-webpack entry in your serverless.yml

plugins:
  - serverless-plugin-datadog
  - serverless-webpack

When using serverless webpack, the plugin will assume you are using es6 module format. If that's not the case, you can manually configure nodeModuleType.

custom:
  datadog:
    nodeModuleType: "node" # 'typescript' | 'es6'

If you have the addLayers option enabled, you may also want to add 'datadog-lambda-js' and 'dd-trace' to the externals section of your webpack config. Note that auto instrumentation of libraries that have been webpacked into your bundle won't work, but other tracer features can be used.

How do I use this with serverless-typescript?

Make sure serverless-datadog is above the serverless-typescript entry in your serverless.yml. The plugin will detect automatically .ts files.

plugins:
  - serverless-plugin-datadog
  - serverless-typescript

Opening Issues

If you encounter a bug with this package, we want to hear about it. Before opening a new issue, 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. In addition, include the steps to reproduce when appropriate.

You can also open an issue for a feature request.

Contributing

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

License

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 (https://www.datadoghq.com/). Copyright 2019 Datadog, Inc.