# 在 AWS Lambda 中检测 C\$1 代码 Lambda 与 AWS X-Ray 集成，以帮助您跟踪、调试和优化 Lambda 应用程序。您可以在某个请求遍历应用程序中的资源（其中可能包括 Lambda 函数和其他 AWS 服务）时，使用 X-Ray 跟踪该请求。 要将跟踪数据发送到 X-Ray，您可以使用以下三个开发工具包库之一： + [适用于 OpenTelemetry 的 AWS 发行版 (ADOT)](https://aws.amazon.com/otel) – 一种安全、可供生产、支持 AWS 的 OpenTelemetry (OTel) SDK 的分发版本。 + [AWS X-Ray SDK for .NET](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html) – 用于生成跟踪数据并将其发送到 X-Ray 的 SDK + [Powertools for AWS Lambda（.NET）](https://docs.aws.amazon.com/powertools/dotnet/)– 一个开发人员工具包，用于实施无服务器最佳实践并提高开发人员速度。 每个开发工具包均提供了将遥测数据发送到 X-Ray 服务的方法。然后，您可以使用 X-Ray 查看、筛选和获得对应用程序性能指标的洞察，从而发现问题和优化机会。 **重要** X-Ray 和 Powertools for AWS Lambda SDK 是 AWS 提供的紧密集成的分析解决方案的一部分。ADOT Lambda Layers 是全行业通用的跟踪分析标准的一部分，该标准通常会收集更多数据，但可能不适用于所有使用案例。您可以使用任一解决方案在 X-Ray 中实现端到端跟踪。要了解有关如何在两者之间进行选择的更多信息，请参阅[在 AWS Distro for Open Telemetry 和 X-Ray 开发工具包之间进行选择](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing)。 **Topics** + [将 Powertools for AWS Lambda（.NET）和 AWS SAM 用于跟踪](#dotnet-tracing-sam) + [使用 X-Ray SDK 分析 .NET 函数](#dotnet-xray-sdk) + [使用 Lambda 控制台激活跟踪](#dotnet-tracing-console) + [使用 Lambda API 激活跟踪](#dotnet-tracing-api) + [使用 CloudFormation 激活跟踪](#dotnet-tracing-cloudformation) + [解释 X-Ray 跟踪](#dotnet-tracing-interpretation) ## 将 Powertools for AWS Lambda（.NET）和 AWS SAM 用于跟踪 请按照以下步骤使用 AWS SAM，通过集成的 [Powertools for AWS Lambda（.NET）](https://docs.powertools.aws.dev/lambda-dotnet)模块来下载、构建和部署示例 Hello World C\$1 应用程序。此应用程序实现了基本的 API 后端，并使用 Powertools 发送日志、指标和跟踪。它由 Amazon API Gateway 端点和 Lambda 函数组成。在向 API Gateway 端点发送 GET 请求时，Lambda 函数会使用嵌入式指标格式向 CloudWatch 调用、发送日志和指标，并向 AWS X-Ray 发送跟踪。该函数将返回一条 hello world 消息。 **先决条件** 要完成本节中的步骤，您必须满足以下条件： + .NET 8 + [AWS CLI 版本 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [AWS SAM CLI 版本 1.75 或更高版本](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)。如果您使用的是旧版本的 AWS SAM CLI，请参阅[升级 AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade)。 **部署示例 AWS SAM 应用程序** 1. 使用 Hello World TypeScript 模板初始化该应用程序。 ``` sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing ``` 1. 构建应用程序。 ``` cd sam-app && sam build ``` 1. 部署应用程序。 ``` sam deploy --guided ``` 1. 按照屏幕上的提示操作。要在交互式体验中接受提供的默认选项，请按 `Enter`。 **注意** 对于 **HelloWorldFunction 可能没有定义授权，确定执行此操作吗？**，确保输入 `y`。 1. 获取已部署应用程序的 URL： ``` aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text ``` 1. 调用 API 端点： ``` curl ``` 如果成功，您将会看到如下响应： ``` {"message":"hello world"} ``` 1. 要获取该函数的跟踪信息，请运行 [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html)。 ``` 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 ``` 1. 这是一个可以通过互联网访问的公有 API 端点。我们建议您在测试后删除该端点。 ``` sam delete ``` X-Ray 无法跟踪对应用程序的所有请求。X-Ray 将应用采样算法确保跟踪有效，同时仍会提供所有请求的一个代表性样本。采样率是每秒 1 个请求和 5% 的其他请求。您无法为函数配置此 X-Ray 采样率。 ## 使用 X-Ray SDK 分析 .NET 函数 您可以使用函数代码来记录元数据并跟踪下游调用。要记录有关您的函数对其他资源和服务进行调用的详细信息，请使用 AWS X-Ray SDK for .NET。要获取开发工具包，请将 `AWSXRayRecorder` 程序包添加到您的项目文件中。 ``` net8.0 true Lambda ``` 有一系列 Nuget 软件包可以为 AWS SDK、实体框架和 HTTP 请求提供自动分析。要查看完整的配置选项集，请参阅《AWS X-Ray 开发人员指南》**中的[适用于 .NET 的 AWS X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html)。 添加所需的 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 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 函数的活动跟踪，请按照以下步骤操作： **打开活跃跟踪** 1. 打开 Lamba 控制台的[函数](https://console.aws.amazon.com/lambda/home#/functions)页面。 1. 选择函数。 1. 选择 **Configuration**（配置），然后选择 **Monitoring and operations tools**（监控和操作工具）。 1. 在**其他监控工具**下，选择**编辑**。 1. 在 **CloudWatch 应用程序信号和 AWS X-Ray** 下，为 **Lambda 服务跟踪**选择**启用**。 1. 选择**保存**。 ## 使用 Lambda API 激活跟踪 借助 AWS CLI 或 AWS SDK 在 Lambda 函数上配置跟踪，请使用以下 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 ``` 跟踪模式是发布函数版本时版本特定配置的一部分。您无法更改已发布版本上的跟踪模式。 ## 使用 CloudFormation 激活跟踪 要对 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 ... ``` ## 解释 X-Ray 跟踪 您的函数需要权限才能将跟踪数据上载到 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 服务图](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph)将显示有关应用程序及其所有组件的信息。以下示例显示了具有两个函数的应用程序。主函数处理事件，有时会返回错误。位于顶部的第二个函数将处理第一个函数的日志组中显示的错误，并使用 AWS SDK 调用 X-Ray、Amazon Simple Storage Service (Amazon S3) 和 Amazon CloudWatch Logs。 ![\[\]](http://docs.aws.amazon.com/zh_cn/lambda/latest/dg/images/sample-errorprocessor-servicemap.png) X-Ray 无法跟踪对应用程序的所有请求。X-Ray 将应用采样算法确保跟踪有效，同时仍会提供所有请求的一个代表性样本。采样率是每秒 1 个请求和 5% 的其他请求。您无法为函数配置此 X-Ray 采样率。 在 X-Ray 中，*跟踪*记录有关由一个或多个*服务*处理的请求的信息。Lambda 会每个跟踪记录 2 个分段，这些分段将在服务图上创建两个节点。下图突出显示了这两个节点： ![\[\]](http://docs.aws.amazon.com/zh_cn/lambda/latest/dg/images/xray-servicemap-function.png) 位于左侧的第一个节点表示接收调用请求的 Lambda 服务。第二个节点表示特定的 Lambda 函数。以下示例显示了一个包含这 2 个分段的跟踪。两者都命名为 **my-function**，但其中一个函数具有 `AWS::Lambda` 源，另一个则具有 `AWS::Lambda::Function` 源。如果 `AWS::Lambda` 分段显示错误，则表示 Lambda 服务存在问题。如果 `AWS::Lambda::Function` 分段显示错误，则说明函数存在问题。 ![\[\]](http://docs.aws.amazon.com/zh_cn/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png) 此示例将展开 `AWS::Lambda::Function` 分段，以显示其三个子分段。 **注意** AWS 目前正在实施对 Lambda 服务的更改。由于这些更改，您可能会看到 AWS 账户 中不同 Lambda 函数发出的系统日志消息和跟踪分段的结构和内容之间存在细微差异。 此处显示的示例跟踪说明了旧样式函数分段。以下段落介绍了新旧样式分段之间的差异。 这些更改将在未来几周内实施，除中国和 GovCloud 区域外，所有 AWS 区域 的函数都将过渡到使用新格式的日志消息和跟踪分段。 旧样式函数分段包含以下子分段： + **初始化** – 表示加载函数和运行[初始化代码](foundation-progmodel.md)所花费的时间。此子分段仅对由您的函数的每个实例处理的第一个事件显示。 + **调用** – 表示执行处理程序代码花费的时间。 + **开销** – 表示 Lambda 运行时为准备处理下一个事件而花费的时间。 新样式函数分段不包含 `Invocation` 子分段。而是将客户子分段直接附加到函数分段。有关新旧样式函数分段结构的更多信息，请参阅 [了解 X-Ray 跟踪](services-xray.md#services-xray-traces)。 您还可以分析 HTTP 客户端、记录 SQL 查询以及使用注释和元数据创建自定义子段。有关更多信息，请参阅 *AWS X-Ray 开发人员指南*中的 [AWS X-Ray SDK for .NET](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html)。 **定价** 作为 AWS 免费套餐的组成部分，您可以每月免费使用 X-Ray 跟踪，但不能超过一定限制。超出该阈值后，X-Ray 会对跟踪存储和检索进行收费。有关更多信息，请参阅 [AWS X-Ray 定价](https://aws.amazon.com/xray/pricing/)。