Datadog CDK Constructs

![NPM](https://www.npmjs.com/package/datadog-cdk-constructs-v2)
![PyPI](https://pypi.org/project/datadog-cdk-constructs-v2/)
![Go](https://pkg.go.dev/github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct)
![Maven](https://search.maven.org/artifact/com.datadoghq/datadog-cdk-constructs)
![License](https://github.com/DataDog/datadog-cdk-constructs/blob/main/LICENSE)

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

For more information on the DatadogECSFargate construct, see [here][23].

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 [Python][1], [Node.js][2], [Java][15], [Go][26], [Ruby][25], and [.NET][19] 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.

Lambda

$3

#### npm

``yarn add --dev datadog-cdk-constructs-v2

`or`


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


#### PyPI

`pip install datadog-cdk-constructs-v2`

##### Note:

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

#### Go

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

#### Maven (Java)

Add to your pom.xml:

`xml com.datadoghq datadog-cdk-constructs 3.3.0`

`$3`

#### AWS CDK

Add this to your CDK stack:

#### TypeScript

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

const datadogLambda = new DatadogLambda(this, "datadogLambda", { nodeLayerVersion: , pythonLayerVersion: , javaLayerVersion: , dotnetLayerVersion: , rubyLayerVersion: , 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([])`

#### Python

`python from datadog_cdk_constructs_v2 import DatadogLambda datadog = DatadogLambda( self, "Datadog", dotnet_layer_version=, node_layer_version=, python_layer_version=, ruby_layer_version=, java_layer_version=, extension_layer_version=, add_layers=, api_key=os.getenv("DD_API_KEY"), site=, ) datadog.add_lambda_functions([]) datadog.add_forwarder_to_non_lambda_log_groups(self.logGroups)`

#### Go

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

#### Java

`java import com.datadoghq.cdkconstructs.DatadogLambda; import com.datadoghq.cdkconstructs.DatadogLambdaProps;

DatadogLambda datadogLambda = new DatadogLambda(this, "Datadog", DatadogLambdaProps.builder() .nodeLayerVersion() .pythonLayerVersion() .javaLayerVersion() .dotnetLayerVersion() .rubyLayerVersion() .addLayers() .extensionLayerVersion() .flushMetricsToLogs() .site("") .apiKey(System.getenv("DD_API_KEY")) .enableDatadogTracing() .enableDatadogLogs() .build() ); datadogLambda.addLambdaFunctions(new Object[]{myFunction}); datadogLambda.addForwarderToNonLambdaLogGroups(new Object[]{myLogGroup});`

`$3`

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

- The Datadog Github integration is installed. - Yourdatadog-cdk-constructs-v2 version is >= 1.4.0

#### 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.


  datadog-cdk version satisfied, but Datadog Github integration NOT installed

If the Datadog Github integration is not installed, you need to import the datadog-cipackage and manually upload your Git metadata to Datadog. For the best results, import thedatadog-ci package where your CDK Stack is initialized.

`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();`


  datadog-cdk version NOT satisfied

Change your initialization function as follows (in this case, gitHash value is passed to the CDK):

`typescript 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); }`

Ensure you call this function to initialize your stack.

In your stack constructor, change to add an optional gitHash parameter, and call addGitCommitMetadata():

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

`$3`

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.

| npm package parameter | PyPI package parameter | Description | | ---------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |addLayers | add_layers | Whether to add the runtime Lambda Layers or expect the user to bring their own. Defaults to true. When true, the Lambda Library version variables are also required. When false, you must include the Datadog Lambda library in your functions' deployment packages. | |pythonLayerVersion | python_layer_version | Version of the Python Lambda layer to install, such as 83. Required if you are deploying at least one Lambda function written in Python and addLayers is true. Find the latest version number [here][5]. Warning: This parameter and pythonLayerArnare mutually exclusive. If used, only set one or the other. | |pythonLayerArn | python_layer_arn | The custom ARN of the Python Lambda layer to install. Required if you are deploying at least one Lambda function written in Python and addLayers is true. Warning: This parameter and pythonLayerVersionare mutually exclusive. If used, only set one or the other. | |nodeLayerVersion | node_layer_version | Version of the Node.js Lambda layer to install, such as 100. Required if you are deploying at least one Lambda function written in Node.js and addLayers is true. Find the latest version number from [here][6]. Warning: This parameter and nodeLayerArnare mutually exclusive. If used, only set one or the other. | |nodeLayerArn | node_layer_arn | The custom ARN of the Node.js Lambda layer to install. Required if you are deploying at least one Lambda function written in Node.js and addLayers is true. Warning: This parameter and nodeLayerVersionare mutually exclusive. If used, only set one or the other. | |javaLayerVersion | java_layer_version | Version of the Java layer to install, such as 8. Required if you are deploying at least one Lambda function written in Java and addLayers is true. Find the latest version number in the [Serverless Java installation documentation][15]. Note: extensionLayerVersion >= 25 and javaLayerVersion >= 5 are required for the DatadogLambda construct to instrument your Java functions properly. Warning: This parameter and javaLayerArnare mutually exclusive. If used, only set one or the other. | |javaLayerArn | java_layer_arn | The custom ARN of the Java layer to install. Required if you are deploying at least one Lambda function written in Java and addLayers is true. Warning: This parameter and javaLayerVersionare mutually exclusive. If used, only set one or the other. | |dotnetLayerVersion | dotnet_layer_version | Version of the .NET layer to install, such as 23. Required if you are deploying at least one Lambda function written in .NET and addLayers is true. Find the latest version number from [here][18]. Warning: This parameter and dotnetLayerArnare mutually exclusive. If used, only set one or the other. | |dotnetLayerArn | dotnet_layer_arn | The custom ARN of the .NET layer to install. Required if you are deploying at least one Lambda function written in .NET and addLayers is true. Warning: This parameter and dotnetLayerVersionare mutually exclusive. If used, only set one or the other. . | |extensionLayerVersion | extension_layer_version | Version of the Datadog Lambda Extension layer to install, such as 5. When extensionLayerVersion is set, apiKey (or if encrypted, apiKMSKey, apiKeySecret, or apiKeySecretArn) needs to be set as well. When enabled, lambda function log groups will not be subscribed by the forwarder. Learn more about the Lambda extension [here][12] and get the [latest version][27]. Warning: This parameter and extensionVersionArn are mutually exclusive. Set only one or the other. Note: If this parameter is set, it adds a layer even if addLayers is set to false. | |extensionLayerArn | extension_layer_arn | The custom ARN of the Datadog Lambda Extension layer to install. When extensionLayerArn is set, apiKey (or if encrypted, apiKMSKey, apiKeySecret, or apiKeySecretArn) needs to be set as well. When enabled, lambda function log groups are not subscribed by the forwarder. Learn more about the Lambda extension [here][12] and get the [latest version][27]. Warning: This parameter andextensionLayerVersion are mutually exclusive. If used, only set one or the other. Note: If this parameter is set, it adds a layer even if addLayers is set to false. | |forwarderArn | forwarder_arn | When set, the plugin automatically subscribes the Datadog Forwarder to the functions' log groups. Do not set forwarderArn when extensionLayerVersion or extensionLayerArnis set. | |createForwarderPermissions | createForwarderPermissions | When set to true, creates a Lambda permission on the the Datadog Forwarder per log group. Since the Datadog Forwarder has permissions configured by default, this is unnecessary in most use cases. | |flushMetricsToLogs | flush_metrics_to_logs | Send custom metrics using CloudWatch logs with the Datadog Forwarder Lambda function (recommended). Defaults to true . If you disable this parameter, it's required to set apiKey (or if encrypted, apiKMSKey, apiKeySecret, or apiKeySecretArn). | |site | site | Set which Datadog site to send data. This is only used when flushMetricsToLogs is false or extensionLayerVersion or extensionLayerArn is set. Possible values are datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, and ddog-gov.com. The default is datadoghq.com. | |apiKey | api_key | Datadog API Key, only needed when flushMetricsToLogs is false or extensionLayerVersion or extensionLayerArnis set. For more information about getting a Datadog API key, see the [API key documentation][8]. | |apiKeySecretArn | api_key_secret_arn | The ARN of the secret storing the Datadog API key in AWS Secrets Manager. Use this parameter in place of apiKey when flushMetricsToLogs is false or extensionLayer is set. Remember to add the secretsmanager:GetSecretValuepermission to the Lambda execution role. | |apiKeySsmArn | api_key_ssm_arn | The ARN of the parameter storing the Datadog API key in AWS Systems Manager Parameter Store (for example, arn:aws:ssm:us-east-1:123456789012:parameter/my/parameter/name). Use this parameter in place of apiKey when flushMetricsToLogs is false or extensionLayer is set. Supports both String and SecureString parameter types. When grantSecretReadAccess is true (default), the construct automatically grants ssm:GetParameter and kms:Decrypt (for the AWS managed key alias/aws/ssm) permissions. If using a custom KMS key for SecureString encryption, you must grant kms:Decryptpermission for that key separately. | |apiKeySecret | api_key_secret | An [AWS CDK ISecret][16] representing a secret storing the Datadog API key in AWS Secrets Manager. Use this parameter in place of apiKeySecretArnto automatically grant your Lambda execution roles read access to the given secret. See here for an example. Only available in datadog-cdk-constructs-v2. | |apiKmsKey | api_kms_key | Datadog API Key encrypted using KMS. Use this parameter in place of apiKey when flushMetricsToLogs is false or extensionLayerVersion or extensionLayerArnis set, and you are using KMS encryption. | |enableDatadogTracing | enable_datadog_tracing | Enable Datadog tracing on your Lambda functions. Defaults to true. | |enableMergeXrayTraces | enable_merge_xray_traces | Enable merging X-Ray traces on your Lambda functions. Defaults to false. | |enableDatadogLogs | enable_datadog_logs | Send Lambda function logs to Datadog via the Datadog Lambda Extension. Defaults to true. Note: This setting has no effect on logs sent via the Datadog Forwarder. | |enableDatadogASM | enable_datadog_asm | Deprecated: use datadogAppsecMode: on instead. Enable [Datadog App and API Protection][21] on the Lambda function. Requires enableDatadogTracing to be enabled. Defaults to false. | |datadogAppSecMode | datadog_app_sec_mode | Enable [Datadog App and API Protection][21] on the Lambda function. To enable App and API Protection, set the value to on. Accepts off, on, extension, and tracer. The values on, extension and tracer require enableDatadogTracing. Defaults to off. For more information on the tracer and extensionoptions read Enable in-tracer App and API Protection. | |captureLambdaPayload | capture_lambda_payload | [Captures incoming and outgoing AWS Lambda payloads][22] in the Datadog APM spans for Lambda invocations. Defaults to false. | |captureCloudServicePayload | capture_cloud_service_payload | [Capture requests and responses between your application and AWS services][24] in the Datadog APM spans' tags. Supported services include SNS, SQS, Kinesis, S3, EventBridge, DynamoDB. If set to true, it will add DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING='all' and DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING='all'. If set to false it would add DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING='$.' and DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING='$.'. $.* is a JSONPath redaction rule that redacts all values. Defaults to false. | |sourceCodeIntegration | source_code_integration | Enable Datadog Source Code Integration, connecting your telemetry with application code in your Git repositories. This requires the Datadog Github integration to work, otherwise please follow the alternative method. Learn more here. Defaults to true. | |injectLogContext | inject_log_context | When set, the Lambda layer will automatically patch console.log with Datadog's tracing ids. Defaults to true. | |logLevel | log_level | When set to debug, the Datadog Lambda Library and Extension will log additional information to help troubleshoot issues. | |env | env | When set along with extensionLayerVersion or extensionLayerArn, a DD_ENV environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, an envtag is added to all Lambda functions with the provided value. | |service | service | When set along with extensionLayerVersion or extensionLayerArn, a DD_SERVICE environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, a servicetag is added to all Lambda functions with the provided value. | |version | version | When set along with extensionLayerVersion or extensionLayerArn, a DD_VERSION environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, a versiontag is added to all Lambda functions with the provided value. | |tags | tags | A comma separated list of key:value pairs as a single string. When set along with extensionLayerVersion or extensionLayerArn, a DD_TAGS environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, the cdk parses the string and sets each key:value pair as a tag to all Lambda functions. | |enableColdStartTracing | enable_cold_start_tracing | Set to false to disable Cold Start Tracing. Used in Node.js and Python. Defaults to true. | |coldStartTraceMinDuration | min_cold_start_trace_duration | Sets the minimum duration (in milliseconds) for a module load event to be traced via Cold Start Tracing. Number. Defaults to 3. | |coldStartTraceSkipLibs | cold_start_trace_skip_libs| Optionally skip creating Cold Start Spans for a comma-separated list of libraries. Useful to limit depth or skip known libraries. Default depends on runtime. | |enableProfiling | enable_profiling | Enable the Datadog Continuous Profiler with true. Supported in Beta for Node.js and Python. Defaults to false. | |encodeAuthorizerContext | encode_authorizer_context | When set to true for Lambda authorizers, the tracing context will be encoded into the response for propagation. Supported for Node.js and Python. Defaults to true. | |decodeAuthorizerContext | decode_authorizer_context | When set to true for Lambdas that are authorized via Lambda authorizers, it will parse and use the encoded tracing context (if found). Supported for Node.js and Python. Defaults to true. | |apmFlushDeadline | apm_flush_deadline | Used to determine when to submit spans before a timeout occurs, in milliseconds. When the remaining time in an AWS Lambda invocation is less than the value set, the tracer attempts to submit the current active spans and all finished spans. Supported for Node.js and Python. Defaults to 100milliseconds. | |redirectHandler | redirect_handler | When set to false, skip redirecting handler to the Datadog Lambda Library's handler. Useful when only instrumenting with Datadog Lambda Extension. Defaults to true. | |grantSecretReadAccess | grant_secret_read_access | When set to true, and apiKeySecretArn or apiKeySsmArn is provided, automatically grant read access to the given secret or parameter to all the lambdas added. Defaults to true. | |llmObsEnabled | llm_obs_enabled | Toggle to enable submitting data to LLM Observability Defaults to false. | |llmObsMlApp | llm_obs_ml_app | The name of your LLM application, service, or project, under which all traces and spans are grouped. This helps distinguish between different applications or experiments. See Application naming guidelines for allowed characters and other constraints. To override this value for a given root span, see Tracing multiple applications. Required if llmObsEnabled is true| |llmObsAgentlessEnabled | llm_obs_agentless_enabled | Only required if you are not using the Datadog Lambda Extension, in which case this should be set to true. Defaults to false. |

#### Tracing

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

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

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

`typescript 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);

} }`

#### 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][10] and [CDK documentation][11].

#### Enable in-tracer App and API Protection

The [Datadog Lambda Library for Python][8] (version 8.114.0 or later) can run [App and API Protection][19] directly inside the instrumented application, giving the security engine additional context. This complements the in-extension implementation delivered by the [Datadog Lambda Extension][12]. appSecModeselects which implementation runs: -on: with pythonLayerVersion>=114on Python functions, App and API Protection runs within the library; other runtimes or manually-supplied libraries fall back to the extension. -tracer: always use the library implementation (every function must be in Python and use the Python library at version 8.114.0or newer). -extension: always use the extension implementation, even when a compatible library is detected. -off: disable App and API Protection entirely.

`$3`

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.

`typescript 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][17].

`$3`

The DatadogLambda construct takes in a list of lambda functions and installs the Datadog Lambda Library by attaching the Lambda Layers for [.NET][19], [Java][15], [Node.js][2], and [Python][1] 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.

`$3`

#### 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/v2" "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/v2" "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)`

`$3`

Parameters for creating the DatadogStepFunctions construct:

| npm package parameter | PyPI package parameter | Go package parameter | Description | | --------------------- | ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- | |env | env | Env | The envtag to be added to the state machine. | |service | service | Service | The servicetag to be added to the state machine. | |version | version | Version | The versiontag to be added to the state machine. | |forwarderArn | forwarder_arn | ForwarderArn| ARN or Datadog Forwarder, which will subscribe to the state machine's log group. | |tags | tags | Tags | A comma separated list of key:value pairs as a single string, which will be added to the state machine's tags. |

`$3`

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.env2.service3.version4.DD_TRACE_ENABLED: true. This enables tracing. 1. To disable tracing, set it tofalsefrom 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_constructversion tag 6. custom tags passed as thetags 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.

`$3`

#### 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][14]. - 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][13] for more details.

`Migrating from v2-1.x.x to v2-2.x.x`

In February 2025, Datadog released a major version update from 1.x.x to 2.x.x. The required changes to migrate to the new version are as follows:

1. Rename the classes for instrumenting Lambda functions:

1. Datadog -> DatadogLambda2.DatadogProps -> DatadogLambdaPropsFor examples, see the Usage section of this page and [examples/][20] folder of the GitHub repository.

2. Upgrade Node.js version to 18.18.0 or above.

3. For Go, change the import from:

`"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct"`

to:

`"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v2"`

`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. Runyarn watch, this will ensure the Typescript files in the src directory are compiled to Javascript in the libdirectory. 3. Navigate tosrc/sample, here you can edit index.tsto test your contributions manually. 4. At the root directory, runnpx 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.

`$3`

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.

[1]: https://github.com/DataDog/datadog-lambda-layer-python
[2]: https://github.com/DataDog/datadog-lambda-layer-js
[3]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html
[4]: https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.Stack.html
[5]: https://github.com/DataDog/datadog-lambda-python/releases
[6]: https://github.com/DataDog/datadog-lambda-js/releases
[7]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-subscriptionfilter.html
[8]: https://docs.datadoghq.com/account_management/api-app-keys/#api-keys
[9]: https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-lambda.Tracing.html
[10]: https://docs.aws.amazon.com/cdk/latest/guide/tagging.html
[11]: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html
[12]: https://docs.datadoghq.com/serverless/datadog_lambda_library/extension/
[13]: https://github.com/projen/projen
[14]: https://cdkworkshop.com/15-prerequisites.html
[15]: https://docs.datadoghq.com/serverless/installation/java/?tab=awscdk
[16]: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.ISecret.html
[17]: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.ISecret.html#grantwbrreadgrantee-versionstages
[18]: https://github.com/DataDog/dd-trace-dotnet-aws-lambda-layer/releases
[19]: https://docs.datadoghq.com/serverless/aws_lambda/installation/dotnet
[20]: https://github.com/DataDog/datadog-cdk-constructs/tree/main/examples
[21]: https://docs.datadoghq.com/security/application_security/
[22]: https://www.datadoghq.com/blog/troubleshoot-lambda-function-request-response-payloads/
[23]: https://github.com/DataDog/datadog-cdk-constructs/blob/main/src/ecs/fargate/README.md
[24]: https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/
[25]: https://docs.datadoghq.com/serverless/aws_lambda/installation/ruby
[26]: https://docs.datadoghq.com/serverless/aws_lambda/installation/go
[27]: https://github.com/DataDog/datadog-lambda-extension/releases

Datadog CDK Constructs

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

For more information on the DatadogECSFargate construct, see [here][23].

This CDK library automatically configures ingestion of metrics, traces, and logs from your serverless applications by:

Lambda

$3

#### npm

``yarn add --dev datadog-cdk-constructs-v2

`or`


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


#### PyPI

`pip install datadog-cdk-constructs-v2`

##### Note:

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

#### Go

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

#### Maven (Java)

Add to your pom.xml:

`xml com.datadoghq datadog-cdk-constructs 3.3.0`

`$3`

#### AWS CDK

Add this to your CDK stack:

#### TypeScript

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

#### Python

#### Go

#### Java

`java import com.datadoghq.cdkconstructs.DatadogLambda; import com.datadoghq.cdkconstructs.DatadogLambdaProps;

`$3`

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

- The Datadog Github integration is installed. - Yourdatadog-cdk-constructs-v2 version is >= 1.4.0

#### 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.


  datadog-cdk version satisfied, but Datadog Github integration NOT installed

`typescript const app = new cdk.App();

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

app.synth();`


  datadog-cdk version NOT satisfied

Change your initialization function as follows (in this case, gitHash value is passed to the CDK):

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

Ensure you call this function to initialize your stack.

In your stack constructor, change to add an optional gitHash parameter, and call addGitCommitMetadata():

`$3`

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.

#### Tracing

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

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

#### Nested Stacks

`typescript 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");

} }

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

} }`

#### Tags

#### Enable in-tracer App and API Protection

`$3`

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.

`typescript 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 ... });`

`$3`

`Step Functions`

Only AWS CDK v2 is supported.

`$3`

#### 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";

##### 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 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

##### 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

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/v2" "github.com/aws/aws-cdk-go/awscdk/v2" sfn "github.com/aws/aws-cdk-go/awscdk/v2/awsstepfunctions" )

##### 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:

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

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

`$3`

Parameters for creating the DatadogStepFunctions construct:

`$3`

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

`$3`

#### Log group already exists

If cdk deploy fails with an error like:

You have two options:

`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][14]. - CDK TypeScript Workshop - Video Introducing CDK by AWS with Demo - CDK Concepts

`Using Projen`

`Migrating from v2-1.x.x to v2-2.x.x`

In February 2025, Datadog released a major version update from 1.x.x to 2.x.x. The required changes to migrate to the new version are as follows:

1. Rename the classes for instrumenting Lambda functions:

1. Datadog -> DatadogLambda2.DatadogProps -> DatadogLambdaPropsFor examples, see the Usage section of this page and [examples/][20] folder of the GitHub repository.

2. Upgrade Node.js version to 18.18.0 or above.

3. For Go, change the import from:

`"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct"`

to:

`"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v2"`

`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:

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

`$3`

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.