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

# 啟用 Transaction Search
<a name="Enable-TransactionSearch"></a>

可以透過主控台或 API 啟用 [Transaction Search](CloudWatch-Transaction-Search.md)。Transaction Search 針對整個帳戶設定，並使用 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)，將透過 X-Ray 進行的所有範圍攝取切換到經濟高效的收集模式。預設情況下，系統亦會免費為您索引 1% 的攝入範圍作為追蹤摘要，供分析之用。鑑於您已能透過 Transaction Search，對所有攝入範圍取得完整的端到端追蹤可見性，此比例通常已足夠滿足需求。

## 先決條件
<a name="Enable-TransactionSearch-prerequisites"></a>

 必須先建立具有下列許可的角色，才能啟用 Transaction Search。

------
#### [ 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/*"
    }
  ]
}
```

------

**注意**  
 若要使用 Transaction Search 和其他 CloudWatch 功能，請將 [CloudWatchReadOnlyAccess 政策](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchReadOnlyAccess.html)新增至您的角色。如需建立角色的詳細資訊，請參閱 [IAM role creation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。

## 在主控台中啟用 Transaction Search
<a name="CloudWatch-Transaction-Search-EnableConsole"></a>

 以下程序說明如何在主控台中啟用 Transaction Search。

**在 CloudWatch 主控台中啟用 Transaction Search**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1.  在導覽窗格的 **Application Signals** 下，選擇 **Transaction Search**。

1.  選擇**啟用 Transaction Search**。

1.  選取要擷取為結構化日誌的方塊，然後輸入要編製索引的範圍百分比。可以免費編製 1% 範圍的索引，並在稍後根據需要變更百分比。

## 使用 API 啟用 Transaction Search
<a name="CloudWatch-Transaction-Search-EnableAPI"></a>

 下列程序說明如何使用 API 啟用 Transaction Search。

### 步驟 1. 建立政策以授與在 CloudWatch Logs 中擷取範圍的存取權
<a name="w2aac28c21c15c11b5"></a>

 使用 AWS CLI 或 SDK 啟用交易搜尋時，您必須使用資源型政策搭配 來設定許可[https://docs.aws.amazon.com/xray/latest/api/API_PutResourcePolicy.html](https://docs.aws.amazon.com/xray/latest/api/API_PutResourcePolicy.html)。

**範例 政策**  
 下列政策範例允許 X-Ray 將追蹤傳送至 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"
                }
            }
        }
    ]
}
```

------

**範例 命令**  
 下列範例顯示如何使用 格式化 AWS CLI 命令`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" } } } ]}'
```

### 步驟 2. 設定追蹤區段的目的地
<a name="w2aac28c21c15c11b7"></a>

 設定透過 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateTraceSegmentDestination.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateTraceSegmentDestination.html) 進行範圍的擷取。

**範例 命令**  
 下列範例顯示如何使用 格式化 AWS CLI 命令`UpdateTraceSegmentDestination`。

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

### 步驟 3。設定要編製索引的範圍數量
<a name="w2aac28c21c15c11b9"></a>

 使用 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateIndexingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateIndexingRule.html) 設定所需的取樣百分比 

**範例 命令**  
 下列範例顯示如何使用 格式化 AWS CLI 命令`UpdateIndexingRule`。

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

**注意**  
 啟用 Transaction Search 後，需等待約十分鐘，範圍才可用於搜尋和分析。

### 步驟 4. 驗證範圍是否可用於搜尋和分析
<a name="w2aac28c21c15c11c11"></a>

 若要驗證範圍是否可用於搜尋和分析，請使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSegmentDestination.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSegmentDestination.html)。

**命令範例**  
 下列範例顯示如何使用 格式化 AWS CLI 命令`GetTraceSegmentDestination`。

```
aws xray get-trace-segment-destination
```

**回應範例**  
 下列範例顯示 Transaction Search 處於作用中狀態時，您可能收到的回應。

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

# 搭配 使用交易搜尋 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"
}
```