本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS X-Ray 與其他 整合 AWS 服務 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 許多 AWS 服務 提供不同層級的 X-Ray 整合，包括取樣和將標頭新增至傳入請求、執行 X-Ray 協助程式，以及自動將追蹤資料傳送至 X-Ray。與 X-Ray 整合可包含下列項目： + *主動檢測* – 取樣和檢測傳入請求 + *被動檢測* – 檢測由其他服務取樣的請求 + *請求追蹤* – 將追蹤標頭新增至所有傳入請求，並將其傳播到下游 + *工具* – 執行 X-Ray 協助程式以從 X-Ray SDK 接收區段 **注意** X-Ray SDKs包含可與其他 整合的外掛程式 AWS 服務。例如，您可以使用適用於 Java Elastic Beanstalk 的 X-Ray 開發套件外掛程式來新增執行應用程式之 Elastic Beanstalk 環境的相關資訊，包括環境名稱和 ID。 以下是與 X-Ray AWS 服務 整合的一些範例： + [AWS Distro for OpenTelemetry (ADOT)](xray-services-adot.md) – 透過 ADOT，工程師可以檢測其應用程式一次，並將相關指標和追蹤傳送至多個 AWS 監控解決方案 AWS X-Ray，包括 Amazon CloudWatch、Amazon OpenSearch Service 和 Amazon Managed Service for Prometheus。 + [AWS Lambda](xray-services-lambda.md) – 主動和被動檢測所有執行時間的傳入請求。 會將兩個節點 AWS Lambda 新增至追蹤映射，一個用於 AWS Lambda 服務，另一個用於 函數。當您啟用檢測時， AWS Lambda 也會在 Java 和 Node.js 執行時間上執行 X-Ray 協助程式，以便與 X-Ray SDK 搭配使用。 + [Amazon API Gateway](xray-services-apigateway.md) – 主動和被動檢測。API Gateway 使用取樣規則來判斷要記錄的請求，並將閘道階段的節點新增至您的服務映射。 + [AWS Elastic Beanstalk](xray-services-beanstalk.md) – 工具。Elastic Beanstalk 在下列平台上包含 X-Ray 協助程式： + *Java SE* – 2.3.0 及更新版本組態 + *Tomcat* – 2.4.0 及更新版本組態 + *Node.js* – 3.2.0 及更新版本組態 + *Windows Server* – 2016 年 12 月 9 日之後發行的 Windows Server Core 以外的所有組態 您可以使用 Elastic Beanstalk 主控台，指示 Elastic Beanstalk 在這些平台上執行協助程式，或使用 `aws:elasticbeanstalk:xray` 命名空間中的 `XRayEnabled`選項。 + [Elastic Load Balancing](xray-services-elb.md) – 在 Application Load Balancer 上請求追蹤。Application Load Balancer 會將追蹤 ID 新增至請求標頭，然後再將其傳送至目標群組。 + [Amazon EventBridge](xray-services-eventbridge.md) – 被動檢測。如果使用 X-Ray SDK 檢測將事件發佈至 EventBridge 的服務，則事件目標會收到追蹤標頭，並且可以繼續傳播原始追蹤 ID。 + [Amazon Simple Notification Service](xray-services-sns.md) – 被動檢測。如果 Amazon SNS 發佈者使用 X-Ray 開發套件追蹤其用戶端，訂閱者可以擷取追蹤標頭，並繼續使用相同的追蹤 ID 從發佈者傳播原始追蹤。 + [Amazon Simple Queue Service](xray-services-sqs.md) – 被動檢測。如果服務使用 X-Ray SDK 追蹤請求，Amazon SQS 可以傳送追蹤標頭，並繼續使用一致的追蹤 ID 將原始追蹤從寄件者傳播給消費者。 + [Amazon Bedrock AgentCore](xray-services-sqs.md) – AgentCore 支援透過 X-Ray 整合的分散式追蹤，可讓您在請求流經代理應用程式時追蹤請求。當您啟用 AgentCore 資源的可觀測性時，您可以跨服務邊界傳播追蹤內容，並了解 AI 代理器和工具的效能。 從下列主題中選擇，以探索整組整合的 AWS 服務。 **Topics** + [Amazon Bedrock AgentCore 和 AWS X-Ray](xray-services-agentcore.md) + [Amazon Elastic Compute Cloud 和 AWS X-Ray](xray-services-ec2.md) + [Amazon SNS 和 AWS X-Ray](xray-services-sns.md) + [Amazon SQS 和 AWS X-Ray](xray-services-sqs.md) + [Amazon S3 和 AWS X-Ray](xray-services-s3.md) + [AWS Distro for OpenTelemetry 和 AWS X-Ray](xray-services-adot.md) + [使用 追蹤 X-Ray 加密組態變更 AWS Config](xray-api-config.md) + [AWS AppSync 而且 AWS X-Ray](xray-services-appsync.md) + [的 Amazon API Gateway 主動追蹤支援 AWS X-Ray](xray-services-apigateway.md) + [Amazon EC2 和 AWS App Mesh](xray-services-appmesh.md) + [AWS App Runner 和 X-Ray](xray-services-app-runner.md) + [使用 記錄 X-Ray API 呼叫 AWS CloudTrail](xray-api-cloudtrail.md) + [CloudWatch 與 X-Ray 整合](xray-services-cloudwatch.md) + [AWS Elastic Beanstalk 而且 AWS X-Ray](xray-services-beanstalk.md) + [Elastic Load Balancing 和 AWS X-Ray](xray-services-elb.md) + [Amazon EventBridge 和 AWS X-Ray](xray-services-eventbridge.md) + [AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md) + [AWS Step Functions 而且 AWS X-Ray](xray-services-stepfunctions.md) # Amazon Bedrock AgentCore 和 AWS X-Ray Amazon Bedrock AgentCore 與 整合 AWS X-Ray ，為您的 AI 代理器和工具提供分散式追蹤功能。此整合可讓您在請求通過代理程式應用程式時追蹤請求，協助您識別效能瓶頸並疑難排解問題。 AgentCore 支援透過 X-Ray 整合的分散式追蹤，可讓您監控 AI 代理器和工具的效能。當您啟用 AgentCore 資源的可觀測性時，您可以跨服務邊界傳播追蹤內容，並了解客服人員與其他 AWS 服務的互動方式。如需詳細資訊，請參閱 [Amazon Bedrock AgentCore](https://docs.aws.amazon.com//bedrock-agentcore/latest/devguide/what-is-genesis.html)。 AgentCore 支援下列 X-Ray 功能： + 將追蹤內容傳播至下游服務 + 使用 AWS Distro for OpenTelemetry (ADOT) SDK 進行自訂檢測 ## 使用 AgentCore 設定 X-Ray 若要搭配 AgentCore 使用 X-Ray，您需要在 AWS 帳戶中啟用 CloudWatch 交易搜尋。這是一次性設定，可讓 AgentCore 將追蹤資料傳送至 X-Ray。如需詳細資訊，請參閱[啟用交易搜尋。 ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) 如需設定 AgentCore 可觀測性的詳細資訊，請參閱[將可觀測性新增至 Amazon Bedrock AgentCore 代理程式或工具 ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html)。 ## 搭配 AgentCore 使用追蹤標頭 AgentCore 支援分散式追蹤的 X-Ray 追蹤標頭格式。您可以在對 AgentCore 的請求中包含 `X-Amzn-Trace-Id`標頭，以維護跨服務界限的追蹤內容。 # Amazon Elastic Compute Cloud 和 AWS X-Ray 您可以使用使用者資料指令碼在 Amazon EC2 執行個體上安裝和執行 X-Ray 協助程式。如需說明，請參閱 [在 Amazon EC2 上執行 X-Ray 協助程式](xray-daemon-ec2.md)。 使用執行個體描述檔授予協助程式上傳追蹤資料的許可到 X-Ray。如需詳細資訊，請參閱[授予協助程式將資料傳送至 X-Ray 的許可](xray-daemon.md#xray-daemon-permissions)。 # Amazon SNS 和 AWS X-Ray 您可以使用 AWS X-Ray 搭配 Amazon Simple Notification Service (Amazon SNS)，在請求通過 SNS 主題到 [SNS 支援的訂閱服務](https://docs.aws.amazon.com/sns/latest/dg/sns-active-tracing.html)時追蹤和分析請求。使用 X-Ray 追蹤搭配 Amazon SNS 來分析訊息及其後端服務的延遲，例如請求在主題中花費的時間，以及將訊息傳遞給每個主題的訂閱所需的時間。Amazon SNS 支援標準和 FIFO 主題的 X-Ray 追蹤。 如果您從已使用 X-Ray 檢測的服務發佈至 Amazon SNS 主題，Amazon SNS 會將追蹤內容從發佈者傳遞給訂閱者。此外，您可以開啟主動追蹤，針對從檢測 SNS 用戶端發佈的訊息，將 Amazon SNS 訂閱的相關區段資料傳送至 X-Ray。使用 Amazon SNS 主控台或使用 Amazon SNS API 或 CLI 開啟 Amazon SNS 主題的[主動追蹤](https://docs.aws.amazon.com/sns/latest/dg/sns-active-tracing.html)。如需[檢測 SNS 用戶端的詳細資訊，請參閱檢測您的應用程式](xray-instrumenting-your-app.md)。 ## 設定 Amazon SNS 主動追蹤 您可以使用 Amazon SNS 主控台或 AWS CLI 或 SDK 來設定 Amazon SNS 主動追蹤。 當您使用 Amazon SNS 主控台時，Amazon SNS 會嘗試為 SNS 建立呼叫 X-Ray 的必要許可。如果您沒有足夠的許可來修改 X-Ray 資源政策，則可以拒絕嘗試。如需這些許可的詳細資訊，請參閱《[Amazon Simple Notification Service 開發人員指南》中的 Amazon SNS 中的 Identity and Access Management](https://docs.aws.amazon.com/sns/latest/dg/sns-authentication-and-access-control.html) 和 [Amazon SNS 存取控制的範例案例](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-use-cases.html)。如需使用 Amazon SNS 主控台開啟主動追蹤的詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》中的在 [Amazon SNS 主題上啟用主動追蹤](https://docs.aws.amazon.com/sns/latest/dg/sns-active-tracing.html)。 使用 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，以允許 Amazon SNS 將追蹤傳送至 X-Ray。 **Example Amazon SNS 主動追蹤的 X-Ray 資源型政策範例** 此範例政策文件指定 Amazon SNS 將追蹤資料傳送至 X-Ray 所需的許可： ``` { Version: "2012-10-17", Statement: [ { Sid: "SNSAccess", Effect: Allow, Principal: { Service: "sns.amazonaws.com", }, Action: [ "xray:PutTraceSegments", "xray:GetSamplingRules", "xray:GetSamplingTargets" ], Resource: "*", Condition: { StringEquals: { "aws:SourceAccount": "account-id" }, StringLike: { "aws:SourceArn": "arn:partition:sns:region:account-id:topic-name" } } } ] } ``` 使用 CLI 建立資源型政策，提供 Amazon SNS 將追蹤資料傳送至 X-Ray 的許可： ``` aws xray put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "SNSAccess", "Effect": "Allow", "Principal": { "Service": "sns.amazonaws.com" }, "Action": [ "xray:PutTraceSegments", "xray:GetSamplingRules", "xray:GetSamplingTargets" ], "Resource": "*", "Condition": { "StringEquals": { "aws:SourceAccount": "account-id" }, "StringLike": { "aws:SourceArn": "arn:partition:sns:region:account-id:topic-name" } } } ] }' ``` 若要使用這些範例，請將 *`partition`*、*`account-id`*、 *`region`*和 取代*`topic-name`*為您的特定 AWS 分割區、區域、帳戶 ID 和 Amazon SNS 主題名稱。若要授予所有 Amazon SNS 主題將追蹤資料傳送至 X-Ray 的許可，請將主題名稱取代為 `*`。 ## 在 X-Ray 主控台中檢視 Amazon SNS 發佈者和訂閱者追蹤 使用 X-Ray 主控台檢視追蹤映射和追蹤詳細資訊，以顯示 Amazon SNS 發佈者和訂閱者的連線檢視。為主題開啟 Amazon SNS 主動追蹤時，X-Ray 追蹤映射和追蹤詳細資訊映射會顯示 Amazon SNS 發佈者、Amazon SNS 主題和下游訂閱者的連線節點： ![\[使用 Amazon SNS 發佈者和訂閱者的追蹤映射\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/services-sns-activetracing-map.png) 選擇跨越 Amazon SNS 發佈者和訂閱者的追蹤之後，X-Ray 追蹤詳細資訊頁面會顯示追蹤詳細資訊地圖和區段時間軸。 **Example Amazon SNS 發佈者和訂閱者的時間表範例** 此範例顯示的時間軸包含 Amazon SNS 發佈者，會將訊息傳送至 Amazon SNS 主題，該主題由 Amazon SQS 訂閱者處理。 ![\[Amazon SNS 發佈者和訂閱者的客群時間軸\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/services-sns-activetracing-timeline.png) 上述時間軸範例提供有關 Amazon SNS 訊息流程的詳細資訊： + **SNS** 區段代表從用戶端進行 `Publish` API 呼叫的往返持續時間。 + **myTopic** 區段代表發佈請求的 Amazon SNS 回應延遲。 + **SQS** 子區段代表 Amazon SNS 將訊息發佈至 Amazon SQS 佇列所需的往返時間。 + **myTopic** 區段與 **SQS** 子區段之間的時間代表訊息在 Amazon SNS 系統中花費的時間。 **Example 批次處理 Amazon SNS 訊息的時間軸範例** 如果在單一追蹤中批次處理多個 Amazon SNS 訊息，區段時間軸會顯示代表每個已處理訊息的區段。 ![\[Amazon SNS 批次訊息的區段時間軸\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/services-sns-activetracing-batch-timeline.png) # Amazon SQS 和 AWS X-Ray AWS X-Ray 與 Amazon Simple Queue Service (Amazon SQS) 整合，以追蹤透過 Amazon SQS 佇列傳遞的訊息。如果服務使用 X-Ray SDK 追蹤請求，Amazon SQS 可以傳送追蹤標頭，並繼續使用一致的追蹤 ID 將原始追蹤從寄件者傳播給消費者。追蹤連續性可讓使用者追蹤、分析和偵錯整個下游服務。 AWS X-Ray 支援使用 Amazon SQS 和 追蹤事件驅動型應用程式 AWS Lambda。使用 CloudWatch 主控台查看與 Amazon SQS 佇列並由下游 Lambda 函數處理之每個請求的連線檢視。來自上游訊息生產者的追蹤會自動連結至來自下游 Lambda 消費者節點的追蹤，建立end-to-end檢視。如需詳細資訊，請參閱[追蹤事件驅動的應用程式](xray-tracelinking.md)。 ![\[透過 Amazon SQS 佇列從 Lambda 追蹤映射。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-servicemap-linkededge.png) Amazon SQS 支援下列追蹤標頭檢測： + **預設 HTTP 標頭** – 當您透過 SDK 呼叫 Amazon SQS 時，X-Ray AWS SDK 會自動將追蹤標頭填入為 HTTP 標頭。預設追蹤標頭由 `X-Amzn-Trace-Id` 攜帶，並對應至 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) 或 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) 請求中包含的所有訊息。若要進一步了解預設 HTTP 標頭 , 請參閱 [追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)。 + **`AWSTraceHeader` 系統屬性** – `AWSTraceHeader`是 Amazon SQS 預留[的訊息系統屬性](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_MessageSystemAttributeValue.html)，用於在佇列中攜帶 X-Ray 追蹤標頭與訊息。即使未透過 X-Ray SDK 自動檢測，`AWSTraceHeader`也可以使用，例如在為新語言建置追蹤 SDK 時。同時設定這兩個標頭檢測時，訊息系統屬性會覆寫 HTTP 追蹤標頭。 在 Amazon EC2 上執行時，Amazon SQS 支援一次處理一則訊息。這適用於在內部部署主機上執行，以及使用容器服務時 AWS Fargate，例如 Amazon ECS 或 AWS App Mesh。 追蹤標頭會從 Amazon SQS 訊息大小和訊息屬性配額中排除。啟用 X-Ray 追蹤不會超過您的 Amazon SQS 配額。若要進一步了解 AWS 配額，請參閱 [Amazon SQS Quotas](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-limits.html)。 ## 傳送 HTTP 追蹤標頭 Amazon SQS 中的寄件者元件可以透過 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)或 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)呼叫自動傳送追蹤標頭。檢測 AWS SDK 用戶端時，可以透過 X-Ray SDK 支援的所有語言自動追蹤它們。您在這些服務中存取的追蹤 AWS 服務 和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。 若要了解如何使用您偏好的語言追蹤 AWS SDK 呼叫，請參閱支援的 SDKs 中的下列主題： + Go – [使用適用於 Go 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-go-awssdkclients.md) + Java – [使用適用於 Java 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-java-awssdkclients.md) + Node.js – [使用適用於 Node.js 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-nodejs-awssdkclients.md) + Python – [使用適用於 Python 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-python-awssdkclients.md) + Ruby – [使用適用於 Ruby 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-ruby-awssdkclients.md) + .NET – [使用適用於 .NET 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-dotnet-sdkclients.md) ## 擷取追蹤標頭和復原追蹤內容 如果您使用的是 Lambda 下游消費者，則會自動進行追蹤內容傳播。若要繼續與其他 Amazon SQS 取用者進行內容傳播，您必須手動檢測接收器元件的交接。 復原追蹤內容有三個主要步驟： + 呼叫 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API，從 `AWSTraceHeader` 屬性的佇列接收訊息。 + 從屬性擷取追蹤標頭。 + 從標頭復原追蹤 ID。選擇性地將更多指標新增至區段。 以下是使用適用於 Java 的 X-Ray 開發套件撰寫的範例實作。 **Example ：擷取追蹤標頭和復原追蹤內容** ``` // Receive the message from the queue, specifying the "AWSTraceHeader" ReceiveMessageRequest receiveMessageRequest = new ReceiveMessageRequest() .withQueueUrl(QUEUE_URL) .withAttributeNames("AWSTraceHeader"); List messages = sqs.receiveMessage(receiveMessageRequest).getMessages(); if (!messages.isEmpty()) { Message message = messages.get(0); // Retrieve the trace header from the AWSTraceHeader message system attribute String traceHeaderStr = message.getAttributes().get("AWSTraceHeader"); if (traceHeaderStr != null) { TraceHeader traceHeader = TraceHeader.fromString(traceHeaderStr); // Recover the trace context from the trace header Segment segment = AWSXRay.getCurrentSegment(); segment.setTraceId(traceHeader.getRootTraceId()); segment.setParentId(traceHeader.getParentId()); segment.setSampled(traceHeader.getSampled().equals(TraceHeader.SampleDecision.SAMPLED)); } } ``` # Amazon S3 和 AWS X-Ray AWS X-Ray 與 Amazon S3 整合，以追蹤上游請求，以更新應用程式的 S3 儲存貯體。如果服務使用 X-Ray SDK 追蹤請求，Amazon S3 可以將追蹤標頭傳送給下游事件訂閱者，例如 AWS Lambda、Amazon SQS 和 Amazon SNS。X-Ray 可啟用 Amazon S3 事件通知的追蹤訊息功能。 您可以使用 X-Ray 追蹤圖來檢視 Amazon S3 與應用程式所使用其他服務之間的連線。您也可以使用主控台來檢視指標，例如平均延遲和失敗率。如需 X-Ray 主控台的詳細資訊，請參閱 [使用 X-Ray 主控台](aws-xray-interface-console.md#xray-console)。 Amazon S3 支援*預設 http 標頭*檢測。當您透過 SDK 呼叫 Amazon S3 時，X-Ray AWS SDK 會自動將追蹤標頭填入為 HTTP 標頭。預設追蹤標頭由 承載`X-Amzn-Trace-Id`。若要進一步了解追蹤標頭，請參閱 概念頁面上[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)的 。Amazon S3 追蹤內容傳播支援下列訂閱者：Lambda、SQS 和 SNS。由於 SQS 和 SNS 本身不會發出區段資料，因此它們不會在 S3 觸發時出現在追蹤或追蹤映射中，即使它們會將追蹤標頭傳播到下游服務。 ## 設定 Amazon S3 事件通知 使用 Amazon S3 通知功能，當儲存貯體中發生特定事件時，您會收到通知。然後，這些通知可以傳播到應用程式中的下列目的地： + Amazon Simple Notification Service (Amazon SNS) + Amazon Simple Queue Service (Amazon SQS) + AWS Lambda 如需支援的事件清單，請參閱《[Amazon S3 開發人員指南》中的支援的事件類型](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html#supported-notification-event-types)。 ### Amazon SNS 和 Amazon SQS 若要發佈通知至 SNS 主題或 SQS 佇列，您必須先授予 Amazon S3 許可。若要授予這些許可，請將 AWS Identity and Access Management (IAM) 政策連接至目的地 SNS 主題或 SQS 佇列。若要進一步了解所需的 IAM 政策，請參閱[授予發佈訊息至 SNS 主題或 SQS 佇列的許可](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html#grant-sns-sqs-permission-for-s3)。 如需整合 SNS 和 SQS 與 X-Ray 的相關資訊，請參閱 [Amazon SNS 和 AWS X-Ray](xray-services-sns.md)和 [Amazon SQS 和 AWS X-Ray](xray-services-sqs.md)。 ### AWS Lambda 當您使用 Amazon S3 主控台為 Lambda 函數設定 S3 儲存貯體的事件通知時，主控台會設定 Lambda 函數的必要許可，讓 Amazon S3 具有從儲存貯體叫用函數的許可。如需詳細資訊，請參閱《Amazon Simple Storage Service 主控台使用者指南》中的[如何啟用和設定 S3 儲存貯體的事件通知？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/enable-event-notifications.html)。 您也可以從 授予 Amazon S3 許可 AWS Lambda ，以叫用 Lambda 函數。如需詳細資訊，請參閱《[AWS Lambda 開發人員指南》中的教學課程：搭配 Amazon S3 使用](https://docs.aws.amazon.com/lambda/latest/dg/with-s3-example.html) AWS Lambda。 如需整合 Lambda 與 X-Ray 的詳細資訊，請參閱[在 AWS Lambda 中檢測 Java 程式碼](https://docs.aws.amazon.com/lambda/latest/dg/java-tracing.html)。 # AWS Distro for OpenTelemetry 和 AWS X-Ray 使用 AWS Distro for OpenTelemetry (ADOT) 收集指標和追蹤，並將其傳送至 AWS X-Ray 和其他監控解決方案，例如 Amazon CloudWatch、Amazon OpenSearch Service 和 Amazon Managed Service for Prometheus。 ## AWS Distro for OpenTelemetry AWS Distro for OpenTelemetry (ADOT) 是基於雲端原生運算基金會 (CNCF) OpenTelemetry 專案的 AWS 分佈。OpenTelemetry 提供一組開放原始碼 APIs、程式庫和代理程式，以收集分散式追蹤和指標。此工具組是上游 OpenTelemetry 元件的分佈，包括 SDKs、自動檢測代理程式和 測試、最佳化、保護和支援的收集器 AWS。 透過 ADOT，工程師可以一次檢測其應用程式，並將相關指標和追蹤傳送至多個 AWS 監控解決方案 AWS X-Ray，包括 Amazon CloudWatch、Amazon OpenSearch Service 和 Amazon Managed Service for Prometheus。 ADOT 與越來越多的 整合 AWS 服務 ，可簡化傳送追蹤和指標以監控解決方案，例如 X-Ray。與 ADOT 整合的一些服務範例包括： + *AWS Lambda* – 適用於 ADOT 的 AWS 受管 Lambda 層透過自動檢測 Lambda 函數、將 OpenTelemetry 與 AWS Lambda 和 X-Ray out-of-the-box組態封裝在易於設定的層中，提供plug-and-play使用者體驗。使用者可以為其 Lambda 函數啟用和停用 OpenTelemetry，而無需變更程式碼。如需詳細資訊，請參閱 [AWS Distro for OpenTelemetry Lambda](https://aws-otel.github.io/docs/getting-started/lambda) + *Amazon Elastic Container Service (ECS)* – 使用 AWS Distro for OpenTelemetry Collector 從 Amazon ECS 應用程式收集指標和追蹤，以傳送至 X-Ray 和其他監控解決方案。如需詳細資訊，請參閱《Amazon ECS 開發人員指南》中的[收集應用程式追蹤資料](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/trace-data.html)。 + *AWS App Runner* – App Runner 支援使用 AWS Distro for OpenTelemetry (ADOT) 將追蹤傳送至 X-Ray。使用 ADOT SDKs來收集容器化應用程式的追蹤資料，並使用 X-Ray 來分析並深入了解經檢測的應用程式。如需詳細資訊，請參閱 [AWS App Runner 和 X-Ray](xray-services-app-runner.md)。 如需 AWS Distro for OpenTelemetry 的詳細資訊，包括與其他 的整合 AWS 服務，請參閱 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)。 如需使用 AWS Distro for OpenTelemetry 和 X-Ray 檢測應用程式的詳細資訊，請參閱[使用 AWS Distro for OpenTelemetry 檢測應用程式](xray-instrumenting-your-app.md#xray-instrumenting-opentel)。 # 使用 追蹤 X-Ray 加密組態變更 AWS Config AWS X-Ray 與 整合 AWS Config ，以記錄對 X-Ray 加密資源所做的組態變更。您可以使用 AWS Config 清查 X-Ray 加密資源、稽核 X-Ray 組態歷史記錄，並根據資源變更傳送通知。 AWS Config 支援將下列 X-Ray 加密資源變更記錄為事件： + **組態變更** – 變更或新增加密金鑰，或還原至預設的 X-Ray 加密設定。 使用以下指示，了解如何在 X-Ray 和 之間建立基本連線 AWS Config。 ## 建立 Lambda 函數觸發 您必須先擁有自訂 AWS Lambda 函數的 ARN，才能產生自訂 AWS Config 規則。按照這些指示，使用 Node.js 來建立基本函數，以根據 `XrayEncryptionConfig` 資源的狀態將合規或未合規的值傳回給 AWS Config 。 **使用 AWS::XrayEncryptionConfig 變更觸發，建立 Lambda 函數** 1. 開啟 [Lambda 主控台](https://console.aws.amazon.com/lambda/home)。選擇 **Create function (建立函數)**。 1. 選擇 **Blueprints (藍圖)**，然後篩選藍圖程式庫的 **config-rule-change-triggered** 藍圖。按一下藍圖名稱中的連結，或選擇 **Configure (設定)** 以繼續。 1. 定義下列欄位以設定藍圖： + 針對 **Name (名稱)**，輸入名稱。 + 在 **Role (角色)** 中，選擇 **Create new role from template(s) (從範本建立新角色)**。 + 在 **Role name (角色名稱)** 中，輸入名稱。 + 針對 **Policy templates (政策範本)**，選擇**AWS Config Rules permissions (&CC; 規則許可)**。 1. 選擇**建立函數**以在 AWS Lambda 主控台中建立和顯示您的函數。 1. 編輯您的函數程式碼，將 `AWS::EC2::Instance` 取代為 `AWS::XrayEncryptionConfig`。您也可以更新描述欄位，以反映這個變更。 **預設程式碼** ``` if (configurationItem.resourceType !== 'AWS::EC2::Instance') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT'; } return 'NON_COMPLIANT'; ``` **更新的程式碼** ``` if (configurationItem.resourceType !== 'AWS::XRay::EncryptionConfig') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT'; } return 'NON_COMPLIANT'; ``` 1. 將以下內容新增至 IAM 中的執行角色，以存取 X-Ray。這些許可允許唯讀存取您的 X-Ray 資源。若未提供適當資源的存取權，則當評估與規則相關聯的 Lambda 函數 AWS Config 時，將導致 超出範圍的訊息。 ``` { "Sid": "Stmt1529350291539", "Action": [ "xray:GetEncryptionConfig" ], "Effect": "Allow", "Resource": "*" } ``` ## 建立 X 射線的自訂 AWS Config 規則 建立 Lambda 函數時，請記下函數的 ARN，然後前往 AWS Config 主控台建立自訂規則。 **建立 X-Ray 的 AWS Config 規則** 1. 開啟 [AWS Config 主控台的**規則**頁面](https://console.aws.amazon.com/config/home#/rules/view)。 1. 選擇 **Add rule (新增規則)**，然後選擇 **Add custom rule (新增自訂規則)**。 1. 在**AWS Lambda 函數 ARN** 中，插入與您要使用的 Lambda 函數相關聯的 ARN。 1. 選擇要設定的觸發類型： + **組態變更** – 當符合規則範圍的任何資源在組態中變更時， AWS Config 觸發評估。評估會在 AWS Config 傳送組態項目變更通知後執行。 + **定期** – 依您選擇的頻率 AWS Config 執行規則的評估 （例如，每 24 小時）。 1. 針對**資源類型**，在 X-Ray 區段**EncryptionConfig**中選擇 。 1. 選擇 ****Save**** (儲存)。 AWS Config 主控台會立即開始評估規則的合規。系統需要幾分鐘的時間來完成評估。 現在此規則符合規範， AWS Config 可以開始以時間軸的形式編譯稽核歷史記錄。 AWS Config 記錄資源變更。對於事件時間軸中的每個變更， 會以從/到格式 AWS Config 產生資料表，以顯示加密金鑰的 JSON 表示法中的變更。與 EncryptionConfig 相關聯的兩個欄位變更是 `Configuration.type` 和 `Configuration.keyID`。 ## 範例結果 以下是 AWS Config 時間軸的範例，顯示在特定日期和時間所做的變更。 ![\[AWS Config 時間軸。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/ConfigTimeline.png) 以下是 AWS Config 變更項目的範例。變更前/後格式可說明有哪些變更。此範例顯示預設 X-Ray 加密設定已變更為定義的加密金鑰。 ![\[X-Ray 加密組態變更項目。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/ConfigChanges.png) ## Amazon SNS 通知 若要收到組態變更的通知，請將 AWS Config 設定為發佈 Amazon SNS 通知。如需詳細資訊，請參閱[透過電子郵件監控 AWS Config 資源變更](https://docs.aws.amazon.com/config/latest/developerguide/monitoring-resource-changes-by-email.html)。 # AWS AppSync 而且 AWS X-Ray 您可以啟用和追蹤 AWS AppSync 的請求。如需詳細資訊，請參閱[使用 AWS X-Ray 追蹤](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html)以取得指示。 為 an AWS AppSync API 啟用 X-Ray 追蹤時，會在您的帳戶中自動建立 AWS Identity and Access Management [服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)，並具有適當的許可。這可讓 AWS AppSync 以安全的方式將追蹤傳送至 X-Ray。 # 的 Amazon API Gateway 主動追蹤支援 AWS X-Ray 您可以使用 X-Ray 在使用者請求通過 Amazon API Gateway APIs 到基礎服務時追蹤和分析使用者請求。API Gateway 支援所有 API Gateway 端點類型的 X-Ray 追蹤：區域、邊緣最佳化和私有。您可以在可使用 X-Ray 的所有 AWS 區域 中使用 X-Ray 搭配 Amazon API Gateway。如需詳細資訊，請參閱《Amazon API Gateway [API Gateway 開發人員指南》中的使用 追蹤 API Gateway API 執行 AWS X-Ray](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html)。 **注意** X-Ray 僅支援透過 APIs Gateway 追蹤 REST API。 Amazon API Gateway 提供 的[主動追蹤](xray-services.md)支援 AWS X-Ray。在您的 API 階段上啟用主動追蹤，以取樣傳入的請求，並將追蹤傳送至 X-Ray。 **啟用 API 階段的主動追蹤** 1. 在以下網址開啟 API Gateway 主控台：[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。 1. 選擇一個 API。 1. 選擇一個階段。 1. 在**日誌/追蹤**索引標籤上，選擇**啟用 X-Ray 追蹤**，然後選擇**儲存變更**。 1. 在左側導覽窗格中，選擇 **Resources (資源)**。 1. 若要使用新設定重新部署 API，請選擇**動作**下拉式清單，然後選擇**部署 API**。 API Gateway 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。您可以建立僅適用於 APIs規則，或僅適用於包含特定標頭的請求的規則。API Gateway 會在區段的屬性中記錄標頭，以及階段和請求的詳細資訊。如需詳細資訊，請參閱[設定 取樣規則](xray-console-sampling.md)。 **注意** 使用 API Gateway [HTTP 整合](https://docs.aws.amazon.com/apigateway/latest/developerguide/setup-http-integrations.html)追蹤 REST APIs 時，每個區段的服務名稱會設定為從 API Gateway 到 HTTP 整合端點的請求 URL 路徑，導致每個唯一 URL 路徑的 X-Ray 追蹤映射上有一個服務節點。大量的 URL 路徑可能會導致追蹤映射超過 10，000 個節點的限制，進而導致錯誤。 若要將 API Gateway 建立的服務節點數量降至最低，請考慮在 URL 查詢字串內或透過 POST 在請求內文中傳遞參數。這兩種方法都會確保參數不屬於 URL 路徑，這可能會導致不同的 URL 路徑和服務節點較少。 對於所有傳入請求，API Gateway 會將[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)新增至尚未有的傳入 HTTP 請求。 ``` X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793 ``` **X-Ray 追蹤 ID 格式** X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含： + 版本編號，即 `1`。 + 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。 例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒`1480615200`為單位或以十六進位數字`58406520`為單位。 + 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字**表示。 即使停用主動追蹤，如果請求是來自已抽樣請求並已開始追蹤的服務，階段仍會記錄區段。例如，經檢測的 Web 應用程式可以使用 HTTP 用戶端呼叫 API Gateway API。當您使用 X-Ray SDK 檢測 HTTP 用戶端時，它會將追蹤標頭新增至包含抽樣決策的傳出請求。API Gateway 會讀取追蹤標頭，並為取樣的請求建立區段。 如果您使用 API Gateway [為您的 API 產生 Java SDK](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-generate-sdk.html)，您可以透過使用用戶端建置器新增請求處理常式來檢測 SDK 用戶端，方法與手動檢測 AWS SDK 用戶端的方式相同。如需說明，請參閱 [使用適用於 Java 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-java-awssdkclients.md)。 # Amazon EC2 和 AWS App Mesh AWS X-Ray 與 整合[AWS App Mesh](https://docs.aws.amazon.com/app-mesh/latest/userguide/what-is-app-mesh.html)，以管理微服務的 Envoy 代理。App Mesh 提供 Envoy 的版本，您可以設定此版本將追蹤資料傳送至在相同任務或 Pod 的容器中執行的 X-Ray 協助程式。X-Ray 支援使用下列 App Mesh 相容服務進行追蹤： + Amazon Elastic Container Service (Amazon ECS) + Amazon Elastic Kubernetes Service (Amazon EKS) + Amazon Elastic Compute Cloud (Amazon EC2) 使用以下指示，了解如何透過 App Mesh 來啟用 X-Ray 追蹤。 ![\[追蹤映射，顯示用戶端與 App Mesh 服務之間的追蹤。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/appmesh-traceContents.png) 若要設定 Envoy 代理將資料傳送至 X-Ray，請在其容器定義中設定`ENABLE_ENVOY_XRAY_TRACING`[環境變數](https://docs.aws.amazon.com/app-mesh/latest/userguide/envoy.html#envoy-config)。 **注意** Envoy 的 App Mesh 版本目前不會根據設定的[取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)傳送追蹤。相反地，它使用 Envoy 1.16.3 版或更新版本的固定取樣率為 5%，或 Envoy 1.16.3 版之前的 50% 取樣率。 **Example Amazon ECS 的 Envoy 容器定義** ``` { "name": "envoy", "image": "public.ecr.aws/appmesh/aws-appmesh-envoy:envoy-version", "essential": true, "environment": [ { "name": "APPMESH_VIRTUAL_NODE_NAME", "value": "mesh/myMesh/virtualNode/myNode" }, { "name": "ENABLE_ENVOY_XRAY_TRACING", "value": "1" } ], "healthCheck": { "command": [ "CMD-SHELL", "curl -s http://localhost:9901/server_info | cut -d' ' -f3 | grep -q live" ], "startPeriod": 10, "interval": 5, "timeout": 2, "retries": 3 } ``` **注意** 若要進一步了解可用的 Envoy 區域地址，請參閱 AWS App Mesh 《 使用者指南》中的 [Envoy 映像](https://docs.aws.amazon.com/app-mesh/latest/userguide/envoy.html)。 如需在容器中執行 X-Ray 協助程式的詳細資訊，請參閱 [在 Amazon ECS 上執行 X-Ray 協助程式](xray-daemon-ecs.md)。對於包含服務網格、微服務、Envoy 代理和 X-Ray 協助程式的範例應用程式，請在 [App Mesh 範例 GitHub 儲存庫](https://github.com/aws/aws-app-mesh-examples/tree/master/examples)中部署`colorapp`範例。 **進一步了解** + [開始使用 AWS App Mesh](https://docs.aws.amazon.com/app-mesh/latest/userguide/getting_started.html) + [AWS App Mesh 和 Amazon ECS 入門](https://docs.aws.amazon.com/app-mesh/latest/userguide/mesh-getting-started-ecs.html) # AWS App Runner 和 X-Ray AWS App Runner 是 AWS 服務 ，提供快速、簡單且符合成本效益的方式，可將原始碼或容器映像直接部署到 中可擴展且安全的 Web 應用程式 AWS 雲端。您不需要學習新技術、決定要使用的運算服務，或知道如何佈建和設定 AWS 資源。如需詳細資訊，請參閱[什麼是 AWS App Runner](https://docs.aws.amazon.com/apprunner/latest/dg/what-is-apprunner.html)。 AWS App Runner 透過與 [AWS Distro for OpenTelemetry](xray-services-adot.md) (ADOT) 整合，將追蹤傳送至 X-Ray。使用 ADOT SDKs來收集容器化應用程式的追蹤資料，並使用 X-Ray 來分析並深入了解經檢測的應用程式。如需詳細資訊，請參閱[使用 X-Ray 追蹤 App Runner 應用程式](https://docs.aws.amazon.com/apprunner/latest/dg/monitor-xray.html)。 # 使用 記錄 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" } } ``` # CloudWatch 與 X-Ray 整合 AWS X-Ray 與 [CloudWatch Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)、CloudWatch RUM 和 CloudWatch Synthetics 整合，讓您更輕鬆地監控應用程式的運作狀態。啟用 Application Signals 的應用程式，以監控和疑難排解服務、用戶端頁面、Synthetics Canary 和服務相依性的運作狀態。 透過關聯 CloudWatch 指標、日誌和 X-Ray 追蹤，X-Ray 追蹤映射可提供服務的end-to-end檢視，協助您快速找出效能瓶頸並識別受影響的使用者。 使用 CloudWatch RUM，您可以執行實際使用者監控，從實際使用者工作階段近乎即時地收集和檢視 Web 應用程式效能的用戶端資料。使用 AWS X-Ray 和 CloudWatch RUM，您可以從應用程式的最終使用者開始，透過下游 AWS 受管服務來分析和偵錯請求路徑。這樣做有助於找出影響最終使用者的延遲趨勢和錯誤。 **Topics** + [CloudWatch RUM 和 AWS X-Ray](xray-services-RUM.md) + [使用 X-Ray 偵錯 CloudWatch 合成 Canary](xray-services-cloudwatch-synthetics.md) # CloudWatch RUM 和 AWS X-Ray 使用 Amazon CloudWatch RUM，您可以執行實際使用者監控，從實際使用者工作階段近乎即時地收集和檢視 Web 應用程式效能的用戶端資料。使用 AWS X-Ray 和 CloudWatch RUM，您可以透過下游 AWS 受管服務，分析和偵錯從應用程式最終使用者開始的請求路徑。這樣做有助於找出影響最終使用者的延遲趨勢和錯誤。 開啟使用者工作階段的 X-Ray 追蹤後，CloudWatch RUM 會將 X-Ray 追蹤標頭新增至允許的 HTTP 請求，並針對允許的 HTTP 請求記錄 X-Ray 區段。然後，您可以在 X-Ray 和 CloudWatch 主控台中查看來自這些使用者工作階段的追蹤和客群，包括 X-Ray 追蹤映射。 **注意** CloudWatch RUM 不會與 X-Ray 取樣規則整合。相反地，當您設定應用程式使用 CloudWatch RUM 時，請選擇取樣百分比。從 CloudWatch RUM 傳送的追蹤可能會產生額外費用。如需詳細資訊，請參閱 [AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)。 根據預設，從 CloudWatch RUM 傳送的用戶端追蹤不會連接到伺服器端追蹤。若要將用戶端追蹤與伺服器端追蹤連線，請設定 CloudWatch RUM Web 用戶端，將 X-Ray 追蹤標頭新增至這些 HTTP 請求。 **警告** 設定 CloudWatch RUM Web 用戶端將 X-Ray 追蹤標頭新增至 HTTP 請求，可能會導致跨來源資源共用 (CORS) 失敗。若要避免這種情況，請將 `X-Amzn-Trace-Id` HTTP 標頭新增至下游服務的 CORS 組態上允許的標頭清單。如果您使用 API Gateway 做為下游，請參閱[啟用 REST API 資源的 CORS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html)。強烈建議您在生產環境中新增用戶端 X-Ray 追蹤標頭之前，先測試您的應用程式。如需詳細資訊，請參閱 [CloudWatch RUM Web 用戶端文件](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md#http)。 如需 CloudWatch 中實際使用者監控的詳細資訊，請參閱[使用 CloudWatch RUM](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM.html)。若要設定您的應用程式以使用 CloudWatch RUM，包括使用 X-Ray 追蹤使用者工作階段，請參閱[設定應用程式以使用 CloudWatch RUM](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM-get-started.html)。 # 使用 X-Ray 偵錯 CloudWatch 合成 Canary CloudWatch Synthetics 是一項全受管服務，可讓您使用每天 24 小時、每分鐘執行一次的指令碼 Canary 來監控端點和 APIs。 您可以自訂 Canary 指令碼，以檢查下列項目中的變更： + 可用性 + 延遲 + 交易 + 中斷或失效的連結 + 逐步完成任務 + 頁面載入錯誤 + UI 資產的載入延遲 + 複雜的精靈流程 + 應用程式中的簽出流程 Canary 會沿著相同的路線，執行與客戶相同的動作和行為，持續驗證客戶的體驗。 若要深入了解如何設定 Synthetics 測試，請參閱[使用 Synthetics 建立及管理 Canary](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries.html)。 ![\[X-Ray 追蹤映射中的範例 Canary 節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-show-canary-active.png) 下列範例會示範您 Synthetics Canary 引起的偵錯問題常見使用案例。每個範例都會示範使用追蹤映射或 X-Ray Analytics 主控台進行偵錯的關鍵策略。 如需如何讀取追蹤映射並與之互動的詳細資訊，請參閱[檢視服務映射](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)。 如需如何讀取 X-Ray Analytics 主控台並與之互動的詳細資訊，請參閱[與 AWS X-Ray Analytics 主控台互動](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-analytics.html)。 **Topics** + [在追蹤映射中檢視錯誤報告增加的 Canary](#xray-services-cloudwatch-synthetics-workflows-which-canary) + [使用個別追蹤的追蹤詳細資訊映射來詳細檢視每個請求](#xray-services-cloudwatch-synthetics-workflows-trace-map) + [判斷上游和下游服務中持續性失敗的根本原因](#xray-services-cloudwatch-synthetics-workflows-root-cause) + [識別效能瓶頸和趨勢](#xray-services-cloudwatch-synthetics-workflows-bottlenecks) + [比較變更前後的延遲及錯誤率或容錯率](#xray-services-cloudwatch-synthetics-workflows-latency) + [決定所有 API 和 URL 的必要 Canary 涵蓋範圍](#xray-services-cloudwatch-synthetics-workflows-impact) + [使用群組專注於 Synthetics 測試](#xray-services-cloudwatch-synthetics-groups) ## 在追蹤映射中檢視錯誤報告增加的 Canary 若要查看 X-Ray 追蹤映射中的哪些 Canary 的錯誤、故障、限流率或回應時間變慢，您可以使用 `Client::Synthetic`[篩選條件](xray-console-filters.md)反白顯示 Synthetics Canary 用戶端節點。按一下節點會顯示整個請求的回應時間分佈。按一下兩個節點之間的邊緣，會顯示已傳送該連線之請求的詳細資訊。您也可以在追蹤映射中檢視相關下游服務的「遠端」推斷節點。 當您按一下 Synthetics 節點時，側邊面板上有一個在 **Synthetics 中檢視**按鈕，會將您重新導向至 Synthetics 主控台，您可以在其中檢查 Canary 詳細資訊。 ![\[X 射線追蹤映射中包含服務詳細資訊的範例 Canary 節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-servicedetail.png) ## 使用個別追蹤的追蹤詳細資訊映射來詳細檢視每個請求 若要判斷哪些服務產生最多延遲或導致錯誤，請在追蹤映射中選取追蹤，以叫用追蹤詳細資訊映射。個別追蹤詳細資訊映射會顯示單一請求的end-to-end路徑。使用此項目可了解呼叫的服務，並視覺化上游和下游服務。 ![\[X 射線追蹤詳細資訊映射中的範例 Canary 節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-tracemap.png) ## 判斷上游和下游服務中持續性失敗的根本原因 收到 Synthetics Canary 中故障的 CloudWatch 警示後，請使用 X-Ray 中追蹤資料的統計建模，在 X-Ray Analytics 主控台中判斷問題的可能根本原因。在 Analytics 主控台中，**回應時間根本原因**資料表會顯示記錄的實體路徑。X-Ray 會判斷追蹤中哪個路徑最有可能導致回應時間。格式指出實體遇到的階層，以回應時間根本原因結束。 下列範例顯示，在 API Gateway 上執行之 API "XXX" 的 Synthetics 測試由於來自 Amazon DynamoDB 資料表的輸送量容量例外狀況而失敗。 ![\[X-Ray 追蹤映射中的範例 Canary 節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-active-select.png) ![\[範例 Canary 節點根本原因。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-rootcause.png) ![\[指出 Canary 節點的範例註釋篩選條件。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-showannot.png) ## 識別效能瓶頸和趨勢 您可以使用來自 Synthetics Canary 的連續流量，在一段時間內填入追蹤詳細資訊映射，來檢視端點效能隨時間變化的趨勢。 ![\[指出 Canary 節點的範例註釋篩選條件。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-distribution.png) ## 比較變更前後的延遲及錯誤率或容錯率 精確指出發生變更的時間，以將該變更與 Canary 所發現問題的增加相關聯。使用 X-Ray Analytics 主控台將時間範圍前後的 定義為不同的追蹤集，在回應時間分佈中建立視覺差異。 ![\[指出 Canary 節點的範例註釋篩選條件。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-compare.png) ## 決定所有 API 和 URL 的必要 Canary 涵蓋範圍 利用 X-Ray Analytics 比較 Canary 和使用者的經歷。下面的 UI 中，藍色趨勢線表示 Canary，綠色趨勢線代表使用者。您也可以看到三個 URL 中有兩個沒有 Canary 測試。 ![\[指出 Canary 節點的範例註釋篩選條件。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-vs-customer.png) ## 使用群組專注於 Synthetics 測試 您可以使用篩選條件表達式來建立 X-Ray 群組，以專注於特定的一組工作流程，例如在 上執行的應用程式「www」的 Synthetics 測試 AWS Elastic Beanstalk。使用[複雜的關鍵字](xray-console-filters.md#console-filters-complex) `service()`和 `edge()` 來篩選服務和邊緣。 **Example 群組篩選條件表達式** ``` "edge(id(name: "www", type: "client::Synthetics"), id(name: "www", type: "AWS::ElasticBeanstalk::Environment"))" ``` ![\[Elastic Beanstalk www 的範例節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/synthetics-canary-active-www.png) # AWS Elastic Beanstalk 而且 AWS X-Ray **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 AWS Elastic Beanstalk 平台包括 X-Ray 協助程式。您可以在 Elastic Beanstalk 主控台或使用組態檔案設定 選項，以[執行協助程式](xray-daemon-beanstalk.md)。 在 Java SE 平台中，您可以使用 Buildfile 檔案搭配執行個體上的 Maven 或 Gradle 來建置應用程式。適用於 Java 的 X-Ray 開發套件 適用於 Java 的 AWS SDK 可從 Maven 取得，因此您只能部署應用程式程式碼並建置執行個體，以避免綁定和上傳所有相依性。 您可以使用 Elastic Beanstalk 環境屬性來設定 X-Ray SDK。Elastic Beanstalk 用來將環境屬性傳遞至應用程式的方法會因平台而異。根據您的平台，使用 X-Ray 開發套件的環境變數或系統屬性。 + **[Node.js 平台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_nodejs.container.html)** – 使用[環境變數](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars) + **[Java SE 平台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/java-se-platform.html)** – 使用[環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) + **[Tomcat 平台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/java-tomcat-platform.html)** – 使用[系統屬性](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops) 如需詳細資訊，請參閱《 AWS Elastic Beanstalk 開發人員指南》中的[設定 AWS X-Ray 偵錯](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html)。 # Elastic Load Balancing 和 AWS X-Ray Elastic Load Balancing 應用程式負載平衡器會將追蹤 ID 新增至名為 的標頭中的傳入 HTTP 請求`X-Amzn-Trace-Id`。 ``` X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793 ``` **X-Ray 追蹤 ID 格式** X-Ray `trace_id`由以連字號分隔的三個數字組成。例如 `1-58406520-a006649127e371903a2de979`。其中包含： + 版本編號，即 `1`。 + 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。 例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒為單位`1480615200`或以十六進位數字`58406520`為單位。 + 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字**表示。 負載平衡器不會將資料傳送至 X-Ray，也不會在服務地圖上顯示為節點。 如需詳細資訊，請參閱 Elastic Load Balancing 開發人員指南中的[為您的 Application Load Balancer 請求追蹤](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-request-tracing.html)。 # Amazon EventBridge 和 AWS X-Ray AWS X-Ray 與 Amazon EventBridge 整合，以追蹤透過 EventBridge 傳遞的事件。如果使用 X-Ray 開發套件檢測的服務將事件傳送至 EventBridge，追蹤內容會傳播到[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)中的下游事件目標。X-Ray 開發套件會自動挑選追蹤標頭，並將其套用至任何後續的檢測。此持續性可讓使用者在整個下游服務中追蹤、分析和偵錯，並提供更完整的系統檢視。 如需詳細資訊，請參閱[EventBridge 使用者指南》中的 EventBridge X-Ray 整合](https://docs.aws.amazon.com//eventbridge/latest/userguide/eb-xray-integ.html)。 *EventBridge * ## 在 X-Ray 服務地圖上檢視來源和目標 X-Ray [追蹤映射](xray-console-servicemap.md)會顯示連接來源和目標服務的 EventBridge 事件節點，如下列範例所示： ![\[X-Ray 會顯示連接來源和目標服務的 EventBridge 事件節點\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/service-map-eventbridge.png) ## 將追蹤內容傳播至事件目標 X-Ray SDK 可讓 EventBridge 事件來源將追蹤內容傳播至下游事件目標。下列特定語言範例示範從[啟用主動追蹤](https://docs.aws.amazon.com//lambda/latest/dg/services-xray.html#services-xray-api)的 Lambda 函數呼叫 EventBridge： ------ #### [ Java ] 新增 X-Ray 的必要相依性： + [AWS X-Ray 適用於 Java 的開發套件](https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-xray/) + [AWS X-Ray 適用於 Java 的 記錄器 SDK](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/) ``` package example; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.events.SQSEvent; import com.amazonaws.xray.AWSXRay; import com.amazonaws.services.eventbridge.AmazonEventBridge; import com.amazonaws.services.eventbridge.AmazonEventBridgeClientBuilder; import com.amazonaws.services.eventbridge.model.PutEventsRequest; import com.amazonaws.services.eventbridge.model.PutEventsRequestEntry; import com.amazonaws.services.eventbridge.model.PutEventsResult; import com.amazonaws.services.eventbridge.model.PutEventsResultEntry; import com.amazonaws.xray.handlers.TracingHandler; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.lang.StringBuilder; import java.util.Map; import java.util.List; import java.util.Date; import java.util.Collections; /* Add the necessary dependencies for XRay: https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-xray https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk */ public class Handler implements RequestHandler{ private static final Logger logger = LoggerFactory.getLogger(Handler.class); /* build EventBridge client */ private static final AmazonEventBridge eventsClient = AmazonEventBridgeClientBuilder .standard() // instrument the EventBridge client with the XRay Tracing Handler. // the AWSXRay globalRecorder will retrieve the tracing-context // from the lambda function and inject it into the HTTP header. // be sure to enable 'active tracing' on the lambda function. .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); @Override public String handleRequest(SQSEvent event, Context context) { PutEventsRequestEntry putEventsRequestEntry0 = new PutEventsRequestEntry(); putEventsRequestEntry0.setTime(new Date()); putEventsRequestEntry0.setSource("my-lambda-function"); putEventsRequestEntry0.setDetailType("my-lambda-event"); putEventsRequestEntry0.setDetail("{\"lambda-source\":\"sqs\"}"); PutEventsRequest putEventsRequest = new PutEventsRequest(); putEventsRequest.setEntries(Collections.singletonList(putEventsRequestEntry0)); // send the event(s) to EventBridge PutEventsResult putEventsResult = eventsClient.putEvents(putEventsRequest); try { logger.info("Put Events Result: {}", putEventsResult); } catch(Exception e) { e.getStackTrace(); } return "success"; } } ``` ------ #### [ Python ] 將下列相依性新增至您的 requirements.txt 檔案： ``` aws-xray-sdk==2.4.3 ``` ``` import boto3 from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all # apply the XRay handler to all clients. patch_all() client = boto3.client('events') def lambda_handler(event, context): response = client.put_events( Entries=[ { 'Source': 'foo', 'DetailType': 'foo', 'Detail': '{\"foo\": \"foo\"}' }, ] ) return response ``` ------ #### [ Go ] ``` package main import ( "context" "github.com/aws/aws-lambda-go/lambda" "github.com/aws/aws-lambda-go/events" "github.com/aws/aws-sdk-go/aws/session" "github.com/aws/aws-xray-sdk-go/xray" "github.com/aws/aws-sdk-go/service/eventbridge" "fmt" ) var client = eventbridge.New(session.New()) func main() { //Wrap the eventbridge client in the AWS XRay tracer xray.AWS(client.Client) lambda.Start(handleRequest) } func handleRequest(ctx context.Context, event events.SQSEvent) (string, error) { _, err := callEventBridge(ctx) if err != nil { return "ERROR", err } return "success", nil } func callEventBridge(ctx context.Context) (string, error) { entries := make([]*eventbridge.PutEventsRequestEntry, 1) detail := "{ \"foo\": \"foo\"}" detailType := "foo" source := "foo" entries[0] = &eventbridge.PutEventsRequestEntry{ Detail: &detail, DetailType: &detailType, Source: &source, } input := &eventbridge.PutEventsInput{ Entries: entries, } // Example sending a request using the PutEventsRequest method. resp, err := client.PutEventsWithContext(ctx, input) success := "yes" if err == nil { // resp is now filled success = "no" fmt.Println(resp) } return success, err } ``` ------ #### [ Node.js ] ``` const AWSXRay = require('aws-xray-sdk') //Wrap the aws-sdk client in the AWS XRay tracer const AWS = AWSXRay.captureAWS(require('aws-sdk')) const eventBridge = new AWS.EventBridge() exports.handler = async (event) => { let myDetail = { "name": "Alice" } const myEvent = { Entries: [{ Detail: JSON.stringify({ myDetail }), DetailType: 'myDetailType', Source: 'myApplication', Time: new Date }] } // Send to EventBridge const result = await eventBridge.putEvents(myEvent).promise() // Log the result console.log('Result: ', JSON.stringify(result, null, 2)) } ``` ------ #### [ C\$1 ] 將下列 X-Ray 套件新增至您的 C\$1 相依性： ``` ``` ``` using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Amazon; using Amazon.Util; using Amazon.Lambda; using Amazon.Lambda.Model; using Amazon.Lambda.Core; using Amazon.EventBridge; using Amazon.EventBridge.Model; using Amazon.Lambda.SQSEvents; using Amazon.XRay.Recorder.Core; using Amazon.XRay.Recorder.Handlers.AwsSdk; using Newtonsoft.Json; using Newtonsoft.Json.Serialization; [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))] namespace blankCsharp { public class Function { private static AmazonEventBridgeClient eventClient; static Function() { initialize(); } static async void initialize() { //Wrap the AWS SDK clients in the AWS XRay tracer AWSSDKHandler.RegisterXRayForAllServices(); eventClient = new AmazonEventBridgeClient(); } public async Task FunctionHandler(SQSEvent invocationEvent, ILambdaContext context) { PutEventsResponse response; try { response = await callEventBridge(); } catch (AmazonLambdaException ex) { throw ex; } return response; } public static async Task callEventBridge() { var request = new PutEventsRequest(); var entry = new PutEventsRequestEntry(); entry.DetailType = "foo"; entry.Source = "foo"; entry.Detail = "{\"instance_id\":\"A\"}"; List entries = new List(); entries.Add(entry); request.Entries = entries; var response = await eventClient.PutEventsAsync(request); return response; } } } ``` ------ # AWS Lambda 而且 AWS X-Ray **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 您可以使用 AWS X-Ray 來追蹤 AWS Lambda 函數。Lambda 會[執行 X-Ray 協助程式](xray-daemon.md)，並記錄區段，其中包含叫用和執行函數的詳細資訊。如需進一步檢測，您可以將 X-Ray 開發套件與您的 函數綁定，以記錄外撥通話並新增註釋和中繼資料。 如果您的 Lambda 函數是由另一個經檢測的服務呼叫，Lambda 會追蹤已取樣的請求，而無需任何其他組態。上游服務可以是經檢測的 Web 應用程式或其他 Lambda 函數。您的服務可以直接透過經檢測的 AWS SDK 用戶端叫用 函數，或使用經檢測的 HTTP 用戶端呼叫 API Gateway API。 AWS X-Ray 支援使用 AWS Lambda 和 Amazon SQS 追蹤事件驅動的應用程式。使用 CloudWatch 主控台查看與 Amazon SQS 佇列並由下游 Lambda 函數處理的每個請求的連線檢視。來自上游訊息生產者的追蹤會自動連結至來自下游 Lambda 消費者節點的追蹤，以end-to-end檢視。如需詳細資訊，請參閱[追蹤事件驅動的應用程式](xray-tracelinking.md)。 **注意** 如果您已啟用下游 Lambda 函數的追蹤，您還必須為呼叫下游函數的根 Lambda 函數啟用追蹤，下游函數才能產生追蹤。 如果您的 Lambda 函數依排程執行，或是由未經檢測的服務調用，您可以設定 Lambda 以使用主動追蹤來取樣和記錄調用。 **在 AWS Lambda 函數上設定 X-Ray 整合** 1. 開啟 [AWS Lambda 主控台](https://console.aws.amazon.com/lambda)。 1. 從左側導覽列選取**函數**。 1. 選擇函數。 1. 在**組態**索引標籤上，向下捲動至**其他監控工具**卡。您也可以選取左側導覽窗格中的**監控和操作工具**來尋找此卡。 1. 選擇 **Edit** (編輯)。 1. 在 **AWS X-Ray** 下，啟用 **Active tracing** (主動追蹤)。 在具有對應 X-Ray 開發套件的執行時間上，Lambda 也會執行 X-Ray 協助程式。 **Lambda 上的 X-Ray SDKs** + **適用於 Go 的 X-Ray 開發套件** – Go 1.7 和更新的執行時間 + **適用於 Java 的 X-Ray 開發套件** – Java 8 執行時間 + **適用於 Node.js 的 X-Ray 開發套件** – Node.js 4.3 和更新版本執行時間 + **適用於 Python 的 X-Ray 開發套件** – Python 2.7、Python 3.6 和更新的執行時間 + **適用於 .NET 的 X-Ray 開發套件** – .NET Core 2.0 和更新的執行時間 若要在 Lambda 上使用 X-Ray 開發套件，請在每次建立新版本時將其與您的函數程式碼綁定。您可以使用用於檢測在其他 服務上執行之應用程式的相同方法，來檢測 Lambda 函數。主要差別是，您無法使用軟體開發套件來檢測傳入的請求、制定抽樣決策及建立區段。 檢測 Lambda 函數和 Web 應用程式之間的另一個區別是，函數程式碼無法修改 Lambda 建立並傳送至 X-Ray 的區段。您可以建立子區段並記錄註釋和中繼資料，但您無法新增註釋和中繼資料到父區段。 如需詳細資訊，請參閱《 *AWS Lambda 開發人員指南*》中的[使用 AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/lambda-x-ray.html)。 # AWS Step Functions 而且 AWS X-Ray AWS X-Ray 與 整合 AWS Step Functions ，以追蹤和分析 Step Functions 的請求。您可以視覺化狀態機器的元件、識別效能瓶頸，以及對導致錯誤的請求進行故障診斷。如需詳細資訊，請參閱《 AWS Step Functions 開發人員指南》中的 [AWS X-Ray 和 Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)。 **在建立新的狀態機器時啟用 X-Ray 追蹤** 1. 開啟 Step Functions 主控台，網址為 [https://console.aws.amazon.com/states/](https://console.aws.amazon.com/states/)。 1. 選擇**建立狀態機器**。 1. 在**定義狀態機器**頁面上，選擇**使用程式碼片段撰寫**或**開始使用範本**。如果您選擇執行範例專案，則無法在建立期間啟用 X-Ray 追蹤。反之，請在建立狀態機器後啟用 X-Ray 追蹤。 1. 選擇 **Next (下一步)**。 1. 在**指定詳細資訊**頁面上，設定您的狀態機器。 1. 選擇**啟用 X-Ray 追蹤**。 **在現有狀態機器中啟用 X-Ray 追蹤** 1. 在 Step Functions 主控台中，選取您要啟用追蹤的狀態機器。 1. 選擇**編輯**。 1. 選擇**啟用 X-Ray 追蹤**。 1. （選用） 透過從許可視窗中選擇**建立新角色，為您的狀態機器自動產生新角色**以包含 X-Ray 許可。 ![\[Permissions section with options to create a new role, choose existing, or enter ARN.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/stepfunctions-permissions.png) 1. 選擇 **Save** (儲存)。 **注意** 當您建立新的狀態機器時，如果對請求進行取樣並在 Amazon API Gateway 或 等上游服務中啟用追蹤，則會自動追蹤 AWS Lambda。對於未透過主控台設定的任何現有狀態機器，例如透過 CloudFormation 範本，請檢查您是否具有授予足夠許可以啟用 X-Ray 追蹤的 IAM 政策。