本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
檢測 C# 代碼 AWS Lambda
Lambda 與 AWS X-Ray 整合,可協助您追蹤、偵錯和最佳化 Lambda 應用程式。您可以使用 X-Ray 來追蹤請求,因為它會周遊您應用程式中的資源,其中可能包含 Lambda 函數和其他 AWS 服務。
若要將追蹤資料傳送至 X-Ray,您可以使用以下三個 SDK 庫之一:
-
AWS 適用於 OpenTelemetry (ADOT) 的發行版
— 安全、可生產就緒且 AWS支援的 (OTel) SDK 發行版本 OpenTelemetry 。 -
適用於 .NET 的 AWS X-Ray SDK – 用於生成追蹤資料並將其傳送至 X-Ray 的 SDK。
-
適用於 AWS Lambda (.NET) 的 Powertools
— 實作無伺服器最佳做法並提高開發人員速度的開發人員工具組。
每個 SDK 均提供將遙測資料傳送至 X-Ray 服務的方法。然後,您可以使用 X-Ray 來檢視、篩選應用程式的效能指標並獲得洞察,從而識別問題和進行最佳化的機會。
重要
用於 AWS Lambda SDK 的 X-Ray 和 Powertools 是由提供的緊密集成的儀器解決方案的一部分。 AWS ADOT Lambda Layers 是用於追蹤檢測之業界通用標準的一部分,這類檢測一般會收集更多資料,但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。若要深入了解如何在兩者之間做選擇,請參閱在 AWS Distro for OpenTelemetry 和 X-Ray SDK 之間進行選擇。
章節
使用動力工具進行 AWS Lambda (.NET)和跟 AWS SAM 踪
請按照下面的步驟來下載,構建和部署示例你好世界 C# 應用程序與集成 Powertools
必要條件
若要完成本節中的步驟,您必須執行下列各項:
-
. NET 6 或. NET 8
-
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。要取得開發套件,請將 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 SDK,實體框架和 HTTP 請求提供自動檢測。若要查看完整的組態選項集,請參閱《AWS X-Ray 開發人員指南》中的適用於 .NET 的AWS X-Ray SDK。
新增所需的 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 下,打開 主動追蹤 。
-
選擇 儲存 。
透過 Lambda API 啟用追蹤
使用 AWS CLI 或 AWS SDK 在 Lambda 函數上設定追蹤功能,並使用下列 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 中顯示兩個單獨的應用程式,及其各自服務映射的圖表](images/sample-errorprocessor-servicemap.png)
X-Ray 無法追蹤應用程式的所有請求。X-Ray 會套用取樣演算法以確保追蹤的效率,同時仍提供所有請求的代表範本。取樣率為每秒 1 次請求和 5% 的額外請求。
注意
您無法針對函數設定 X-Ray 取樣率。
在 X-Ray 中,追蹤會記錄一或多個服務所處理之要求的相關資訊。Lambda 會記錄每個追蹤 2 個區段,在服務圖表上建立兩個節點。下列影像會強調顯示這兩個節點:
![具有單一函數的 X-Ray 服務映射。](images/xray-servicemap-function.png)
左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為我的函數,但一個具有的起源AWS::Lambda
,另一個具有的AWS::Lambda::Function
起源。如果AWS::Lambda
區段顯示錯誤,表示 Lambda 服務發生問題。如果AWS::Lambda::Function
區段顯示錯誤,表示您的函數發生問題。
![顯示特定 Lambda 調用每個子區段延遲的 X-Ray 追蹤。](images/nodejs-xray-timeline.png)
此範例會展開區AWS::Lambda::Function
段,以顯示其三個子區段:
-
初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。
-
調用 – 表示執行處理常式程式碼所花費的時間。
-
額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。
您也可以檢測 HTTP 用戶端、記錄 SQL 查詢,以及建立具有註釋和中繼資料的自訂子區段。如需詳細資訊,請參閱《AWS X-Ray 開發人員指南》中的 適用於 .NET 的 AWS X-Ray SDK 許可。
定價
作為免費方案的一部分,您可以每月免費使用 X-Ray 追蹤,最多達到一定限制。 AWS 達到閾值後,X-Ray 會收取追蹤儲存及擷取的費用。如需詳細資訊,請參閱 AWS X-Ray 定價