datadog-cdk-constructs
Advanced tools
CDK Construct Library to automatically instrument Python and Node Lambda functions with Datadog
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:
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.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
For use with AWS CDK v2:
pip install datadog-cdk-constructs-v2
For use with AWS CDK v1:
pip install datadog-cdk-constructs
Pay attention to the output from your package manager as the Datadog CDK Construct Library has peer dependencies.
datadog-cdk-constructs rather than datadog-cdk-constructs-v2.Add this to your CDK stack:
# Example automatically generated from non-compiling source. May contain errors.
from datadog_cdk_constructs_v2 import Datadog
datadog = Datadog(self, "Datadog",
node_layer_version=<LAYER_VERSION>,
python_layer_version=<LAYER_VERSION>,
java_layer_version=<LAYER_VERSION>,
add_layers=<BOOLEAN>,
extension_layer_version="<EXTENSION_VERSION>",
forwarder_arn="<FORWARDER_ARN>",
create_forwarder_permissions=<BOOLEAN>,
flush_metrics_to_logs=<BOOLEAN>,
site="<SITE>",
api_key="{Datadog_API_Key}",
api_key_secret_arn="{Secret_ARN_Datadog_API_Key}",
api_key_secret=<AWS_CDK_ISECRET>, # Only available in datadog-cdk-constructs-v2
api_kms_key="{Encrypted_Datadog_API_Key}",
enable_datadog_tracing=<BOOLEAN>,
enable_merge_xray_traces=<BOOLEAN>,
enable_datadog_logs=<BOOLEAN>,
inject_log_context=<BOOLEAN>,
log_level=<STRING>,
env=<STRING>, # Optional
service=<STRING>, # Optional
version=<STRING>, # Optional
tags=<STRING>
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
datadog.add_forwarder_to_non_lambda_log_groups([<LOG_GROUPS>])
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.0datadog-cdk-constructs >= 0.8.5If 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.
If the Datadog Github Integration is not installed, you need to import the datadog-ci package and manually upload your Git metadata to Datadog.
We recommend you do this where your CDK Stack is initialized.
# Example automatically generated from non-compiling source. May contain errors.
app = cdk.App()
# Make sure to add @datadog/datadog-ci via your package manager
datadog_ci = require("@datadog/datadog-ci")
# Manually uploading Git metadata to Datadog.
datadog_ci.git_metadata.upload_git_commit_hash("{Datadog_API_Key}", "<SITE>")
app = cdk.App()
ExampleStack(app, "ExampleStack")
app.synth()
Change your initialization function as follows (note: we're changing this to pass just the gitHash value to the CDK):
# Example automatically generated from non-compiling source. May contain errors.
def main():
# Make sure to add @datadog/datadog-ci via your package manager
datadog_ci = require("@datadog/datadog-ci")
[, gitHash] = await datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')
app = cdk.App()
# Pass in the hash to the ExampleStack constructor
ExampleStack(app, "ExampleStack", {}, git_hash)
Ensure you call this function to initialize your stack.
In your stack constructor, change to add an optional gitHash parameter, and call addGitCommitMetadata():
# Example automatically generated from non-compiling source. May contain errors.
class ExampleStack(cdk.Stack):
def __init__(self, scope, id, props=None, git_hash=None):
datadog.add_git_commit_metadata([<YOUR_FUNCTIONS>], git_hash)
To further configure your Datadog construct, use the following custom parameters:
Note: The descriptions use the npm package parameters, but they also apply to the PyPI package parameters.
| npm package parameter | PyPI package parameter | Description |
|---|---|---|
addLayers | add_layers | Whether to add the 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 21. Required if you are deploying at least one Lambda function written in Python and addLayers is true. Find the latest version number here. |
nodeLayerVersion | node_layer_version | Version of the Node.js Lambda layer to install, such as 29. 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. |
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. Note: extensionLayerVersion >= 25 and javaLayerVersion >= 5 are required for the Datadog construct to instrument your Java functions properly. |
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 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. |
forwarderArn | forwarder_arn | When set, the plugin will automatically subscribe the Datadog Forwarder to the functions' log groups. Do not set forwarderArn when extensionLayerVersion is 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 or apiKeySecretArn). |
site | site | Set which Datadog site to send data. This is only used when flushMetricsToLogs is false or extensionLayerVersion is set. Possible values are datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.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 is set. For more information about getting a Datadog API key, see the API key documentation. |
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:GetSecretValue permission to the Lambda execution role. |
apiKeySecret | api_key_secret | An AWS CDK ISecret representing a secret storing the Datadog API key in AWS Secrets Manager. Use this parameter in place of apiKeySecretArn to 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 is 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. |
enableSourceCodeIntegration | enable_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, a DD_ENV environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, an env tag is added to all Lambda functions with the provided value. |
service | service | When set along with extensionLayerVersion, a DD_SERVICE environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, a service tag is added to all Lambda functions with the provided value. |
version | version | When set along with extensionLayerVersion, a DD_VERSION environment variable is added to all Lambda functions with the provided value. When set along with forwarderArn, a version tag 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, 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 NodeJS 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 NodeJS 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 NodeJS 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 NodeJS and Python. Defaults to true. |
apmFlushDeadline | 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 NodeJS and Python. Defaults to 100 milliseconds. | |
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. |
Note: Using the parameters above may override corresponding function level DD_XXX environment variables.
Enable X-Ray Tracing on your Lambda functions. For more information, see CDK documentation.
# Example automatically generated from non-compiling source. May contain errors.
import aws_cdk_lib.aws_lambda as lambda_
lambda_function = lambda_.Function(self, "HelloHandler",
runtime=lambda_.Runtime.NODEJS_14_X,
code=lambda_.Code.from_asset("lambda"),
handler="hello.handler",
tracing=lambda_.Tracing.ACTIVE
)
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 from non-compiling source. May contain errors.
from datadog_cdk_constructs_v2 import Datadog
import aws_cdk_lib as cdk
from constructs import Construct
class RootStack(cdk.Stack):
def __init__(self, scope, id, props=None):
super().__init__(scope, id, props)
NestedStack(self, "NestedStack")
datadog = Datadog(self, "Datadog",
node_layer_version=<LAYER_VERSION>,
python_layer_version=<LAYER_VERSION>,
java_layer_version=<LAYER_VERSION>,
add_layers=<BOOLEAN>,
forwarder_arn="<FORWARDER_ARN>",
flush_metrics_to_logs=<BOOLEAN>,
site="<SITE>",
api_key="{Datadog_API_Key}",
api_key_secret_arn="{Secret_ARN_Datadog_API_Key}",
api_kms_key="{Encrypted_Datadog_API_Key}",
enable_datadog_tracing=<BOOLEAN>,
enable_merge_xray_traces=<BOOLEAN>,
enable_datadog_logs=<BOOLEAN>,
inject_log_context=<BOOLEAN>
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
class NestedStack(cdk.NestedStack):
def __init__(self, scope, id, props=None):
super().__init__(scope, id, props)
datadog = Datadog(self, "Datadog",
node_layer_version=<LAYER_VERSION>,
python_layer_version=<LAYER_VERSION>,
java_layer_version=<LAYER_VERSION>,
add_layers=<BOOLEAN>,
forwarder_arn="<FORWARDER_ARN>",
flush_metrics_to_logs=<BOOLEAN>,
site="<SITE>",
api_key="{Datadog_API_Key}",
api_key_secret_arn="{Secret_ARN_Datadog_API_Key}",
api_kms_key="{Encrypted_Datadog_API_Key}",
enable_datadog_tracing=<BOOLEAN>,
enable_merge_xray_traces=<BOOLEAN>,
enable_datadog_logs=<BOOLEAN>,
inject_log_context=<BOOLEAN>
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
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.
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 Datadog 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 datadog = new Datadog(this, 'Datadog', {
...
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.
The Datadog CDK construct takes in a list of lambda functions and installs the Datadog Lambda Library by attaching the Lambda Layers for 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.
In this repository, the folders v1 and v2 correspond to the packages datadog-cdk-constructs and datadog-cdk-contructs-v2. Each can be treated as a separate project (they are separate projen projects with separate dependencies, config files, tests, and scripts).
Additionally, there is a common folder that contains shared logic common to both v1 and v2 packages. This is done by soft-linking a common folder within v1/src and v2/src to the common folder in the root of the repository.
The v1 and v2 Datadog CDK Construct Libraries both 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 within v1 or v2 folders, then run npx projen (while in v1 or v2) to synthesize the new changes. Check out Projen for more details.
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.
If you find an issue with this package and have a fix, please feel free to open a pull request following the procedures.
If you contribute to this package you can run the tests using yarn test within the v1 or v2 folders. This package also includes a sample application for manual testing:
cd into v1 or v2.yarn watch, this will ensure the Typescript files in the src directory are compiled to Javascript in the lib directory.src/sample, here you can edit index.ts to test your contributions manually.v1 or v2 directory (whichever you are working on), run npx cdk --app lib/sample/index.js <CDK Command>, replacing <CDK Command> with common CDK commands like synth, diff, or deploy.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 the root of the v1 or v2 directory
DD_CONSTRUCT_DEBUG_LOGS=true npx cdk --app lib/sample/index.js synth --quiet
For product feedback and questions, join the #serverless channel in the Datadog community on Slack.
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.
FAQs
CDK Construct Library to automatically instrument Python and Node Lambda functions with Datadog
We found that datadog-cdk-constructs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.