使用動力工具 AWS Lambda (. NET) 和 AWS SAM 用於追蹤使用 X-Ray SDK 來檢測您的. NET函數透過 Lambda 主控台來啟用追蹤使用 Lambda 啟用追蹤 API 使用啟動追蹤 AWS CloudFormation 解讀 X-Ray 追蹤

檢測 C＃代碼 AWS Lambda

Lambda 與 AWS X-Ray 整合，可協助您追蹤、偵錯和最佳化 Lambda 應用程式。您可以使用 X-Ray 來追蹤請求，因為它會周遊您應用程式中的資源，其中可能包含 Lambda 函數和其他 AWS 服務。

若要將追蹤資料傳送至 X-Ray，您可以使用以下三個資SDK源庫之一：

AWS () 發行版 — OpenTelemetry (ADOT) 的一個安全、可生產就緒且 AWS支援的發行版本。 OpenTelemetry OTel SDK
適用於 .NET 的 AWS X-Ray SDK— 用SDK於產生追蹤資料並將其傳送至 X-Ray。
動力工具 AWS Lambda (. NET) — 實作無伺服器最佳實務並提高開發人員速度的開發人員工具組。

將遙測資料傳送至 X-Ray 服務的每一種方式。SDKs然後，您可以使用 X-Ray 來檢視、篩選應用程式的效能指標並獲得洞察，從而識別問題和進行最佳化的機會。

重要

X-Ray 和 Powertools AWS Lambda SDKs 是由 AWS提供的緊密集成的儀器解決方案的一部分。ADOTLambda 層是業界範圍內追蹤儀器標準的一部分，一般會收集更多資料，但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。要了解有關在它們之間進行選擇的更多信息，請參閱選擇開放遙測發行 AWS 版和 X-Ray SDKs。

使用動力工具 AWS Lambda (. NET) 和 AWS SAM 用於追蹤

請按照下面的步驟下載，構建和部署示例你好世界 C＃應用程序與集成的 Powertools AWS Lambda （. NET) 模組使用 AWS SAM. 此應用程序實現了基本的API後端，並使用 Powertools 發出日誌，指標和跟踪。它由一個 Amazon API 網關端點和一個 Lambda 函數組成。當您將GET請求傳送至API閘道端點時，Lambda 函數會呼叫、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至 AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

若要完成本節中的步驟，您必須執行下列各項：

。 NET6 或. NET8
AWS CLI 第二版
AWS SAM CLI版本 1.75 或更高版本。如果您使用的是較舊版本的 AWS SAM CLI，請參閱升級 AWS SAM CLI.

部署範例 AWS SAM 應用程式

使用 Hello World TypeScript 範本初始化應用程式。


sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing

建置應用程式。
```
cd sam-app && sam build
```
部署應用程式。
```
sam deploy --guided
```
依照螢幕上的提示操作。若要接受互動體驗中提供的預設選項，請按下 Enter。

注意
因為HelloWorldFunction 可能沒有定義授權，這可以嗎？ ，請務必輸入y。

獲取已部署URL的應用程序：


aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

調用API端點：
```
curl <URL_FROM_PREVIOUS_STEP>
```
成功的話，您將會看到以下回應：
```
{"message":"hello world"}
```

若要取得函數的追蹤，請執行 sam 追蹤。


sam traces

追蹤輸出如下：


New XRay Service Graph
  Start time: 2023-02-20 23:05:16+08:00
  End time: 2023-02-20 23:05:16+08:00
  Reference Id: 0 - AWS::Lambda - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.814
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.429
  Reference Id: 2 - (Root) AWS::ApiGateway::Stage - sam-app/Prod - Edges: [0]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.839
  Reference Id: 3 - client - sam-app/Prod - Edges: [2]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 3] at (2023-02-20T23:05:16.521000) with id (1-63f38c2c-270200bf1d292a442c8e8a00) and duration (2.877s)
 - 2.839s - sam-app/Prod [HTTP: 200]
   - 2.836s - Lambda [HTTP: 200]
 - 2.814s - sam-app-HelloWorldFunction-pNjujb7mEoew [HTTP: 200]
 - 2.429s - sam-app-HelloWorldFunction-pNjujb7mEoew
   - 0.230s - Initialization
   - 2.389s - Invocation
     - 0.600s - ## FunctionHandler
       - 0.517s - Get Calling IP
   - 0.039s - Overhead

這是可透過網際網路存取的公用API端點。建議您在測試後刪除端點。
```
sam delete
```

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

使用 X-Ray SDK 來檢測您的. NET函數

您可以測試函數代碼以記錄中繼資料並追蹤下游呼叫。若要記錄函數對其他資源和服務所發出呼叫的詳細資訊，請使用適用於 .NET 的 AWS X-Ray SDK。若要取得SDK，請將AWSXRayRecorder套件新增至您的專案檔案。


<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="2.1.0" />
    <PackageReference Include="AWSSDK.Core" Version="3.7.103.24" />
    <PackageReference Include="AWSSDK.Lambda" Version="3.7.104.3" />
    <PackageReference Include="AWSXRayRecorder.Core" Version="2.13.0" />
    <PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.11.0" />
  </ItemGroup>
</Project>

有一系列 Nuget 軟件包提供自動檢測 AWS SDKs，實體框架和HTTP請求。若要查看完整的組態選項集，請參閱AWS X-Ray SDK的〈〉。 NET在AWS X-Ray 開發人員指南中。

新增所需的 Nuget 套件後，請設定自動檢測。最佳實務是在函數的處理常式函數之外執行此設定。這麼做可讓您利用執行環境重新使用來改善函數的效能。在下列程式碼範例中，會在函數建構函式中呼叫RegisterXRayForAllServices方法，以便為所有 AWS SDK呼叫新增分析。


[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        // Add auto instrumentation for all AWS SDK calls
        // It is important to call this method before initializing any SDK clients
        AWSSDKHandler.RegisterXRayForAllServices();
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

透過 Lambda 主控台來啟用追蹤

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

開啟主動追蹤

開啟 Lambda 主控台中的函數頁面。
選擇一個函數。
選擇組態，然後選擇 監控和操作工具 。
選擇編輯。
在 X-Ray 下，打開 主動追蹤 。
選擇 Save (儲存)。

使用 Lambda 啟用追蹤 API

使用 AWS CLI 或設定 Lambda 函數的追蹤 AWS SDK，請使用下列API作業：

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


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

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

使用啟動追蹤 AWS CloudFormation

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

範例 function-inline.yml - 追蹤組態


Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

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

範例 template.yml - 追蹤組態


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

解讀 X-Ray 追蹤

您的函數需要將追蹤資料上傳至 X-Ray 的許可。當您在 Lambda 主控台中啟用追蹤時，Lambda 會將必要的許可新增至函數的執行角色。否則，請將AWSXRayDaemonWriteAccess原則新增至執行角色。

設定主動追蹤之後，您可以透過應用程式來觀察特定請求。X-Ray 服務圖顯示了有關應用程式及其所有元件的資訊。下列範例顯示具有兩個函式的應用程式。主要函式會處理事件，有時會傳回錯誤。頂部的第二個函數處理出現在第一個日誌組中的錯誤，並使用調 AWS SDK用 X-Ray，Amazon 簡單存儲服務（Amazon S3）和亞馬遜 CloudWatch 日誌。

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

左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為我的函數，但一個具有的起源AWS::Lambda，另一個具有的AWS::Lambda::Function起源。如果AWS::Lambda區段顯示錯誤，表示 Lambda 服務發生問題。如果AWS::Lambda::Function區段顯示錯誤，表示您的函數發生問題。

此範例會展開區AWS::Lambda::Function段以顯示其三個子區段。

注意

AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統記錄訊息的結構和內容，以及. AWS 帳戶

此處顯示的示例跟踪說明了舊式函數段。以下段落說明舊樣式和新樣式區段之間的差異。

這些變更將在未來幾週內實施，除了中國和 GovCloud 地區以 AWS 區域外的所有功能都將轉換為使用新格式的日誌訊息和追蹤區段。

舊式函數段包含以下子段：

初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。
調用 – 表示執行處理常式程式碼所花費的時間。
額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。

新樣式的函數段不包含Invocation子段。相反，客戶子段直接附加到功能段。如需舊式和新型式函數區段結構的詳細資訊，請參閱了解 X-Ray 追蹤。

您也可以檢測用HTTP戶端、記錄SQL查詢，以及使用註釋和中繼資料建立自訂子區段。如需詳細資訊，請參閱《AWS X-Ray 開發人員指南》中的適用於 .NET 的 AWS X-Ray SDK 許可。

定價

作為免費方案的一部分，您可以每月免費使用 X-Ray 追蹤，最多達到一定限制。 AWS 達到閾值後，X-Ray 會收取追蹤儲存及擷取的費用。如需詳細資訊，請參閱 AWS X-Ray 定價。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

日誌

測試

檢測 C＃ 代碼 AWS Lambda

重要

章節