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.

Prerequisites

Before you can enable Transaction Search, you must create a role with the following permissions.

JSON

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "TransactionSearchXRayPermissions",
      "Effect": "Allow",
      "Action": [
        "xray:GetTraceSegmentDestination",
        "xray:UpdateTraceSegmentDestination",
        "xray:GetIndexingRules",
        "xray:UpdateIndexingRule"
      ],
      "Resource": "*"
    },
    {
      "Sid": "TransactionSearchLogGroupPermissions",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutRetentionPolicy"
      ],
      "Resource": [
        "arn:aws:logs:*:*:log-group:/aws/application-signals/data:*",
        "arn:aws:logs:*:*:log-group:aws/spans:*"
      ]
    },
    {
      "Sid": "TransactionSearchLogsPermissions",
      "Effect": "Allow",
      "Action": [
        "logs:PutResourcePolicy",
        "logs:DescribeResourcePolicies"
      ],
      "Resource": "*"
    },
    {
      "Sid": "TransactionSearchApplicationSignalsPermissions",
      "Effect": "Allow",
      "Action": [
        "application-signals:StartDiscovery"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchApplicationSignalsCreateServiceLinkedRolePermissions",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/application-signals.cloudwatch.amazonaws.com/AWSServiceRoleForCloudWatchApplicationSignals",
      "Condition": {
        "StringLike": {
          "iam:AWSServiceName": "application-signals.cloudwatch.amazonaws.com"
        }
      }
    },
    {
      "Sid": "CloudWatchApplicationSignalsGetRolePermissions",
      "Effect": "Allow",
      "Action": "iam:GetRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/application-signals.cloudwatch.amazonaws.com/AWSServiceRoleForCloudWatchApplicationSignals"
    },
    {
      "Sid": "CloudWatchApplicationSignalsCloudTrailPermissions",
      "Effect": "Allow",
      "Action": [
        "cloudtrail:CreateServiceLinkedChannel"
      ],
      "Resource": "arn:aws:cloudtrail:*:*:channel/aws-service-channel/application-signals/*"
    }
  ]
}

Note

If you encrypt spans with a customer managed AWS KMS key, the role also needs the kms:DescribeKey permission for the key. If your role uses the CloudWatchFullAccessV2 managed policy, it already has this permission. For an example policy and the key requirements, see Encrypting spans with a customer managed key.

Note

To use Transaction Search and other CloudWatch features, add the CloudWatchReadOnlyAccess policy to your role. For information about how to create a role, see IAM role creation.

Encrypting spans with a customer managed key

By default, CloudWatch Logs encrypts the aws/spans log group that stores your spans. To use your own key instead, choose a customer managed AWS KMS key when you enable Transaction Search. X-Ray applies the key only when it creates the aws/spans log group.

The key must meet the following requirements:

• It's a symmetric encryption key in the same account and Region as the log group. Specify the key ARN. Key IDs and alias ARNs aren't supported.

• The key policy allows CloudWatch Logs to use the key. For more information about key policies for CloudWatch Logs, see Encrypt log data in CloudWatch Logs using AWS KMS.

• The role that enables Transaction Search has the kms:DescribeKey permission for the key. If the aws/spans log group already exists, you also need the logs:AssociateKmsKey permission for it.

The following example JSON policy grants the kms:DescribeKey permission for one key. Add it to the role that enables Transaction Search:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "TransactionSearchKmsDescribeKey",
            "Effect": "Allow",
            "Action": "kms:DescribeKey",
            "Resource": "arn:aws:kms:us-east-1:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
        }
    ]
}

In the example, make the following replacements:

• Replace us-east-1 with the Region of your key.

• Replace 111122223333 with your account ID.

• Replace a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 with the ID of your key.

If the aws/spans log group already exists, X-Ray doesn't apply the key. In the console, CloudWatch applies your key to the existing log group in CloudWatch Logs instead.

If you use the API or CloudFormation, a request that includes a key fails, and X-Ray makes no changes. Instead, enable Transaction Search without a key, and then associate your key with the existing log group in CloudWatch Logs. Your key encrypts only spans that CloudWatch Logs ingests after you associate it.

The key applies only to the aws/spans log group. To encrypt the /aws/application-signals/data log group, create it with your key before you enable 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.

5. (Optional) Select Customize encryption settings (advanced), and then choose a customer managed key to encrypt the aws/spans log group with your own key. For more information about the key requirements, see Encrypting spans with a customer managed key.

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:logs:us-east-1:123456789012:log-group:aws/spans:*",
                "arn:aws:logs:us-east-1:123456789012:log-group:/aws/application-signals/data:*"
            ],
            "Condition": {
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:xray: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:xray: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

To encrypt the aws/spans log group with your own key, add the key ARN in CloudWatchLogsConfiguration. For more information about the key requirements, see Encrypting spans with a customer managed key. In the following example, replace the key ARN with the ARN of your key.

aws xray update-trace-segment-destination --destination CloudWatchLogs --cloud-watch-logs-configuration '{"SpansLogGroupKmsKeyId": "arn:partition:kms:region:account-id:key/key-id"}'

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 10 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"
}

If you used a customer managed key, the following command shows which key encrypts the aws/spans log group.

aws logs describe-log-groups --log-group-name-prefix aws/spans --query 'logGroups[].kmsKeyId'