使用 X-Ray 跟踪您的 App Runner 应用程序

AWS X-Ray 是一项服务，它收集有关您的应用程序所处理的请求的数据，并提供可用于查看、筛选和深入了解这些数据的工具，以识别问题和优化机会。对于对应用程序的任何跟踪请求，您不仅可以查看有关请求和响应的详细信息，还可以查看有关您的应用程序对下游 AWS 资源、微服务、数据库和 HTTP Web API 的调用的详细信息。

X-Ray 使用来自为云应用程序提供支持的 AWS 资源的跟踪数据来生成详细的服务图。该服务图显示客户端、您的前端服务以及前端服务调用来处理请求和保存数据的后端服务。您可以使用服务图来查明瓶颈、延迟峰值和其他需要解决的问题，以提高应用程序性能。

有关 X-Ray 的更多信息，请参阅 AWS X-Ray 开发人员指南。

检测您的应用程序以进行跟踪

使用便携式遥测规范 OpenTelemetry，检测您的 App Runner 服务应用程序以进行跟踪。目前，App Runner 支持 AWS Distro fo OpenTelemetry r (ADOT)，这是一种使用服务收集和呈现遥测信息的 OpenTelemetry实现。 AWS X-Ray 实现了跟踪组件。

根据您在应用程序中使用的特定 ADOT SDK，ADOT 最多支持两种检测方法：自动和手动。有关使用您的 SDK 进行检测的更多信息，请参阅 ADOT 文档，然后在导航窗格中选择您的 SDK。

运行时设置

以下是用于检测您的 App Runner 服务应用程序以进行跟踪的一般运行时设置说明。

为运行时设置跟踪

1. 按照 AWS Distro for OpenTelemetry (ADOT) 中为你的运行时提供的说明来检测你的应用程序。

2. 如果您使用的是源代码存储库，则在apprunner.yaml文件build部分安装所需的OTEL依赖项；如果您使用的是容器镜像，则在 Dockerfile 中安装所需的依赖项。

3. 如果您使用的是源代码存储库，则在apprunner.yaml文件中设置环境变量；如果您使用的是容器镜像，则在 Dockerfile 中设置环境变量。

   例 环境变量

   注意

   以下示例列出了要添加到apprunner.yaml文件中的重要环境变量。如果您使用的是容器镜像，请将这些环境变量添加到您的 Dockerfile 中。但是，每个运行时可能都有自己的特点，您可能需要在以下列表中添加更多环境变量。有关运行时特定说明的更多信息以及有关如何为运行时设置应用程序的示例，请参阅 AWS Distro for for OpenTelemetry 并转到 “入门” 下的 “运行时”。

   env:
       - name: OTEL_PROPAGATORS
         value: xray
       - name: OTEL_METRICS_EXPORTER
         value: none
       - name: OTEL_EXPORTER_OTLP_ENDPOINT
         value: http://localhost:4317  
       - name: OTEL_RESOURCE_ATTRIBUTES
         value: 'service.name=example_app'

   注意

   OTEL_METRICS_EXPORTER=none是 App Runner 的重要环境变量，因为 App Runner Otel 收集器不接受指标记录。它只接受指标跟踪。

运行时设置示例

以下示例演示如何使用 AD OT Python SDK 自动检测您的应用程序。SDK 会自动生成包含遥测数据的跨度，这些数据描述了 Python 框架在应用程序中使用的值，而无需添加一行 Python 代码。您只需要在两个源文件中添加或修改几行。

首先，添加一些依赖关系，如以下示例所示。

例 requirements.txt

opentelemetry-distro[otlp]>=0.24b0
opentelemetry-sdk-extension-aws~=2.0
opentelemetry-propagator-aws-xray~=1.0

然后，对您的应用程序进行检测。执行此操作的方法取决于您的服务来源，即源图像或源代码。

Source image

当您的服务源是镜像时，您可以直接检测 Dockerfile，该文件控制构建容器镜像和在镜像中运行应用程序。以下示例显示了用于 Python 应用程序的经过检测的 DockerFile。新增的仪器以粗体显示。

例 Dockerfile

FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install python3.7 -y && curl -O https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py && yum update -y
COPY . /app
WORKDIR /app
RUN pip3 install -r requirements.txt
RUN opentelemetry-bootstrap --action=install
ENV OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=urllib3
ENV OTEL_METRICS_EXPORTER=none              
ENV OTEL_RESOURCE_ATTRIBUTES='service.name=example_app'
CMD OTEL_PROPAGATORS=xray OTEL_PYTHON_ID_GENERATOR=xray opentelemetry-instrument python3 app.py
EXPOSE 8080

Source code repository

当您的服务源是包含应用程序源的存储库时，您可以使用 App Runner 配置文件设置间接检测映像。这些设置控制 App Runner 生成的 Dockerfile，这些文件用于为你的应用程序构建镜像。以下示例显示了 Python 应用程序的经过检测的 App Runner 配置文件。新增的仪器以粗体显示。

例 apprunner.yaml

version: 1.0
runtime: python3 
build:
  commands:
    build:
      - pip install -r requirements.txt
      - opentelemetry-bootstrap --action=install
run: 
  command: opentelemetry-instrument python app.py
  network: 
    port: 8080 
  env:
    - name: OTEL_PROPAGATORS
      value: xray
    - name: OTEL_METRICS_EXPORTER
      value: none
    - name: OTEL_PYTHON_ID_GENERATOR
      value: xray  
    - name: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS 
      value: urllib3
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: 'service.name=example_app'

为您的 App Runner 服务实例角色添加 X-Ray 权限

要将 X-Ray 跟踪与 App Runner 服务一起使用，您必须为该服务的实例提供与 X-Ray 服务交互的权限。为此，您可以将实例角色与您的服务关联并添加具有 X-Ray 权限的托管策略。有关 App Runner 实例角色的更多信息，请参阅实例角色。将AWSXRayDaemonWriteAccess托管策略添加到您的实例角色并在创建期间将其分配给您的服务。

为您的 App Runner 服务启用 X-Ray 跟踪

创建服务时，App Runner 默认会禁用跟踪。在配置可观察性时，您可以为服务启用 X-Ray 跟踪。有关更多信息，请参阅 管理可观察性。

如果您使用 App Runner API 或 AWS CLI，则ObservabilityConfiguration资源TraceConfiguration对象中的对象包含跟踪设置。要保持跟踪禁用状态，请不要指定TraceConfiguration对象。

在控制台和 API 案例中，请务必将上一节中讨论的实例角色与 App Runner 服务相关联。

查看 App Runner 服务的 X-Ray 跟踪数据

在 App Runner 控制台中服务控制面板页面的可观察性选项卡上，选择查看服务地图以导航到 Amazon CloudWatch 控制台。

使用 Amazon CloudWatch 控制台查看您的应用程序所处理的请求的服务地图和跟踪。服务地图显示请求延迟以及与其他应用程序和 AWS 服务的交互等信息。您向代码中添加的自定义注释允许您轻松搜索跟踪。有关更多信息，请参阅 Amazon CloudWatch 用户指南中的使用 ServiceLens 来监控应用程序的运行状况。