Instrumenting Python Applications
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Instrumenting Python Applications

After you have installed the AWS integration and the Datadog Forwarder, choose one of the following methods to instrument your application to send metrics, logs, and traces to Datadog.

Configuration

The Datadog Serverless Plugin automatically adds the Datadog Lambda library to your functions using layers, and configures your functions to send metrics, traces, and logs to Datadog through the Datadog Forwarder.

To install and configure the Datadog Serverless Plugin, follow these steps:

  1. Install the Datadog Serverless Plugin:

    yarn add --dev serverless-plugin-datadog
  2. In your serverless.yml, add the following:

    plugins:
      - serverless-plugin-datadog
  3. In your serverless.yml, also add the following section:

    custom:
      datadog:
        flushMetricsToLogs: true
        forwarder: # The Datadog Forwarder ARN goes here.

    More information on the Datadog Forwarder ARN or installation can be found here. For additional settings, see the plugin documentation.

This service is in public beta. If you have any feedback, contact Datadog support.

The Datadog CloudFormation macro automatically transforms your SAM application template to add the Datadog Lambda library to your functions using layers, and configure your functions to send metrics, traces, and logs to Datadog through the Datadog Forwarder.

Install the Datadog CloudFormation Macro

Run the following command with your AWS credentials to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro once for a given region in your account. Replace create-stack with update-stack to update the macro to the latest version.

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

The macro is now deployed and ready to use.

Instrument the Function

In your template.yml, add the following under the Transform section, after the AWS::Serverless transform for SAM.

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      pythonLayerVersion: "<LAYER_VERSION>"
      stackName: !Ref "AWS::StackName"
      forwarderArn: "<FORWARDER_ARN>"
      service: "<SERVICE>" # Optional
      env: "<ENV>" # Optional

Replace <SERVICE> and <ENV> with appropriate values, <LAYER_VERSION> with the desired version of Datadog Lambda layer (see the latest releases), and <FORWARDER_ARN> with Forwarder ARN (see the Forwarder documentation).

More information and additional parameters can be found in the macro documentation.

This service is in public beta. If you have any feedback, contact Datadog support.

The Datadog CloudFormation macro automatically transforms the CloudFormation template generated by the AWS CDK to add the Datadog Lambda library to your functions using layers, and configure your functions to send metrics, traces, and logs to Datadog through the Datadog Forwarder.

Install the Datadog CloudFormation Macro

Run the following command with your AWS credentials to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro once for a given region in your account. Replace create-stack with update-stack to update the macro to the latest version.

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

The macro is now deployed and ready to use.

Instrument the Function

Add the DatadogServerless transform and the CfnMapping to your Stack object in your AWS CDK app. See the sample code below in Python (the usage in other language should be similar).

from aws_cdk import core

class CdkStack(core.Stack):
  def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
    super().__init__(scope, id, **kwargs)
    self.add_transform("DatadogServerless")

    mapping = core.CfnMapping(self, "Datadog",
      mapping={
        "Parameters": {
          "pythonLayerVersion": "<LAYER_VERSION>",
          "forwarderArn": "<FORWARDER_ARN>",
          "stackName": self.stackName,
          "service": "<SERVICE>",  # Optional
          "env": "<ENV>",  # Optional
        }
      })

Replace <SERVICE> and <ENV> with appropriate values, <LAYER_VERSION> with the desired version of Datadog Lambda layer (see the latest releases), and <FORWARDER_ARN> with Forwarder ARN (see the Forwarder documentation).

More information and additional parameters can be found in the macro documentation.

Update the Zappa Settings

  1. Add the following settings to your zappa_settings.json:

    {
        "dev": {
            "layers": ["arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>"],
            "lambda_handler": "datadog_lambda.handler.handler",
            "aws_environment_variables": {
                "DD_LAMBDA_HANDLER": "handler.lambda_handler",
                "DD_TRACE_ENABLED": "true",
                "DD_FLUSH_TO_LOG": "true",
            },
        }
    }
  2. Replace the placeholder <AWS_REGION>, <RUNTIME> and <VERSION> in the layer ARN with appropriate values. The available RUNTIME options are Python27, Python36, Python37, and Python38. For VERSION, see the latest release. For example:

    # For regular regions
    arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python37:19
        
    # For us-gov regions
    arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python37:19

Subscribe the Datadog Forwarder to the Log Groups

You need to subscribe the Datadog Forwarder Lambda function to each of your function’s log groups, to send metrics, traces, and logs to Datadog.

  1. Install the Datadog Forwarder if you haven’t.
  2. Ensure the option DdFetchLambdaTags is enabled.
  3. Subscribe the Datadog Forwarder to your function’s log groups.
This service is in public beta. If you have any feedback, contact Datadog support.

Use the Datadog CLI to set up instrumentation on your Lambda functions in your CI/CD pipelines. The CLI command automatically adds the Datadog Lambda library to your functions using layers, and configures your functions to send metrics, traces, and logs to Datadog.

Install the Datadog CLI

Install the Datadog CLI with NPM or Yarn:

# NPM
npm install -g @datadog/datadog-ci

# Yarn
yarn global add @datadog/datadog-ci

Instrument the Function

Run the following command with your AWS credentials. Replace <functionname> and <another_functionname> with your Lambda function names, <aws_region> with the AWS region name, <layer_version> with the desired version of the Datadog Lambda layer (see latest releases) and <forwarder_arn> with Forwarder ARN (see the Forwarder documentation).

datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v <layer_version> --forwarder	<forwarder_arn>

For example:

datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 19 --forwarder arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder

More information and additional parameters can be found in the CLI documentation.

Install the Datadog Lambda Library

You can either install the Datadog Lambda library as a layer (recommended) or as a Python package.

The minor version of the datadog-lambda package always matches the layer version. E.g., datadog-lambda v0.5.0 matches the content of layer version 5.

Using the Layer

Configure the layers for your Lambda function using the ARN in the following format:

# For regular regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>

# For us-gov regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:<VERSION>

The available RUNTIME options are Python27, Python36, Python37, and Python38. For VERSION, see the latest release. For example:

arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python37:19

Using the Package

Install datadog-lambda and its dependencies locally to your function project folder. Note: datadog-lambda depends on ddtrace, which uses native extensions; therefore they must be installed and compiled in a Linux environment. For example, you can use dockerizePip for the Serverless Framework and –use-container for AWS SAM. For more details, see how to add dependencies to your function deployment package.

pip install datadog-lambda -t ./

See the latest release.

Configure the Function

  1. Set your function’s handler to datadog_lambda.handler.handler.
  2. Set the environment variable DD_LAMBDA_HANDLER to your original handler, for example, myfunc.handler.
  3. Set the environment variable DD_TRACE_ENABLED to true.
  4. Set the environment variable DD_FLUSH_TO_LOG to true.
  5. Optionally add a service and env tag with appropriate values to your function.

Subscribe the Datadog Forwarder to the Log Groups

You need to subscribe the Datadog Forwarder Lambda function to each of your function’s log groups, to send metrics, traces, and logs to Datadog.

  1. Install the Datadog Forwarder if you haven’t.
  2. Ensure the option DdFetchLambdaTags is enabled.
  3. Subscribe the Datadog Forwarder to your function’s log groups.

Explore Datadog Serverless Monitoring

After you have configured your function following the steps above, you can view metrics, logs and traces on the Serverless Homepage.

Monitor Custom Business Metrics

If you would like to submit a custom metric or manually instrument a function, see the sample code below:

from ddtrace import tracer
from datadog_lambda.metric import lambda_metric

def lambda_handler(event, context):
    # submit a custom metric
    lambda_metric(
        "coffee_house.order_value",  # metric name
        12.45,  # metric value
        tags=['product:latte', 'order:online']  # tags
    )
    return {
        "statusCode": 200,
        "body": get_message()
    }

# submit a custom span
@tracer.wrap()
def get_message():
    return "Hello from serverless!"

Enable custom metric submission to get started.

Enable the AWS X-Ray Integration

Datadog’s integration with AWS X-Ray allows you to visualize end-to-end serverless transactions, so you can zero in on the source of any errors or slowdowns, and see how the performance of your functions impacts your users’ experience. Depending on your language and configuration, choose between setting up Datadog APM or the AWS X-Ray integration for your tracing needs.