本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 記錄 X-Ray API 呼叫 AWS CloudTrail
AWS X-Ray 已與 整合[AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)，此服務提供使用者、角色或 所採取動作的記錄 AWS 服務。CloudTrail 會將 X-Ray 的所有 API 呼叫擷取為事件。擷取的呼叫包括從 X-Ray 主控台的呼叫，以及對 X-Ray API 操作的程式碼呼叫。您可以使用 CloudTrail 所收集的資訊，判斷對 X-Ray 提出的請求、提出請求的 IP 地址、提出請求的時間，以及其他詳細資訊。
每一筆事件或日誌專案都會包含產生請求者的資訊。身分資訊可協助您判斷下列事項：
+ 該請求是使用根使用者還是使用者憑證提出。
+ 請求是否代表 IAM Identity Center 使用者提出。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 該請求是否由另一項 AWS 服務服務提出。
當您建立帳戶 AWS 帳戶 時CloudTrail 會在 中處於作用中狀態，而且您會自動存取 CloudTrail **事件歷史記錄**。CloudTrail **事件歷史記錄**為 AWS 區域中過去 90 天記錄的管理事件，提供可檢視、可搜尋、可下載且不可變的記錄。如需詳細資訊，請參閱「AWS CloudTrail 使用者指南」**中的[使用 CloudTrail 事件歷史記錄](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)。檢視**事件歷史記錄**不會產生 CloudTrail 費用。
如需 AWS 帳戶 過去 90 天內持續記錄的事件，請建立線索或 [CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) 事件資料存放區。
**CloudTrail 追蹤**
*線索*能讓 CloudTrail 將日誌檔案交付至 Amazon S3 儲存貯體。使用 建立的所有線索 AWS 管理主控台 都是多區域。您可以使用 AWS CLI建立單一或多區域追蹤。建議您建立多區域追蹤，因為您擷取 AWS 區域 帳戶中所有 的活動。如果您建立單一區域追蹤，您只能檢視追蹤 AWS 區域中記錄的事件。如需追蹤的詳細資訊，請參閱《AWS CloudTrail 使用者指南》**中的[為您的 AWS 帳戶建立追蹤](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)和[為組織建立追蹤](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html)。
您可以透過建立追蹤，免費將持續管理事件的一個複本從 CloudTrail 傳遞至您的 Amazon S3 儲存貯體，但這樣做會產生 Amazon S3 儲存費用。如需 CloudTrail 定價的詳細資訊，請參閱 [AWS CloudTrail 定價](https://aws.amazon.com/cloudtrail/pricing/)。如需 Amazon S3 定價的相關資訊，請參閱 [Amazon S3 定價](https://aws.amazon.com/s3/pricing/)。
**CloudTrail Lake 事件資料存放區**
*CloudTrail Lake* 讓您能夠對事件執行 SQL 型查詢。CloudTrail Lake 會將分列式 JSON 格式的現有事件轉換為 [Apache ORC](https://orc.apache.org/) 格式。ORC 是一種單欄式儲存格式，針對快速擷取資料進行了最佳化。系統會將事件彙總到*事件資料存放區*中，事件資料存放區是事件的不可變集合，其依據為您透過套用[進階事件選取器](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-concepts.html#adv-event-selectors)選取的條件。套用於事件資料存放區的選取器控制哪些事件持續存在並可供您查詢。如需 CloudTrail Lake 的詳細資訊，請參閱*AWS CloudTrail 《 使用者指南*》中的[使用 AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html)。
CloudTrail Lake 事件資料存放區和查詢會產生費用。建立事件資料存放區時，您可以選擇要用於事件資料存放區的[定價選項](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html#cloudtrail-lake-manage-costs-pricing-option)。此定價選項將決定擷取和儲存事件的成本，以及事件資料存放區的預設和最長保留期。如需 CloudTrail 定價的詳細資訊，請參閱 [AWS CloudTrail 定價](https://aws.amazon.com/cloudtrail/pricing/)。
**Topics**
+ [CloudTrail 中的 X-Ray 管理事件](#xray-api-cloudtrail-mgmt)
+ [CloudTrail 中的 X-Ray 資料事件](#cloudtrail-data-events)
+ [X-Ray 事件範例](#xray-cloudtrail-examples)
## CloudTrail 中的 X-Ray 管理事件
AWS X-Ray 與 整合， AWS CloudTrail 以記錄使用者、角色或 X-Ray AWS 服務 中的 所做的 API 動作。您可以使用 CloudTrail 即時監控 X-Ray API 請求，並將日誌存放在 Amazon S3、Amazon CloudWatch Logs 和 Amazon CloudWatch Events 中。X-Ray 支援將下列動作記錄為 CloudTrail 日誌檔案中的事件：
**支援的 API 動作**
+ [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_CreateGroup.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateGroup.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_UpdateGroup.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateGroup.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_DeleteGroup.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteGroup.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetGroup.html](https://docs.aws.amazon.com/xray/latest/api/API_GetGroup.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetGroups.html](https://docs.aws.amazon.com/xray/latest/api/API_GetGroups.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetInsight.html](https://docs.aws.amazon.com/xray/latest/api/API_GetInsight.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetInsightEvents.html](https://docs.aws.amazon.com/xray/latest/api/API_GetInsightEvents.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetInsightImpactGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetInsightImpactGraph.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetInsightSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetInsightSummaries.html)
+ [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingStatisticSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingStatisticSummaries.html)
## CloudTrail 中的 X-Ray 資料事件
[資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events)提供有關在資源上執行或在資源中執行的資源操作的資訊 （例如[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)， 會將區段文件上傳至 X-Ray)。
這些也稱為資料平面操作。資料事件通常是大量資料的活動。根據預設，CloudTrail 不會記錄資料事件。CloudTrail **事件歷史記錄**不會記錄資料事件。
資料事件需支付額外的費用。如需 CloudTrail 定價的詳細資訊，請參閱 [AWS CloudTrail 定價](https://aws.amazon.com/cloudtrail/pricing/)。
您可以使用 CloudTrail 主控台或 CloudTrail API 操作 AWS CLI來記錄 X-Ray 資源類型的資料事件。如需如何記錄資料事件的詳細資訊，請參閱 *AWS CloudTrail 使用者指南*中的[使用 AWS 管理主控台 記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console)和[使用 AWS Command Line Interface記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI)。
下表列出您可以記錄資料事件的 X-Ray 資源類型。**資料事件類型 (主控台)** 資料行會顯示從 CloudTrail 主控台上的**資料事件類型**清單中選擇的值。**resources.type 值**欄會顯示值，您會在使用 AWS CLI 或 CloudTrail APIs 設定進階事件選取器時指定此`resources.type`值。**記錄到 CloudTrail 的資料 API** 資料行會針對資源類型顯示記錄到 CloudTrail 的 API 呼叫。
| 資料事件類型 (主控台) | resources.type 值 | 記錄到 CloudTrail 的資料 API |
| --- | --- | --- |
| X-Ray 追蹤 | AWS::XRay::Trace | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/xray-api-cloudtrail.html) |
您可以設定進階事件選取器來篩選 `eventName`和 `readOnly` 欄位，以僅記錄對您重要的事件。不過，您無法透過新增`resources.ARN`欄位選擇器來選取事件，因為 X-Ray 追蹤沒有 ARNs。如需這些欄位的詳細資訊，請參閱 *AWS CloudTrail API 參考*中的 [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html)。以下是如何執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/put-event-selectors.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/put-event-selectors.html) AWS CLI 命令以記錄 CloudTrail 追蹤資料事件的範例。您必須在 中執行 命令，或指定建立追蹤的區域；否則，操作會傳回`InvalidHomeRegionException`例外狀況。
```
aws cloudtrail put-event-selectors --trail-name myTrail --advanced-event-selectors \
'{
"AdvancedEventSelectors": [
{
"FieldSelectors": [
{ "Field": "eventCategory", "Equals": ["Data"] },
{ "Field": "resources.type", "Equals": ["AWS::XRay::Trace"] },
{ "Field": "eventName", "Equals": ["PutTraceSegments","GetSamplingTargets"] }
],
"Name": "Log X-Ray PutTraceSegments and GetSamplingTargets data events"
}
]
}'
```
## X-Ray 事件範例
### 管理事件範例， `GetEncryptionConfig`
以下是 CloudTrail 中 X-Ray GetEncryptionConfig日誌項目的範例。
**Example**
```
{
"eventVersion"=>"1.05",
"userIdentity"=>{
"type"=>"AssumedRole",
"principalId"=>"AROAJVHBZWD3DN6CI2MHM:MyName",
"arn"=>"arn:aws:sts::123456789012:assumed-role/MyRole/MyName",
"accountId"=>"123456789012",
"accessKeyId"=>"AKIAIOSFODNN7EXAMPLE",
"sessionContext"=>{
"attributes"=>{
"mfaAuthenticated"=>"false",
"creationDate"=>"2023-7-01T00:24:36Z"
},
"sessionIssuer"=>{
"type"=>"Role",
"principalId"=>"AROAJVHBZWD3DN6CI2MHM",
"arn"=>"arn:aws:iam::123456789012:role/MyRole",
"accountId"=>"123456789012",
"userName"=>"MyRole"
}
}
},
"eventTime"=>"2023-7-01T00:24:36Z",
"eventSource"=>"xray.amazonaws.com",
"eventName"=>"GetEncryptionConfig",
"awsRegion"=>"us-east-2",
"sourceIPAddress"=>"33.255.33.255",
"userAgent"=>"aws-sdk-ruby2/2.11.19 ruby/2.3.1 x86_64-linux",
"requestParameters"=>nil,
"responseElements"=>nil,
"requestID"=>"3fda699a-32e7-4c20-37af-edc2be5acbdb",
"eventID"=>"039c3d45-6baa-11e3-2f3e-e5a036343c9f",
"eventType"=>"AwsApiCall",
"recipientAccountId"=>"123456789012"
}
```
### 資料事件範例， `PutTraceSegments`
以下是 CloudTrail 中 X-Ray PutTraceSegments資料事件日誌項目的範例。
**Example**
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROAWYXPW54Y4NEXAMPLE:i-0dzz2ac111c83zz0z",
"arn": "arn:aws:sts::012345678910:assumed-role/my-service-role/i-0dzz2ac111c83zz0z",
"accountId": "012345678910",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AROAWYXPW54Y4NEXAMPLE",
"arn": "arn:aws:iam::012345678910:role/service-role/my-service-role",
"accountId": "012345678910",
"userName": "my-service-role"
},
"attributes": {
"creationDate": "2024-01-22T17:34:11Z",
"mfaAuthenticated": "false"
},
"ec2RoleDelivery": "2.0"
}
},
"eventTime": "2024-01-22T18:22:05Z",
"eventSource": "xray.amazonaws.com",
"eventName": "PutTraceSegments",
"awsRegion": "us-west-2",
"sourceIPAddress": "198.51.100.0",
"userAgent": "aws-sdk-ruby3/3.190.0 md/internal ua/2.0 api/xray#1.0.0 os/linux md/x86_64 lang/ruby#2.7.8 md/2.7.8 cfg/retry-mode#legacy",
"requestParameters": {
"traceSegmentDocuments": [
"trace_id:1-00zzz24z-EXAMPLE4f4e41754c77d0000",
"trace_id:1-00zzz24z-EXAMPLE4f4e41754c77d0000",
"trace_id:1-00zzz24z-EXAMPLE4f4e41754c77d0001",
"trace_id:1-00zzz24z-EXAMPLE4f4e41754c77d0002"
]
},
"responseElements": {
"unprocessedTraceSegments": []
},
"requestID": "5zzzzz64-acbd-46ff-z544-451a3ebcb2f8",
"eventID": "4zz51z7z-77f9-44zz-9bd7-6c8327740f2e",
"readOnly": false,
"resources": [
{
"type": "AWS::XRay::Trace"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "012345678910",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ZZZZZ-RSA-AAA128-GCM-SHA256",
"clientProvidedHostHeader": "example.us-west-2.xray.cloudwatch.aws.dev"
}
}
```