Logging using CloudWatch Logs - Amazon Step Functions
Configure loggingCloudWatch Logs payloadsIAM Policies for logging to CloudWatch Logs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Logging using CloudWatch Logs

Standard Workflows record execution history in Amazon Step Functions, although you can optionally configure logging to Amazon CloudWatch Logs.

Unlike Standard Workflows, Express Workflows don't record execution history in Amazon Step Functions. To see execution history and results for an Express Workflow, you must configure logging to Amazon CloudWatch Logs. Publishing logs doesn't block or slow down executions.

Note

When you configure logging, CloudWatch Logs charges will apply and you will be billed at the vended logs rate. For more information, see Vended Logs under the Logs tab on the CloudWatch Pricing page.

Configure logging

When you create a Standard Workflow using the Step Functions console, it will not be configured to enable logging to CloudWatch Logs. An Express Workflow created using the Step Functions console will by default be configured to enable logging to CloudWatch Logs.

For Express workflows, Step Functions can create a role with the necessary Amazon Identity and Access Management (IAM) policy for CloudWatch Logs. If you create a Standard Workflow, or an Express Workflow using the API, CLI, or Amazon CloudFormation, Step Functions will not enable logging by default, and you will need ensure your role has the necessary permissions.

For each execution started from the console, Step Functions provides a link to CloudWatch Logs, configured with the correct filter to fetch log events specific for that execution.

To configure logging, you can pass the LoggingConfiguration parameter when using CreateStateMachine or UpdateStateMachine. You can further analyze your data in CloudWatch Logs by using CloudWatch Logs Insights. For more information see Analyzing Log Data with CloudWatch Logs Insights.

CloudWatch Logs payloads

Execution history events may contain either input or output properties in their definitions. If escaped input or escaped output sent to CloudWatch Logs exceeds 248KB, it will be truncated as a result of CloudWatch Logs quotas.

IAM Policies for logging to CloudWatch Logs

You will also need to configure your state machine's execution IAM role to have the proper permission to log to CloudWatch Logs as shown in the following example.

IAM policy example

The following is an example policy you can use to configure your permissions. As shown in the following example, you need to specify * in the Resource field because CloudWatch API actions, such as CreateLogDelivery and DescribeLogGroups, don't support Resource types defined by Amazon CloudWatch Logs. For more information, see Actions defined by Amazon CloudWatch Logs.

  • For information about CloudWatch resources, see CloudWatch Logs resources and operations in the Amazon CloudWatch User Guide.

  • For information about the permissions you need to set up sending logs to CloudWatch Logs, see User permissions in the section titled Logs sent to CloudWatch Logs.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogDelivery",
                "logs:CreateLogStream",
                "logs:GetLogDelivery",
                "logs:UpdateLogDelivery",
                "logs:DeleteLogDelivery",
                "logs:ListLogDeliveries",
                "logs:PutLogEvents",
                "logs:PutResourcePolicy",
                "logs:DescribeResourcePolicies",
                "logs:DescribeLogGroups"
            ],
            "Resource": "*"
        }
    ]
}
Unable to access the CloudWatch Logs

If you're unable to access the CloudWatch Logs, make sure you've done the following:

  1. Configured your state machine's execution IAM role to have the proper permission to log to CloudWatch Logs.

    If you're using the CreateStateMachine or UpdateStateMachine requests, make sure you've specified the IAM role in the roleArn parameter containing the permissions as shown in the preceding example.

  2. Checked the CloudWatch Logs resource policy doesn't exceed the 5120 character limit for CloudWatch Logs resource policies.

    If you've exceeded the character limit, remove unnecessary permissions from the CloudWatch Logs resource policy, or prefix the log group name with /aws/vendedlogs, which will grant permissions to the log group without appending more characters to the resource policy. When you create a log group in the Step Functions console, the log group names are prefixed with /aws/vendedlogs/states. For more information, see Amazon CloudWatch Logs resource policy size restrictions.