使用 X-Ray 追蹤 App Runner 應用程式 - AWS App Runner
檢測您的應用程式以進行追蹤將 X-Ray 許可新增至您的 App Runner 服務執行個體角色為您的 App Runner 服務啟用 X-Ray 追蹤檢視 App Runner 服務的 X-Ray 追蹤資料

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

使用 X-Ray 追蹤 App Runner 應用程式

AWS X-Ray 是一項 服務，可收集應用程式提供的請求相關資料，並提供可用來檢視、篩選和深入了解該資料的工具，以識別問題和最佳化的機會。對於應用程式的任何追蹤請求，您不僅可以查看請求和回應的詳細資訊，還可以查看應用程式對下游 AWS 資源、微服務、資料庫和 HTTP Web APIs發出的呼叫的詳細資訊。

X-Ray 使用來自支援雲端應用程式 AWS 的資源的追蹤資料來產生詳細的服務圖表。此服務圖表顯示用戶端、前端服務和後端服務，而前端服務會呼叫後端服務來處理請求和保留資料。使用服務圖形來識別瓶頸、延遲劇增的狀況和待解決的其他問題，以提升應用程式的效能。

如需 X-Ray 的詳細資訊，請參閱《AWS X-Ray 開發人員指南》。

App Runner 服務的 X-Ray 服務映射範例

檢測您的應用程式以進行追蹤

使用可攜式遙測規格 OpenTelemetry 檢測 App Runner 服務應用程式以進行追蹤。目前，App Runner 支援 AWS Distro for OpenTelemetry (ADOT)，這是使用 AWS 服務收集和呈現遙測資訊的 OpenTelemetry 實作。X-Ray 實作追蹤元件。

根據您在應用程式中使用的特定 ADOT 開發套件，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 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 收集器不接受指標記錄。它只接受指標追蹤。

執行時間設定範例

下列範例示範使用 ADOT Python 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'

將 X-Ray 許可新增至您的 App Runner 服務執行個體角色

若要搭配 App Runner 服務使用 X-Ray 追蹤，您必須為服務的執行個體提供與 X-Ray 服務互動的許可。您可以建立執行個體角色與服務的關聯，並新增具有 X-Ray 許可的受管政策來執行此操作。如需 App Runner 執行個體角色的詳細資訊，請參閱 執行個體角色。將 AWSXRayDaemonWriteAccess受管政策新增至執行個體角色，並在建立期間將其指派給您的服務。

為您的 App Runner 服務啟用 X-Ray 追蹤

當您建立服務時，App Runner 預設會停用追蹤。您可以在設定可觀測性時為服務啟用 X-Ray 追蹤。如需詳細資訊，請參閱管理可觀測性。

如果您使用 App Runner API 或 AWS CLI，則 ObservabilityConfiguration 資源物件中的 TraceConfiguration 物件會包含追蹤設定。 ObservabilityConfiguration 若要停用追蹤，請勿指定TraceConfiguration物件。

在主控台和 API 案例中，請務必將上一節討論的執行個體角色與 App Runner 服務建立關聯。

檢視 App Runner 服務的 X-Ray 追蹤資料

在 App Runner 主控台中服務儀表板頁面的可觀測性索引標籤上，選擇檢視服務映射以導覽至 Amazon CloudWatch 主控台。

App Runner 服務儀表板頁面顯示可觀測性索引標籤

使用 Amazon CloudWatch 主控台來檢視應用程式提供之請求的服務映射和追蹤。服務映射會顯示請求延遲以及與其他應用程式 AWS 和服務互動等資訊。您新增至程式碼的自訂註釋可讓您輕鬆搜尋追蹤。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的使用 ServiceLens 監控應用程式的運作狀態。