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 layers for your .NET, Java, Node.js, and Python 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.

AWS CDK v1 vs AWS CDK v2

WARNING: AWS CDK v1 has reached end-of-support and datadog-cdk-constructs will no longer be receiving updates. It's strongly recommended to upgrade to AWS CDK v2 (official migration guide) and switch to using datadog-cdk-constructs-v2.

Two separate versions of Datadog CDK Constructs exist; datadog-cdk-constructs and datadog-cdk-constructs-v2. These are designed to work with AWS CDK v1 and AWS CDK v2 respectively.

• datadog-cdk-constructs-v2 requires Node >= 14, while datadog-cdk-constructs supports Node >= 12.
• datadog-cdk-constructs-v2 contains more features.
• Otherwise, the use of the two packages is identical.

Lambda

Package Installation

npm

For use with AWS CDK v2:

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

For use with AWS CDK v1:

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

PyPI

For use with AWS CDK v2:

pip install datadog-cdk-constructs-v2

For use with AWS CDK v1:

pip install datadog-cdk-constructs

Note:

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

Go

For use with AWS CDK v2:

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

AWS CDK v1 is not supported.

Usage

AWS CDK

The following examples assume the use of AWS CDK v2. If you're using CDK v1, import datadog-cdk-constructs rather than datadog-cdk-constructs-v2.

Add this to your CDK stack:

TypeScript

import { DatadogLambda } from "datadog-cdk-constructs-v2";

const datadogLambda = new DatadogLambda(this, "datadogLambda", {
  nodeLayerVersion: ,
  pythonLayerVersion: ,
  javaLayerVersion: ,
  dotnetLayerVersion: 
  addLayers: ,
  extensionLayerVersion: "",
  forwarderArn: "",
  createForwarderPermissions: ,
  flushMetricsToLogs: ,
  site: "",
  apiKey: "{Datadog_API_Key}",
  apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
  apiKeySecret: , // Only available in datadog-cdk-constructs-v2
  apiKmsKey: "{Encrypted_Datadog_API_Key}",
  enableDatadogTracing: ,
  enableMergeXrayTraces: ,
  enableDatadogLogs: ,
  injectLogContext: ,
  logLevel: ,
  env: , //Optional
  service: , //Optional
  version: , //Optional
  tags: , //Optional
});
datadogLambda.addLambdaFunctions([])
datadogLambda.addForwarderToNonLambdaLogGroups([])

Go

import (
	"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct"
)
datadogLambda := ddcdkconstruct.NewDatadogLambda(
    stack,
    jsii.String("Datadog"),
    &ddcdkconstruct.DatadogLambdaProps{
        NodeLayerVersion:      jsii.Number(),
        AddLayers:             jsii.Bool(),
        Site:                  jsii.String(),
        ApiKey:                jsii.String(os.Getenv("DD_API_KEY")),
        // ...
    })
datadogLambda.AddLambdaFunctions(&[]interface{}{myFunction}, nil)
datadogLambda.AddForwarderToNonLambdaLogGroups()

Source Code Integration

Source code integration is enabled by default through automatic lambda tagging, and will work if:

• The Datadog Github integration is installed.

• Your datadog-cdk dependency satisfies either of the below versions:

  • datadog-cdk-constructs-v2 >= 1.4.0
  • datadog-cdk-constructs >= 0.8.5

Alternative Methods to Enable Source Code Integration

If the automatic implementation doesn't work for your case, please follow one of the two guides below.

Note: these alternate guides only work for Typescript.

const app = new cdk.App();

// Make sure to add @datadog/datadog-ci via your package manager
const datadogCi = require("@datadog/datadog-ci");
// Manually uploading Git metadata to Datadog.
datadogCi.gitMetadata.uploadGitCommitHash("{Datadog_API_Key}", "");

const app = new cdk.App();
new ExampleStack(app, "ExampleStack", {});

app.synth();

async function main() {
  // Make sure to add @datadog/datadog-ci via your package manager
  const datadogCi = require("@datadog/datadog-ci");
  const [, gitHash] = await datadogCi.gitMetadata.uploadGitCommitHash("{Datadog_API_Key}", "");

  const app = new cdk.App();
  // Pass in the hash to the ExampleStack constructor
  new ExampleStack(app, "ExampleStack", {}, gitHash);
}

export class ExampleStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps, gitHash?: string) {
    ...
    ...
    datadogLambda.addGitCommitMetadata([], gitHash)
  }
}

Configuration

To further configure your DatadogLambda construct for Lambda, use the following custom parameters:

Note: The descriptions use the npm package parameters, but they also apply to PyPI and Go package parameters.

Note: Using the parameters above may override corresponding function level DD_XXX environment variables.

Tracing

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

import * as lambda from "aws-cdk-lib/aws-lambda";

const lambda_function = new lambda.Function(this, "HelloHandler", {
  runtime: lambda.Runtime.NODEJS_14_X,
  code: lambda.Code.fromAsset("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.

import { DatadogLambda } from "datadog-cdk-constructs-v2";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

class RootStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    new NestedStack(this, "NestedStack");

    const datadogLambda = new DatadogLambda(this, "DatadogLambda", {
      nodeLayerVersion: ,
      pythonLayerVersion: ,
      javaLayerVersion: ,
      dotnetLayerVersion: ,
      addLayers: ,
      forwarderArn: "",
      flushMetricsToLogs: ,
      site: "",
      apiKey: "{Datadog_API_Key}",
      apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
      apiKmsKey: "{Encrypted_Datadog_API_Key}",
      enableDatadogTracing: ,
      enableMergeXrayTraces: ,
      enableDatadogLogs: ,
      injectLogContext: 
    });
    datadogLambda.addLambdaFunctions([]);

  }
}

class NestedStack extends cdk.NestedStack {
  constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
    super(scope, id, props);

    const datadogLambda = new DatadogLambda(this, "DatadogLambda", {
      nodeLayerVersion: ,
      pythonLayerVersion: ,
      javaLayerVersion: ,
      dotnetLayerVersion: ,
      addLayers: ,
      forwarderArn: "",
      flushMetricsToLogs: ,
      site: "",
      apiKey: "{Datadog_API_Key}",
      apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
      apiKmsKey: "{Encrypted_Datadog_API_Key}",
      enableDatadogTracing: ,
      enableMergeXrayTraces: ,
      enableDatadogLogs: ,
      injectLogContext: 
    });
    datadogLambda.addLambdaFunctions([]);

  }
}

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.

Automatically grant AWS secret read access to Lambda execution role

Only available in datadog-cdk-constructs-v2

To automatically grant your Lambda execution roles read access to a given secret, pass in apiKeySecret in place of apiKeySecretArn when initializing the DatadogLambda construct.

const { Secret } = require('aws-cdk-lib/aws-secretsmanager');

const secret = Secret.fromSecretPartialArn(this, 'DatadogApiKeySecret', 'arn:aws:secretsmanager:us-west-1:123:secret:DATADOG_API_KEY');

const datadogLambda = new DatadogLambda(this, 'DatadogLambda', {
  ...
  apiKeySecret: secret
  ...
});

When addLambdaFunctions is called, the Datadog CDK construct grants your Lambda execution roles read access to the given AWS secret. This is done through the AWS ISecret's grantRead function.

How it works

The DatadogLambda construct takes in a list of lambda functions and installs the Datadog Lambda Library by attaching the Lambda Layers for .NET, Java, 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 subscribes the forwarder to any additional log groups of your choosing.

Step Functions

Only AWS CDK v2 is supported.

Usage

TypeScript

Example stack: step-functions-typescript-stack

Basic setup

import * as sfn from "aws-cdk-lib/aws-stepfunctions";
import { DatadogStepFunctions} from "datadog-cdk-constructs-v2";

const stateMachine = new sfn.StateMachine(...);
const datadogSfn = new DatadogStepFunctions(this, "DatadogSfn", {
  env: "", // e.g. "dev"
  service: "", // e.g. "my-cdk-service"
  version: "", // e.g. "1.0.0"
  forwarderArn: "", // e.g. "arn:test:forwarder:sa-east-1:12345678:1"
  tags: , // optional, e.g. "custom-tag-1:tag-value-1,custom-tag-2:tag-value-2"
});
datadogSfn.addStateMachines([stateMachine]);

Merging traces

To merge the Step Function's traces with downstream Lambda function or Step function's traces, modify the Lambda task payload or Step Function task input:

import * as tasks from "aws-cdk-lib/aws-stepfunctions-tasks";
import * as sfn from "aws-cdk-lib/aws-stepfunctions";
import { DatadogStepFunctions, DatadogLambda } from "datadog-cdk-constructs-v2";

const lambdaFunction = ...;
const lambdaTask = new tasks.LambdaInvoke(this, "MyLambdaTask", {
  lambdaFunction: lambdaFunction,
  payload: sfn.TaskInput.fromObject(
    DatadogStepFunctions.buildLambdaPayloadToMergeTraces(
      { "custom-key": "custom-value" }
    )
  ),
});

const childStateMachine = new sfn.StateMachine(...);
const invokeChildStateMachineTask = new tasks.StepFunctionsStartExecution(this, "InvokeChildStateMachineTask", {
  stateMachine: childStateMachine,
  input: sfn.TaskInput.fromObject(
    DatadogStepFunctions.buildStepFunctionTaskInputToMergeTraces({ "custom-key": "custom-value" }),
  ),
});

const stateMachine = new sfn.StateMachine(this, "CdkTypeScriptTestStateMachine", {
  definitionBody: sfn.DefinitionBody.fromChainable(lambdaTask.next(invokeChildStateMachineTask)),
});

const datadogLambda = ...;
datadogLambda.addLambdaFunctions([lambdaFunction]);

const datadogSfn = ...;
datadogSfn.addStateMachines([childStateMachine, stateMachine]);

Python

Example stack: step-functions-python-stack

Basic setup

from aws_cdk import (
    aws_stepfunctions as sfn,
    aws_stepfunctions_tasks as tasks,
)
from datadog_cdk_constructs_v2 import DatadogStepFunctions, DatadogLambda

state_machine = sfn.StateMachine(...)
datadog_sfn = DatadogStepFunctions(
    self,
    "DatadogSfn",
    env="", # e.g. "dev"
    service="", # e.g. "my-cdk-service"
    version="", # e.g. "1.0.0"
    forwarderArn="", # e.g. "arn:test:forwarder:sa-east-1:12345678:1"
    tags=, # optional, e.g. "custom-tag-1:tag-value-1,custom-tag-2:tag-value-2"
)
datadog_sfn.add_state_machines([child_state_machine, parent_state_machine])

Merging traces

To merge the Step Function's traces with downstream Lambda function or Step function's traces, modify the Lambda task payload or Step Function task input:

from aws_cdk import (
    aws_lambda,
    aws_stepfunctions as sfn,
    aws_stepfunctions_tasks as tasks,
)
from datadog_cdk_constructs_v2 import DatadogStepFunctions, DatadogLambda

lambda_function = aws_lambda.Function(...)
lambda_task = tasks.LambdaInvoke(
    self,
    "MyLambdaTask",
    lambda_function=lambda_function,
    payload=sfn.TaskInput.from_object(
        DatadogStepFunctions.build_lambda_payload_to_merge_traces(
            {"custom-key": "custom-value"}
        )
    ),
)

child_state_machine = sfn.StateMachine(...)
invoke_child_state_machine_task = tasks.StepFunctionsStartExecution(
    self,
    "InvokeChildStateMachineTask",
    state_machine=child_state_machine,
    input=sfn.TaskInput.from_object(
        DatadogStepFunctions.build_step_function_task_input_to_merge_traces(
            {"custom-key": "custom-value"}
        )
    ),
)

state_machine = sfn.StateMachine(
    self,
    "CdkPythonTestStateMachine",
    definition_body=sfn.DefinitionBody.from_chainable(
        lambda_task.next(invoke_child_state_machine_task)
    ),
)

datadog_lambda = DatadogLambda(...)
datadog_lambda.add_lambda_functions([lambda_function])

datadog_sfn = DatadogStepFunctions(...)
datadog_sfn.add_state_machines([child_state_machine, state_machine])

Go

Example stack: step-functions-go-stack

Basic setup

import (
	"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct"
	"github.com/aws/aws-cdk-go/awscdk/v2"
	sfn "github.com/aws/aws-cdk-go/awscdk/v2/awsstepfunctions"
)

stack := awscdk.NewStack(...)
stateMachine := sfn.NewStateMachine(...)
datadogSfn := ddcdkconstruct.NewDatadogStepFunctions(
  stack,
  jsii.String("DatadogSfn"),
  &ddcdkconstruct.DatadogStepFunctionsProps{
    Env:            jsii.String(""), // e.g. "dev"
    Service:        jsii.String("), // e.g. "my-cdk-service"
    Version:        jsii.String(""), // e.g. "1.0.0"
    ForwarderArn:   jsii.String(""), // e.g. "arn:test:forwarder:sa-east-1:12345678:1"
    Tags:           jsii.String(""), // optional, e.g. "custom-tag-1:tag-value-1,custom-tag-2:tag-value-2"
  }
)
datadogSfn.AddStateMachines(&[]sfn.StateMachine{stateMachine}, nil)

Merging traces

To merge the Step Function's traces with downstream Lambda function or Step function's traces, modify the Lambda task payload or Step Function task input:

import (
	"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct"
	"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
	sfn "github.com/aws/aws-cdk-go/awscdk/v2/awsstepfunctions"
	sfntasks "github.com/aws/aws-cdk-go/awscdk/v2/awsstepfunctionstasks"
	"github.com/aws/jsii-runtime-go"
)

lambdaFunction := awslambda.NewFunction(...)
lambdaPayload := ddcdkconstruct.DatadogStepFunctions_BuildLambdaPayloadToMergeTraces(&map[string]interface{}{
  "custom-key": "custom-value",
})
lambdaTask := sfntasks.NewLambdaInvoke(stack, jsii.String("MyLambdaTask"), &sfntasks.LambdaInvokeProps{
  LambdaFunction: lambdaFunction,
  Payload: sfn.TaskInput_FromObject(lambdaPayload),
})

childStateMachine := sfn.NewStateMachine(...)
stateMachineTaskInput := ddcdkconstruct.DatadogStepFunctions_BuildStepFunctionTaskInputToMergeTraces(
  &map[string]interface{}{
    "custom-key": "custom-value",
  }
)
invokeChildStateMachineTask := sfntasks.NewStepFunctionsStartExecution(
  stack,
  jsii.String("InvokeChildStateMachineTask"),
  &sfntasks.StepFunctionsStartExecutionProps{
    StateMachine: childStateMachine,
    Input: sfn.TaskInput_FromObject(stateMachineTaskInput),
  }
)
stateMachine := sfn.NewStateMachine(stack, jsii.String("CdkGoTestStateMachine"), &sfn.StateMachineProps{
  DefinitionBody: sfn.DefinitionBody_FromChainable(lambdaTask.Next(invokeChildStateMachineTask)),
})

datadogLambda := ...
datadogLambda.AddLambdaFunctions(&[]interface{}{lambdaFunction}, nil)

datadogSfn := ...
datadogSfn.AddStateMachines(&[]sfn.StateMachine{childStateMachine, stateMachine}, nil)

Configuration

Parameters for creating the DatadogStepFunctions construct:

How it works

The DatadogStepFunctions construct takes in a list of state machines and for each of them:

1. Set up logging, including:

   1. Set log level to ALL
   2. Set includeExecutionData to true
   3. Create and set destination log group (if not set already)
   4. Add permissions to the state machine role to log to CloudWatch Logs

2. Subscribe Datadog Forwarder to the state machine's log group

3. Set tags, including:

   1. env

   2. service

   3. version

   4. DD_TRACE_ENABLED: true. This enables tracing.

      1. To disable tracing, set it to false from AWS Management Console after the stack is deployed.
      2. If you wish to disable tracing using CDK, please open an issue so we can support it.

   5. dd_cdk_construct version tag

   6. custom tags passed as the tags paramater to DatadogStepFunctions construct

To merge the Step Function's traces with downstream Lambda function or Step function's traces, the construct adds $$.Execution, $$.State and $$.StateMachine fields into the Step Function task input or Lambda task payload.

Troubleshooting

Log group already exists

If cdk deploy fails with an error like:

> Resource of type 'AWS::Logs::LogGroup' with identifier '{"/properties/LogGroupName":"/aws/vendedlogs/states/CdkStepFunctionsTypeScriptStack1-CdkTypeScriptTestChildStateMachine-Logs-dev"}' already exists.

You have two options:

1. Delete the log group if you no longer need the logs in it. You may do so from AWS Management Console, at CloudWatch -> Logs -> Log groups.
2. Update the state machine definition if you wish to use the existing log group:

import * as logs from 'aws-cdk-lib/aws-logs';

const logGroupName = "/aws/vendedlogs/states/xxx";
const logGroup = logs.LogGroup.fromLogGroupName(stack, 'StateMachineLogGroup', logGroupName);

const stateMachine = new sfn.StateMachine(stack, 'MyStateMachine', {
  logs: {
    destination: logGroup,
  },
  ...
});

Resources to learn about CDK

• If you are new to AWS CDK then check out this workshop.
• CDK TypeScript Workshop
• Video Introducing CDK by AWS with Demo
• CDK Concepts

Using Projen

The Datadog CDK Construct Libraries use 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.
2. Run yarn watch, this will ensure the Typescript files in the src directory are compiled to Javascript in the lib directory.
3. Navigate to src/sample, here you can edit index.ts to test your contributions manually.
4. At the root directory, run npx cdk --app lib/sample/index.js , replacing `` 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 for Lambda, 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 the root 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.