本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 搭配 使用交易搜尋 CloudFormation
<a name="CloudWatch-Transaction-Search-Cloudformation"></a>

您可以使用 CloudFormation 來啟用和設定 X-Ray 交易搜尋。

**注意**  
若要建立 CloudFormation 堆疊，請參閱[建立您的第一個堆疊。 ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/gettingstarted.walkthrough.html)

## 先決條件
<a name="prerequsites-transaction-search"></a>
+ 您必須具有 IAM 使用者或角色的 AWS 帳戶存取權，該帳戶具有使用 Amazon EC2、Amazon S3 的許可 CloudFormation，或具有管理使用者存取權。
+ 必須擁有可存取網際網路的虛擬私有雲端 (VPC)。方便起見，可以使用帳戶隨附的預設 VPC。預設 VPC 和預設子網路已足以滿足此組態需求。
+ 在使用 AWS CDK 或 啟用之前，請確定已停用交易搜尋 CloudFormation。

## 啟用 Transaction Search
<a name="enabling-transaction-search-CFN"></a>

若要使用 CloudFormation 啟用 Transaction Search，必須先建立以下兩個資源。
+ `AWS::Logs::ResourcePolicy`
+ `AWS::XRay::TransactionSearchConfig`

1. **建立 AWS::Logs::ResourcePolicy**：建立資源政策，允許 X-Ray 將追蹤傳送至 CloudWatch Logs

   **YAML**

   ```
   Resources:
     LogsResourcePolicy:
       Type: AWS::Logs::ResourcePolicy
       Properties:
         PolicyName: TransactionSearchAccess
         PolicyDocument: !Sub >
           {
             "Version": "2012-10-17",		 	 	 
             "Statement": [
               {
                 "Sid": "TransactionSearchXRayAccess",
                 "Effect": "Allow",
                 "Principal": {
                   "Service": "xray.amazonaws.com"
                 },
                 "Action": "logs:PutLogEvents",
                 "Resource": [
                   "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:aws/spans:*",
                   "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/application-signals/data:*"
                 ],
                 "Condition": {
                   "ArnLike": {
                     "aws:SourceArn": "arn:${AWS::Partition}:xray:${AWS::Region}:${AWS::AccountId}:*"
                   },
                   "StringEquals": {
                     "aws:SourceAccount": "${AWS::AccountId}"
                   }
                 }
               }
             ]
           }
   ```

   **JSON**

   ```
   {
       "Resources": {
           "LogsResourcePolicy": {
               "Type": "AWS::Logs::ResourcePolicy",
               "Properties": {
                   "PolicyName": "TransactionSearchAccess",
                   "PolicyDocument": {
                       "Fn::Sub": "{\n  \"Version\": \"2012-10-17\",		 	 	 \n  \"Statement\": [\n    {\n      \"Sid\": \"TransactionSearchXRayAccess\",\n      \"Effect\": \"Allow\",\n      \"Principal\": {\n        \"Service\": \"xray.amazonaws.com\"\n      },\n      \"Action\": \"logs:PutLogEvents\",\n      \"Resource\": [\n        \"arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:aws/spans:*\",\n        \"arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/application-signals/data:*\"\n      ],\n      \"Condition\": {\n        \"ArnLike\": {\n          \"aws:SourceArn\": \"arn:${AWS::Partition}:xray:${AWS::Region}:${AWS::AccountId}:*\"\n        },\n        \"StringEquals\": {\n          \"aws:SourceAccount\": \"${AWS::AccountId}\"\n        }\n      }\n    }\n  ]\n}"
                   }
               }
           }
       }
   }
   ```

1. **建立和設定 AWS::XRay::TransactionSearchConfig**：建立 `TransactionSearchConfig` 資源以啟用 Transaction Search。

   **YAML**

   ```
   Resources:
     XRayTransactionSearchConfig:
       Type: AWS::XRay::TransactionSearchConfig
   ```

   **JSON**

   ```
   {
     "Resources": {
       "XRayTransactionSearchConfig": {
         "Type": "AWS::XRay::TransactionSearchConfig"
       }
     }
   }
   ```

1. (選用) 可以設定 `IndexingPercentage` 屬性來控制將編製索引的範圍百分比。

   **YAML**

   ```
   Resources:
     XRayTransactionSearchConfig:
       Type: AWS::XRay::TransactionSearchConfig
       Properties:
         IndexingPercentage: 50
   ```

   **JSON**

   ```
   {
     "Resources": {
       "XRayTransactionSearchConfig": {
         "Type": "AWS::XRay::TransactionSearchConfig",
         "Properties": {
           "IndexingPercentage": 20
         }
       }
     }
   }
   ```

   IndexingPercentage 值可設定在 0 到 100 之間。

## 範本範例
<a name="transaction-search-CFN-examples"></a>

下列範例同時包含資源政策與 TransactionSearchConfig。

**YAML**

```
Resources:
  LogsResourcePolicy:
    Type: AWS::Logs::ResourcePolicy
    Properties:
      PolicyName: TransactionSearchAccess
      PolicyDocument: !Sub >
        {
          "Version": "2012-10-17",		 	 	 
          "Statement": [
            {
              "Sid": "TransactionSearchXRayAccess",
              "Effect": "Allow",
              "Principal": {
                "Service": "xray.amazonaws.com"
              },
              "Action": "logs:PutLogEvents",
              "Resource": [
                "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:aws/spans:*",
                "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/application-signals/data:*"
              ],
              "Condition": {
                "ArnLike": {
                  "aws:SourceArn": "arn:${AWS::Partition}:xray:${AWS::Region}:${AWS::AccountId}:*"
                },
                "StringEquals": {
                  "aws:SourceAccount": "${AWS::AccountId}"
                }
              }
            }
          ]
        }

  XRayTransactionSearchConfig:
    Type: AWS::XRay::TransactionSearchConfig
    Properties:
      IndexingPercentage: 10
```

**JSON**

```
{
    "Resources": {
        "LogsResourcePolicy": {
            "Type": "AWS::Logs::ResourcePolicy",
            "Properties": {
                "PolicyName": "TransactionSearchAccess",
                "PolicyDocument": {
                    "Fn::Sub": "{\n  \"Version\": \"2012-10-17\",		 	 	 \n  \"Statement\": [\n    {\n      \"Sid\": \"TransactionSearchXRayAccess\",\n      \"Effect\": \"Allow\",\n      \"Principal\": {\n        \"Service\": \"xray.amazonaws.com\"\n      },\n      \"Action\": \"logs:PutLogEvents\",\n      \"Resource\": [\n        \"arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:aws/spans:*\",\n        \"arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/application-signals/data:*\"\n      ],\n      \"Condition\": {\n        \"ArnLike\": {\n          \"aws:SourceArn\": \"arn:${AWS::Partition}:xray:${AWS::Region}:${AWS::AccountId}:*\"\n        },\n        \"StringEquals\": {\n          \"aws:SourceAccount\": \"${AWS::AccountId}\"\n        }\n      }\n    }\n  ]\n}"
                }
            }
        },
        "XRayTransactionSearchConfig": {
            "Type": "AWS::XRay::TransactionSearchConfig",
            "Properties": {
                "IndexingPercentage": 20
            }
        }
    }
}
```

以下是在 TypeScript AWS CDK 中使用 的範例。

**CDK**

```
import * as cdk from '@aws-cdk/core';
import * as logs from '@aws-cdk/aws-logs';
import * as xray from '@aws-cdk/aws-xray';

export class XRayTransactionSearchStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Create the resource policy
    const transactionSearchAccess = new logs.CfnResourcePolicy(this, 'XRayLogResourcePolicy', {
      policyName: 'TransactionSearchAccess',
      policyDocument: JSON.stringify({
        Version: '2012-10-17',		 	 	 
        Statement: [
          {
            Sid: 'TransactionSearchXRayAccess',
            Effect: 'Allow',
            Principal: {
              Service: 'xray.amazonaws.com',
            },
            Action: 'logs:PutLogEvents',
            Resource: [
              `arn:${this.partition}:logs:${this.region}:${this.account}:log-group:aws/spans:*`,
              `arn:${this.partition}:logs:${this.region}:${this.account}:log-group:/aws/application-signals/data:*`,
            ],
            Condition: {
              ArnLike: {
                'aws:SourceArn': `arn:${this.partition}:xray:${this.region}:${this.account}:*`,
              },
              StringEquals: {
                'aws:SourceAccount': this.account,
              },
            },
          },
        ],
      }),
    });

    // Create the TransactionSearchConfig with dependency
    const transactionSearchConfig = new xray.CfnTransactionSearchConfig(this, 'XRayTransactionSearchConfig', {
      indexingPercentage: 10,
    });

    // Add the dependency to ensure Resource Policy is created first
    transactionSearchConfig.addDependsOn(transactionSearchAccess);
  }
}
```

## 驗證 DNS 組態
<a name="transaction-search-verify"></a>

部署 CloudFormation 堆疊之後，您可以使用 驗證組態 AWS CLI。

**aws xray get-trace-segment-destination**

成功的組態將傳回下列內容。

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