Datadog recommends the Serverless CloudFormation macro for customers using AWS SAM to deploy their serverless applications.

The macro automatically configures ingestion of metrics, traces, and logs from your serverless applications by:

• Installing and configuring the Datadog Lambda Library and Lambda Extension for your Python, Node.js, .NET, and Java Lambda functions.
• Enabling the collection of enhanced Lambda metrics and custom metrics from your Lambda functions.
• Managing subscriptions from the Datadog Forwarder to your Lambda function log groups, if desired.

Installation

To make the Datadog serverless macro available for use in your AWS account, deploy a CloudFormation stack with a Datadog-provided template. This deployment includes a CloudFormation macro resource and a Lambda function that is invoked when the macro is run. Deploying this stack enables you to use the macro on other CloudFormation stacks deployed in the same account. For more details about defining a macro in your account, see the CloudFormation documentation page.

Note: The Datadog serverless macro needs to be created once in each region that contains stacks you wish to transform.

Option 1: AWS Console

Create the Datadog serverless macro stack in your AWS account using the Launch Stack template link above.

Option 2: AWS CLI

If you are installing for the first time, deploy with:

aws cloudformation create-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

Usage with AWS SAM

To deploy your serverless application with SAM, add the Datadog Serverless CloudFormation macro under the Transform section in your template.yml file, after the required SAM transform. Also add a DDGitData parameter and pass it to the macro to enable Datadog Source Code Integration:

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      apiKey: "<DATADOG_API_KEY>"
      pythonLayerVersion: "<LAYER_VERSION>" # Use appropriate parameter for other runtimes
      extensionLayerVersion: "<LAYER_VERSION>"
      service: "<SERVICE>" # Optional
      env: "<ENV>" # Optional
      version: "<VERSION>" # Optional
      tags: "<TAGS>" # Optional
      # Pass DDGitData here to enable Source Code Integration tagging
      gitData: !Ref DDGitData
      # For additional parameters, see the Configuration section

Parameters:
  DDGitData:
    Type: String
    Default: ""
    Description: "The output of $(git rev-parse HEAD),$(git config --get remote.origin.url). Used for Datadog Source Code Integration tagging"

To set the DDGitData parameter for Datadog’s Source Code Integration, use SAM’s --parameter-overrides option:

sam deploy --parameter-overrides  DDGitData="$(git rev-parse HEAD),$(git config --get remote.origin.url)"

Note: If you did not modify the provided template.yml file when you installed the macro, then the name of the macro defined in your account will be DatadogServerless. If you have modified the original template, make sure the name of the transform you add here matches the Name property of the AWS::CloudFormation::Macro resource.

Note: If you want to specify some of the configuration only once, you can modify template.yml and add the environment variables you want to configure for that region. This is a way to control additional default values. The example below sets DD_API_KEY_SECRET_ARN and DD_ENV, which the macro will treats as default values:

Resources:
  MacroFunction:
    Type: AWS::Serverless::Function
    DependsOn: MacroFunctionZip
    Properties:
      FunctionName:
        Fn::If:
          - SetFunctionName
          - Ref: FunctionName
          - Ref: AWS::NoValue
      Description: Processes a CloudFormation template to install Datadog Lambda layers for Lambda functions.
      Handler: src/index.handler
      ...
      Environment:
        Variables:
          DD_API_KEY_SECRET_ARN: "arn:aws:secretsmanager:us-west-2:123456789012:secret:DdApiKeySecret-e1v5Yn7TvIPc-d1Qc4E"
          DD_ENV: "dev"

Updating

If you are updating the macro after a new release, use the update-stack method:

aws cloudformation update-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

You may also specify a version of the macro from the latest releases by replacing latest.yml with the release version, e.g. 0.1.2.yml.

Configuration

To further configure your macro, use the following custom parameters:

How it works

This macro modifies your CloudFormation template to install the Datadog Lambda Library by attaching the Lambda Layers for Node.js, Python, .NET, and Java to your functions. It redirects to a replacement handler that initializes the Lambda Library without any required code changes.

Troubleshooting

Debug Logs

In order to help debug issues, you can look at the CloudWatch Logs for the macro Lambda function. To find the CloudWatch logs:

• Find the macro CloudFormation stack (named datadog-serverless-macro if you copied the command under instructions)
• Click on the resources tab and the CloudWatch Log Group should be available with Logical ID MacroFunctionLogGroup

Error message: ‘FunctionName’ property is undefined for…

This error occurs when you provide a forwarderArn and are deploying your Lambda function for the first time, so no log group currently exists, and the macro cannot create this log group or subscribe to the Forwarder for you. One way to fix this issue is to explicitly define the FunctionName property on your Lambda (see the example below).

Resources:
  MyLambda:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs12.x
      FunctionName: MyFunctionName # Add this property to your Lambdas

If you cannot (or prefer not) define the FunctionName explicitly, then remove the forwarderArn parameter from the SAM template or CDK source code, and instead define the subscription filters using the AWS::Logs::SubscriptionFilter resource like below.

Resources:
  MyLogSubscriptionFilter:
    Type: "AWS::Logs::SubscriptionFilter"
    Properties:
      DestinationArn: "<DATADOG_FORWARDER_ARN>"
      LogGroupName: "<CLOUDWATCH_LOG_GROUP_NAME>"
      FilterPattern: ""

Error message: ’logGroupNamePrefix’ failed to satisfy constraint…

The forwarderArn option does not work when FunctionName contains CloudFormation functions, such as !Sub. In this case, the macro does not have access to the actual function name (CloudFormation executes functions after transformations). It therefore cannot create log groups and subscription filters for your functions.

Remove the forwarderArn parameter from the SAM template or CDK source code, and instead define the subscription filters using the AWS::Logs::SubscriptionFilter resource like below.

Resources:
  MyLogSubscriptionFilter:
    Type: "AWS::Logs::SubscriptionFilter"
    Properties:
      DestinationArn: "<DATADOG_FORWARDER_ARN>"
      LogGroupName: "<CLOUDWATCH_LOG_GROUP_NAME>"
      FilterPattern: ""

Error message: ‘Failed to execute transform DatadogServerless’

This error can occur if the IAM user executing the command lacks the lambda:InvokeFunction permission. Add the permission to the user’s IAM role.

Setting up X-Ray tracing using a predefined Lambda execution role

Complete the following steps to enable X-Ray tracing when using a predefined Lambda execution role (such as one created outside the CloudFormation template, like this example):

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Role: !Sub arn:aws:iam::${AWS::AccountId}:role/PredefinedRole

1. Set the enableXrayTracing option to true for the macro.
2. Add this inline policy to your Lambda execution role:

{
	"Version": "2012-10-17",
	"Statement": {
		"Action": [
			"xray:PutTraceSegments",
			"xray:PutTelemetryRecords"
		],
		"Resource": [
			"*"
		],
		"Effect": "Allow"
	}
}

Community

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