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

# 使用 視覺化 Lambda 函數叫用 AWS X-Ray
<a name="services-xray"></a>

您可以使用 AWS X-Ray 視覺化應用程式的元件、識別效能瓶頸，以及對導致錯誤的請求進行故障診斷。您的 Lambda 函數會將追蹤資料傳送至 X-Ray，而且 X-Ray 會處理資料，以產生服務映射和可搜尋的追蹤摘要。

Lambda 支援兩種 X-Ray 追蹤模式：`Active` 和 `PassThrough`。啟用 `Active` 追蹤時，Lambda 會自動為函式調用建立追蹤區段，並將其傳送至 X-Ray。另一方面，`PassThrough` 模式僅會將追蹤內容傳播至下游服務。若您已為函式啟用 `Active` 追蹤，Lambda 會自動將取樣請求的追蹤傳送至 X-Ray。通常，上游服務 (例如 Amazon API Gateway) 或託管於 Amazon EC2 且嵌入 X-Ray SDK 的應用程式，會決定是否應該追蹤傳入請求，而後將該取樣決策新增為追蹤標頭。Lambda 會使用該標頭來決定是否傳送追蹤。來自上游訊息生產者的追蹤 (例如 Amazon SQS) 會自動連結至來自下游 Lambda 函數的追蹤，進而建立整個應用程式的端對端檢視。如需詳細資訊，請參閱《AWS X-Ray 開發人員指南》**中的[追蹤事件導向應用程式](https://docs.aws.amazon.com//xray/latest/devguide/xray-tracelinking.html)。

**注意**  
Lambda 函數若具有 Amazon Managed Streaming for Apache Kafka (Amazon MSK)、自我管理的 Apache Kafka、帶有 ActiveMQ 和 RabbitMQ 的 Amazon MQ，或是 Amazon DocumentDB 事件來源映射，目前不支援 X-Ray 追蹤。

若要使用控制台在 Lambda 函數上切換主動追蹤，請按照下列步驟操作：

**開啟主動追蹤**

1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。

1. 選擇一個函數。

1. 選擇**組態**，然後選擇**監控和操作工具**。

1. 在**其他監控工具**欄位中，選擇**編輯**。

1. 在 **CloudWatch Application Signals 和 AWS X-Ray** 下，選擇**啟用** **Lambda 服務追蹤**。

1. 選擇**儲存**。

您的函數需要將追蹤資料上傳至 X-Ray 的許可。當您在 Lambda 主控台中啟用追蹤時，Lambda 會將必要的許可新增至函數的[執行角色](lambda-intro-execution-role.md)。否則，請將 [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess) 政策新增至執行角色。

X-Ray 無法追蹤應用程式的所有請求。X-Ray 會套用取樣演算法以確保追蹤的效率，同時仍提供所有請求的代表範本。取樣率為每秒 1 次請求和 5% 的額外請求。不能針對函數設定 X-Ray 取樣率。

## 了解 X-Ray 追蹤
<a name="services-xray-traces"></a>

在 X-Ray 中，*追蹤*會記錄一或多個*服務*所處理之要求的相關資訊。Lambda 會在每個追蹤上記錄 2 個區段，這會在服務圖表上建立兩個節點。下圖反白顯示了這兩個節點：

![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/xray-servicemap-function.png)


左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。

為 Lambda 服務記錄的區段 `AWS::Lambda` 涵蓋準備 Lambda 執行環境所需的所有步驟。這包括排程 MicroVM、使用您設定的資源建立或取消凍結執行環境，以及下載函數程式碼和所有層。

`AWS::Lambda::Function` 區段用於函數要完成的工作。

**注意**  
AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統日誌訊息的結構和內容，與 AWS 帳戶中不同 Lambda 函數發出的追蹤區段之間存在細微差異。  
此變更會影響該函數區段的子區段。以下段落說明這些子區段的舊格式和新格式。  
這些變化將在未來幾週內實作，除中國和 GovCloud 區域以外，所有 AWS 區域 中的所有函數都會轉換至使用新格式的日誌訊息和追蹤區段。

**舊式 AWS X-Ray Lambda 區段結構**  
`AWS::Lambda` 區段的舊式 X-Ray 結構如下所示：

![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/V2_sandbox_images/v1_XRay_structure.png)


在此格式中，函數區段具有 `Initialization`、`Invocation` 和 `Overhead` 的子區段。另外，對於 [Lambda SnapStart](snapstart.md) 還有一個 `Restore` 子區段 (此圖表中未顯示)。

`Initialization` 子區段代表 Lambda 執行環境生命週期的初始化階段。在此階段，Lambda 會初始化延伸模組、初始化執行時期，並執行函數的初始化程式碼。

`Invocation` 子區段表示調用階段，其中 Lambda 調用函數處理常式。這從執行時間和延伸註冊開始，並在執行時間準備傳送響應時結束。

(僅限 Lambda SnapStart) `Restore` 子區段會顯示 Lambda 還原快照、載入執行時期和執行任何還原後[執行時期勾點](snapstart-runtime-hooks.md)所需的時間。還原快照的程序可能包括在 MicroVM 以外的活動上花費的時間。此時間在 `Restore` 子區段中報告。您不需要為在 MicroVM 外還原快照所花費的時間付費。

`Overhead` 子區段表示當執行時間傳送響應和下一次調用信號之間的時間發生的階段。在此期間，執行時間會完成與調用相關的所有工作，並準備凍結沙盒。

**重要**  
您可以使用 X-Ray 開發套件來擴充 `Invocation` 子區段與下游呼叫、註釋和中繼資料的其他子區段。您無法直接存取函數區段，或在處理常式調用範圍之外記錄完成的工作。

如需 Lambda 執行環境階段的詳細資訊，請參閱[了解 Lambda 執行環境生命週期](lambda-runtime-environment.md)。

下圖顯示了使用舊式 X-Ray 結構的追蹤範例。

![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png)


請注意此範例中的兩個區段。兩者都被命名為 **my-function**，但其中之一的來源為 `AWS::Lambda`，而另一個的來源為 `AWS::Lambda::Function`。如果 `AWS::Lambda` 區段顯示錯誤，Lambda 服務就會出現問題。如果 `AWS::Lambda::Function` 區段顯示錯誤，表示您的函數出現了問題。

**注意**  
偶爾您可能會注意到 X-Ray 追蹤中的函數初始化和調用階段之間存在很大的差距。對於使用[佈建並行](provisioned-concurrency.md)的函數，這是因為 Lambda 會在調用之前才初始化函數執行個體。對於使用[未預留 (隨需) 並行](lambda-concurrency.md)的函數，即使沒有調用，Lambda 也可能會主動初始化函數執行個體。從視覺上看，這兩種情況都會顯示為初始化和調用階段之間的時間差距。

**新樣式 AWS X-Ray 的 Lambda 區段結構**  
`AWS::Lambda` 區段的新式 X-Ray 結構如下所示：

![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/V2_sandbox_images/v2_XRay_structure.png)


在此新格式中，`Init` 子區段和以往一樣代表 Lambda 執行環境生命週期的初始化階段。

新格式中沒有調用區段。而客戶子區段則直接連接到 `AWS::Lambda::Function` 區段。此區段包含以下指標做為註釋：
+ `aws.responseLatency`：函數執行所需的時間
+ `aws.responseDuration`：將回應傳輸給客戶所需的時間
+ `aws.runtimeOverhead`：完成執行時期所需的額外時間
+ `aws.extensionOverhead`：延伸功能完成所需的額外時間

下圖顯示了使用新式 X-Ray 結構的追蹤範例。

![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v2.png)


請注意此範例中的兩個區段。兩者都被命名為 **my-function**，但其中之一的來源為 `AWS::Lambda`，而另一個的來源為 `AWS::Lambda::Function`。如果 `AWS::Lambda` 區段顯示錯誤，Lambda 服務就會出現問題。如果 `AWS::Lambda::Function` 區段顯示錯誤，表示您的函數出現了問題。

如需在 Lambda 追蹤的語言特定簡介，請參閱下列主題：
+ [在 中檢測 Node.js 程式碼 AWS Lambda](nodejs-tracing.md)
+ [在 中檢測 Python 程式碼 AWS Lambda](python-tracing.md)
+ [在 中檢測 Ruby 程式碼 AWS Lambda](ruby-tracing.md)
+ [在 中檢測 Java 程式碼 AWS Lambda](java-tracing.md)
+ [在 中檢測 Go 程式碼 AWS Lambda](golang-tracing.md)
+ [在 中檢測 C\$1 程式碼 AWS Lambda](csharp-tracing.md)

如需支援主動設備測試之服務的完整清單，請參閱《 AWS X-Ray 開發人員指南》中的 [Supported AWS 服務](https://docs.aws.amazon.com/xray/latest/devguide/xray-usage.html#xray-usage-codechanges) 一節。

## Lambda 中的預設追蹤行為
<a name="services-xray-default"></a>

若未啟用 `Active` 追蹤，Lambda 會預設為使用 `PassThrough` 追蹤模式。

在 `PassThrough` 模式下，Lambda 會將 X-Ray 追蹤標頭轉送至下游服務，但不會自動傳送追蹤。即使追蹤標頭包含對請求進行取樣的決策，情況也是如此。如果上游服務不提供 X-Ray 追蹤標頭，Lambda 會產生標頭，並決定不進行取樣。不過，您可以從函式程式碼呼叫追蹤程式庫來傳送自己的追蹤。

**注意**  
 先前，當上游服務 (如 Amazon API Gateway) 新增追蹤標頭時，Lambda 會自動傳送追蹤。Lambda 不自動傳送追蹤資料，讓您能自主控制，只追蹤對自己而言重要的函式。若解決方案取決於此被動追蹤行為，請切換至 `Active` 追蹤。

## 執行角色許可
<a name="services-xray-permissions"></a>

Lambda 需要下列許可才能傳送追蹤資料到 X-Ray。新增許可到您的函數的[執行角色](lambda-intro-execution-role.md)。
+ [xray:PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)
+ [xray:PutTelemetryRecords](https://docs.aws.amazon.com/xray/latest/api/API_PutTelemetryRecords.html)

這些許可包含在 [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess) 受管政策中。

## 透過 Lambda API 啟用 `Active` 追蹤
<a name="services-xray-api"></a>

若要使用 AWS CLI 或 AWS SDK 管理追蹤組態，請使用下列 API 操作：
+ [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+ [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html)
+ [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html)

下列範例 AWS CLI 命令會在名為 **my-function** 的函數上啟用主動追蹤。

```
aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active
```

追蹤模式是您發布函數版本時版本特定組態的一部分。您無法變更已發佈版本上的追蹤模式。

## 使用 啟用`Active`追蹤 CloudFormation
<a name="services-xray-cloudformation"></a>

若要在 CloudFormation 範本中的 `AWS::Lambda::Function` 資源上啟用追蹤，請使用 `TracingConfig` 屬性。

**Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml) - 追蹤組態**  

```
Resources:
  function:
    Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
    Properties:
      TracingConfig:
        Mode: Active
      ...
```

對於 AWS Serverless Application Model (AWS SAM) `AWS::Serverless::Function` 資源，請使用 `Tracing` 屬性。

**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml) - 追蹤組態**  

```
Resources:
  function:
    Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
    Properties:
      Tracing: Active
      ...
```