Enable transaction search - Amazon CloudWatch
Enabling Transaction Search in the consoleEnabling Transaction Search using an API

Enable transaction search

You can enable Transaction Search through the console or by using an API. Transaction search is configured for the entire account and switches all spans ingestion through X-Ray into cost effective collection mode using Amazon CloudWatch Pricing. By default you will also index 1% of ingested spans for free as trace summary for analysis, which is typically sufficient given you already have full end-to-end trace visibility on all ingested spans through Transaction Search.

Enabling Transaction Search in the console

The following procedure describes how to enable Transaction Search in the console.

To enable Transaction Search in the CloudWatch console

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. From the navigation pane, under Application Signals, choose Transaction Search.

  3. Choose Enable Transaction Search.

  4. Select the box to ingest spans as structured logs, and enter a percentage of spans to be indexed. You can index spans at 1% for free and change the percentage later based on your requirements.

Enabling Transaction Search using an API

The following procedure describes how to enable Transaction Search using an API.

Step 1. Create a policy that grants access to ingest spans in CloudWatch Logs

When using the AWS CLI or SDK to enable Transaction Search, you must configure permissions using a resource-based policy with PutResourcePolicy.

Example policy

The following example policy allows X-Ray to send traces to CloudWatch Logs

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "TransactionSearchXRayAccess",
            "Effect": "Allow",
            "Principal": {
                "Service": "xray.amazonaws.com"
            },
            "Action": "logs:PutLogEvents",
            "Resource": [
                "arn:aws:us-east-1:123456789012account-id:log-group:aws/spans:*",
    "arn:aws:us-east-1:123456789012:log-group:/aws/application-signals/data:*"
            ],
            "Condition": {
                "ArnLike": {
                "aws:SourceArn": "arn:aws:us-east-1:123456789012:*"
                },
                "StringEquals": {
                "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}
Example command

The following example shows how to format your AWS CLI command with PutResourcePolicy. 

aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:logs:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}'

Step 2. Configure the destination of trace segments

Configure the ingestion of spans with UpdateTraceSegmentDestination.

Example command

The following example shows how to format your AWS CLI command with UpdateTraceSegmentDestination. 

aws xray update-trace-segment-destination --destination CloudWatchLogs

Step 3. Configure the amount of spans to index

Configure your desired sampling percentage with UpdateIndexingRule

Example command

The following example shows how to format your AWS CLI command with UpdateIndexingRule. 

aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}'
Note

After you enable Transaction Search, it can take ten minutes for spans to become available for search and analysis.

Step 4. Verify spans are available for search and analysis

To verify spans are available for search and analysis, use GetTraceSegmentDestination.

Example commands

The following example shows how to format your AWS CLI command with GetTraceSegmentDestination. 

aws xray get-trace-segment-destination
Example response

The following example shows the response you can expect when Transaction Search is active. 

{
    "Destination": "CloudWatchLogs",
    "Status": "ACTIVE"
}