--- title: Install Serverless Monitoring for AWS Step Functions description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Serverless > Serverless Monitoring for AWS Step Functions > Install Serverless Monitoring for AWS Step Functions --- # Install Serverless Monitoring for AWS Step Functions ### Requirements{% #requirements %} - The full Step Function execution length must be less than 6 hours for full traces. ### How it works{% #how-it-works %} AWS Step Functions is a fully managed service, and the Datadog Agent cannot be directly installed on Step Functions. However, Datadog can monitor Step Functions through Cloudwatch metrics and logs. Datadog collects Step Functions metrics from Cloudwatch through the [AWS Step Functions integration](https://docs.datadoghq.com/integrations/amazon_step_functions). Datadog collects Step Functions logs from Cloudwatch through one of the following: - [Datadog Forwarder](https://docs.datadoghq.com/logs/guide/forwarder). For instructions, see the Setup section on this page. - Amazon Data Firehose. For instructions, see [Send AWS service logs to the Datadog Amazon Data Firehose destination](https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-kinesis-firehose-destination). Datadog uses these ingested logs to generate [enhanced metrics](https://docs.datadoghq.com/serverless/step_functions/enhanced-metrics) and traces for your Step Function executions. {% image source="https://datadog-docs.imgix.net/images/serverless/step_functions/telemetry_ingestion.328f637e5963ffffed527ccb913b0340.png?auto=format" alt="A diagram explaining how Step Functions telemetry is ingested and used in Datadog" /%} ## Setup{% #setup %} Ensure that the [AWS Step Functions integration](https://docs.datadoghq.com/integrations/amazon_step_functions) is installed. Then, to send your Step Functions logs to Datadog: {% tab title="Custom (Terraform)" %} 1. Enable all logging for your Step Function. In your AWS console, open your state machine. Click *Edit* and find the Logging section. There, set *Log level* to `ALL` and enable the *Include execution data* checkbox. {% image source="https://datadog-docs.imgix.net/images/serverless/step_functions/aws_log.5c906764f2df5c891ee719b4a94c5607.png?auto=format" alt="AWS UI, Logging section, showing log level set to ALL." /%} 1. Ensure you have deployed the [Datadog Lambda Forwarder](https://docs.datadoghq.com/logs/guide/forwarder), and that you are using v3.130.0 or later. As an alternative, you may also use [Amazon Data Firehose](https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-kinesis-firehose-destination), which can subscribe to Amazon CloudWatch log groups across multiple AWS regions. However, it requires that the Step Functions log group name begins with "/aws/vendedlogs/states/". 1. Subscribe CloudWatch logs to the Datadog Lambda Forwarder. If the log group name for your Step Functions begins with "/aws/vendedlogs/states/", you can also use the [Serverless Framework or the Datadog CLI to configure the subscription](https://docs.datadoghq.com/serverless/step_functions/merge-step-functions-lambda). Automatic custom installation: 1. Ensure that you have set up the [Datadog-AWS integration](https://docs.datadoghq.com/getting_started/integrations/aws/). 1. In Datadog, open the [AWS integration tile](https://app.datadoghq.com/integrations/aws), and view the *Configuration* tab. 1. On the left, select the AWS account where your Step Function is running. Open the *Log Collection* tab. 1. In the *Log Autosubscription* section, under *Autosubscribe Forwarder Lambda Functions*, enter the ARN of your Datadog Lambda Forwarder, as noted previously. Click *Add*. 1. Toggle on *Step Functions CloudWatch Logs*. Changes take 15 minutes to take effect. **Note**: Log Autosubscription requires your Lambda Forwarder and Step Function to be in the same region. Manual custom installation: 1. Open your AWS console and go to your Datadog Lambda Forwarder. In the *Function overview* section, click on *Add trigger*. 1. Under *Add trigger*, in the *Trigger configuration* section, use the *Select a source* dropdown to select `CloudWatch Logs`. 1. Under *Log group*, select the log group for your state machine. For example, `/aws/vendedlogs/states/my-state-machine`. 1. Enter a filter name. You can choose to name it "empty filter" and leave the *Filter pattern* box blank. 1. Set up tags. Open your AWS console and go to your Step Functions state machine. Open the *Tags* section and add `env:`, `service:`, and `version:` tags. The `env` tag is required to see traces in Datadog, and it defaults to `dev`. The `service` tag defaults to the state machine's name. The `version` tag defaults to `1.0`. 1. To enable tracing, you have two options: - **Per Step Function**: Add the `DD_TRACE_ENABLED` tag to each Step Function and set the value to `true`. - **At the Forwarder level**: To enable tracing for all Step Functions connected to the Forwarder, you have two options: - When creating the CloudFormation stack for the forwarder, set the `DdStepFunctionsTraceEnabled` parameter to `true`. - After the forwarder is created, set the environment variable `DD_STEP_FUNCTIONS_TRACE_ENABLED` to `true`. {% /tab %} {% tab title="Datadog CI" %} 1. If you haven't already, install the [Datadog CLI](https://docs.datadoghq.com/serverless/libraries_integrations/cli/) v2.18.0+. ```shell npm install -g @datadog/datadog-ci @datadog/datadog-ci-plugin-stepfunctions ``` 1. Ensure you have deployed the [Datadog Lambda Forwarder](https://docs.datadoghq.com/logs/guide/forwarder), and that you are using v3.130.0 or later. As an alternative, you can also use [Amazon Data Firehose](https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-kinesis-firehose-destination), which can subscribe to Amazon CloudWatch log groups across multiple AWS regions. Your Step Functions log group name should use this format: ``` /aws/vendedlogs/states/-Logs ``` **Optionally**, you can add your environment to this log group name: `/aws/vendedlogs/states/-Logs-` Take note of your Forwarder's ARN. 1. Run: ```shell datadog-ci stepfunctions instrument \ --step-function \ --forwarder \ --env \ --propagate-upstream-trace \ --merge-step-function-and-lambda-traces ``` - Replace `` with the ARN of your Step Function. Repeat the `--step-function` flag for each Step Function you wish to instrument. - Replace `` with the ARN of your Datadog Lambda Forwarder. This step configures the log stream subscription for the Forwarder. - Replace `` with the environment tag you would like to apply to your Step Functions. For more information about the `datadog-ci stepfunctions` command, see the [Datadog CLI documentation](https://github.com/DataDog/datadog-ci/tree/master/packages/plugin-stepfunctions#readme). **Note**: The `datadog-ci stepfunctions instrument` command automatically enables tracing. {% /tab %} {% tab title="Serverless Plugin" %} 1. If you haven't already, install the [Datadog Serverless Framework Plugin](https://docs.datadoghq.com/serverless/libraries_integrations/plugin/) v5.40.0+: ```shell serverless plugin install --name serverless-plugin-datadog ``` 1. Ensure you have deployed the [Datadog Lambda Forwarder](https://docs.datadoghq.com/logs/guide/forwarder), and that you are using v3.130.0 or later. As an alternative, you can also use [Amazon Data Firehose](https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-kinesis-firehose-destination), which can subscribe to Amazon CloudWatch log groups across multiple AWS regions. Your Step Functions log group name should use this format: ``` /aws/vendedlogs/states/-Logs- ``` 1. Add the following to your `serverless.yml`: ```yaml custom: datadog: site: apiKeySecretArn: forwarderArn: enableStepFunctionsTracing: true propagateUpstreamTrace: true mergeStepFunctionAndLambdaTraces: true ``` - Replace `` with (ensure the correct DATADOG SITE is selected on the right of this docs page). - Replace `` with the ARN of the AWS secret where your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. - Replace `` with the ARN of your Datadog Lambda Forwarder. This step configures the log stream subscription for the Forwarder. For additional settings, see [Datadog Serverless Framework Plugin - Configuration parameters](https://github.com/datadog/serverless-plugin-datadog?tab=readme-ov-file#configuration-parameters). **Note**: The `enableStepFunctionsTracing: true` line automatically enables tracing. {% /tab %} {% tab title="AWS CDK" %} 1. Ensure you have deployed the [Datadog Lambda Forwarder](https://docs.datadoghq.com/logs/guide/forwarder), and that you are using v3.130.0 or later. 1. Install [Datadog's CDK Construct Library](https://github.com/DataDog/datadog-cdk-constructs), which automatically sets up logging and subscribes the Forwarder to the log group. **Example** ```python 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]) ``` For sample stacks and additional code examples, see [CDK Examples for Instrumenting AWS Step Functions](https://docs.datadoghq.com/serverless/guide/step_functions_cdk). **Note**: The Datadog Step Functions CDK construct automatically enables tracing. {% /tab %} {% tab title="AWS SAM" %} 1. Ensure you have deployed the [Datadog Lambda Forwarder](https://docs.datadoghq.com/logs/guide/forwarder), and that you are using v3.130.0 or later. 1. Add the following to your `template.yaml`: ```yaml Transform: - AWS::Serverless-2016-10-31 - Name: DatadogServerless Parameters: stackName: !Ref "AWS::StackName" apiKey: "" env: "" # e.g. "dev" service: "" # e.g. "my-sam-service" version: "" # e.g. "1.0.0" stepFunctionForwarderArn: "" # "arn:test:forwarder:sa-east-1:12345678:1" tags: "" # optional, e.g. "custom-tag-1:tag-value-1,custom-tag-2:tag-value-2" ``` For additional settings, [see the documentation on GitHub](https://github.com/DataDog/datadog-cloudformation-macro/blob/main/serverless/README.md). {% /tab %} **Do not set** the following environment variables in your serverless environment. They should only be set in non-serverless environments. - `DD_AGENT_HOST` - `DD_TRACE_AGENT_URL` {% alert level="info" %} Enhanced metrics are automatically enabled if you enable tracing. Therefore, if tracing is enabled, you are billed for both Serverless Workload Monitoring and Serverless APM. See [Pricing](https://www.datadoghq.com/pricing/?product=serverless-monitoring#products). {% /alert %} ## Additional options for instrumentation{% #additional-options-for-instrumentation %} ### Merge Step Functions with AWS Lambda traces{% #merge-step-functions-with-aws-lambda-traces %} See [Merge Step Functions traces with Lambda traces](https://docs.datadoghq.com/serverless/step_functions/merge-step-functions-lambda). Ensure that you have also [set up Serverless Monitoring for AWS Lambda](https://docs.datadoghq.com/serverless/aws_lambda/installation). ### Sample traces{% #sample-traces %} To manage the APM traced invocation sampling rate for serverless functions, set the `DD_TRACE_SAMPLE_RATE` environment variable on the function to a value between 0.00 (no tracing of Step Function invocations) and 1.00 (trace all Step Function invocations). The dropped traces are not ingested into Datadog. ### Enable enhanced metrics (without tracing){% #enable-enhanced-metrics-without-tracing %} Datadog generates [enhanced metrics](https://docs.datadoghq.com/serverless/step_functions/enhanced-metrics) from collected Cloudwatch logs. Enhanced metrics are automatically enabled if you enable traces. To enable enhanced metrics without enabling tracing, add a `DD_ENHANCED_METRICS` tag to each of your Step Functions and set the value to `true`. {% alert level="info" %} If you enable enhanced metrics without enabling traces, you are only billed for Serverless Workload Monitoring. If you enable tracing (which automatically includes enhanced metrics), you are billed for both Serverless Workload Monitoring and Serverless APM. See [Pricing](https://www.datadoghq.com/pricing/?product=serverless-monitoring#products). {% /alert %} ## See your Step Function metrics, logs, and traces in Datadog{% #see-your-step-function-metrics-logs-and-traces-in-datadog %} After you have invoked your state machine, go to the [**Serverless app**](https://app.datadoghq.com/functions?search=&cloud=aws&entity_view=step_functions) in Datadog. Search for `service:` to see the relevant metrics, logs, and traces associated with that state machine. If you set the `service` tag on your state machine to a custom value, search for `service:`. {% image source="https://datadog-docs.imgix.net/images/serverless/step_functions/overview1.9f81e6f595801730f013117e918a39cb.png?auto=format" alt="An AWS Step Function side panel view." /%} If you cannot see your traces, see [Troubleshooting](https://docs.datadoghq.com/serverless/step_functions/troubleshooting).