Datadog CDK Constructs

Use this Datadog CDK Construct Library to deploy serverless applications using AWS CDK .

This CDK library 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 traces and custom metrics from your Lambda functions.
• Managing subscriptions from the Datadog Forwarder to your Lambda and non-Lambda log groups.

npm Package Installation:

yarn add --dev datadog-cdk-constructs
# or
npm install datadog-cdk-constructs --save-dev

PyPI Package Installation:

pip install datadog-cdk-constructs

Note:

Pay attention to the output from your package manager as the Datadog CDK Construct Library has peer dependencies.

Usage

AWS CDK

If you are new to AWS CDK then check out this workshop.

Add this to your CDK stack:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
from datadog_cdk_constructs import Datadog

datadog = Datadog(self, "Datadog",
    node_layer_version=<LAYER_VERSION>,
    python_layer_version=<LAYER_VERSION>,
    add_layers=<BOOLEAN>,
    forwarder_arn="<FORWARDER_ARN>",
    flush_metrics_to_logs=<BOOLEAN>,
    site="<SITE>",
    api_key="{Datadog_API_Key}",
    api_kms_key="{Encrypted_Datadog_API_Key}",
    enable_datadog_tracing=<BOOLEAN>,
    inject_log_context=<BOOLEAN>
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
datadog.add_forwarder_to_non_lambda_log_groups([<LOG_GROUPS>])

Configuration

To further configure your Datadog construct, use the following custom parameters:

Note: The Descriptions may use the npm package parameters however they also apply to the PyPI package parameters.

AWS CDK Configurations

The AWS CDK library offers some additional options that you may include in your lambda functions and application / stack.

Tracing

Enable X-Ray Tracing on your Lambda functions. For more information, see CDK documentation.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_lambda as lambda_

lambda_function = lambda_.Function(self, "HelloHandler",
    runtime=lambda_.Runtime.NODEJS_10_X,
    code=lambda_.Code.from_asset("lambda"),
    handler="hello.handler",
    tracing=lambda_.Tracing.ACTIVE
)

Nested Stacks

Add the Datadog CDK Construct to each stack you wish to instrument with Datadog. In the example below, we initialize the Datadog CDK Construct and call addLambdaFunctions() in both the RootStack and NestedStack.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
from datadog_cdk_constructs import Datadog
import aws_cdk.core as cdk

class RootStack(cdk.Stack):
    def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, synthesizer=None, terminationProtection=None, analyticsReporting=None):
        super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting)
        NestedStack(self, "NestedStack")

        datadog = Datadog(self, "Datadog",
            node_layer_version=<LAYER_VERSION>,
            python_layer_version=<LAYER_VERSION>,
            add_layers=<BOOLEAN>,
            forwarder_arn="<FORWARDER_ARN>",
            flush_metrics_to_logs=<BOOLEAN>,
            site="<SITE>",
            api_key="{Datadog_API_Key}",
            api_kms_key="{Encrypted_Datadog_API_Key}",
            enable_datadog_tracing=<BOOLEAN>,
            inject_log_context=<BOOLEAN>
        )
        datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])

class NestedStack(cdk.NestedStack):
    def __init__(self, scope, id, *, parameters=None, timeout=None, notificationArns=None, removalPolicy=None):
        super().__init__(scope, id, parameters=parameters, timeout=timeout, notificationArns=notificationArns, removalPolicy=removalPolicy)

        datadog = Datadog(self, "Datadog",
            node_layer_version=<LAYER_VERSION>,
            python_layer_version=<LAYER_VERSION>,
            add_layers=<BOOLEAN>,
            forwarder_arn="<FORWARDER_ARN>",
            flush_metrics_to_logs=<BOOLEAN>,
            site="<SITE>",
            api_key="{Datadog_API_Key}",
            api_kms_key="{Encrypted_Datadog_API_Key}",
            enable_datadog_tracing=<BOOLEAN>,
            inject_log_context=<BOOLEAN>
        )
        datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])

Tags

Add tags to your constructs. We recommend setting an env and service tag to tie Datadog telemetry together. For more information see official AWS documentation and CDK documentation.

How it works

The Datadog CDK construct takes in a list of lambda functions and installs the Datadog Lambda Library by attaching the Lambda Layers for Node.js and Python to your functions. It redirects to a replacement handler that initializes the Lambda Library without any required code changes. Additional configurations added to the Datadog CDK construct will also translate into their respective environment variables under each lambda function (if applicable / required).

While Lambda function based log groups are handled by the addLambdaFunctions method automatically, the construct has an additional function addForwarderToNonLambdaLogGroups which will subscribe the forwarder to any additional log groups of your choosing.

Resources to learn about CDK

• CDK TypeScript Workshop
• Video Introducing CDK by AWS with Demo
• CDK Concepts

Using Projen

This AWS CDK Construct Library uses Projen to maintain project configuration files such as the package.json, .gitignore, .npmignore, etc. Most of the configuration files will be protected by Projen via read-only permissions. In order to change these files, edit the .projenrc.js file then run npx projen to synthesize the new changes. Check out Projen for more details.

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 the Datadog CDK Construct version, Node 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.

Testing

If you contribute to this package you can run the tests using yarn test. This package also includes a sample application for manual testing:

1. Open a seperate terminal and run yarn watch, this will ensure the Typescript files in the src directory are compiled to Javascript in the lib directory.
2. Navigate to src/sample, here you can edit index.ts to test your contributions manually.
3. At the root datadog-cdk-constructs directory run npx cdk --app lib/sample/index.js <CDK Command>, replacing <CDK Command> with common CDK commands like synth, diff, or deploy.

• Note, if you receive "... is not authorized to perform: ..." you may also need to authorize the commands with your AWS credentials.

Debug Logs

To display the debug logs for this library, set the DD_CONSTRUCT_DEBUG_LOGS env var to true when running cdk synth (use --quiet to suppress generated template output).

Example: Ensure you are at root datadog-cdk-constructs directory

DD_CONSTRUCT_DEBUG_LOGS=true npx cdk --app lib/sample/index.js synth --quiet

Community

For product feedback and questions, join the #serverless channel in the Datadog community on Slack.

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 2021 Datadog, Inc.