使用 X-Ray 追蹤您的應用程式執行程式 - AWS App Runner
檢測您的追蹤應用程式將 X-Ray 權限新增至您的應用程式執行個體角色為您的應用程式執行器服務啟用 X-Ray查看應用程序運行器服務的 X-Ray 跟踪數據

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

使用 X-Ray 追蹤您的應用程式執行程式

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

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

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

應用程式執行器服務的 X-Ray 服務對應範例

檢測您的追蹤應用程式

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

根據您在應用程式中使用的特定 ADOT SDK，ADOT 最多支援兩種檢測方法：自動和手動。如需有關 SDK 檢測的詳細資訊，請參閱 ADOT 文件，並在導覽窗格中選擇您的 SDK。

運行時設置

以下是檢測 App Runner 服務應用程式以進行追蹤的一般執行階段設定指示。

若要設定執行階段的追蹤

  1. 按照發行AWS 版 OpenTelemetry（ADOT）中為您的運行時提供的說明來檢測您的應用程序。

  2. 如果您使用的是源代碼存儲庫，請在apprunner.yaml文件的build部分中安裝所需的OTEL依賴關係，或者如果您使用的是容器映像，則在 Dockerfile 中安裝所需的依賴關係。

  3. 如果您使用的是源代碼存儲庫，請在apprunner.yaml文件中設置環境變量，或者如果您使用的是容器映像，則在 Dockerfile 中設置環境變量。

    範例 環境變數
    注意

    下列範例會列出要新增至apprunner.yaml檔案的重要環境變數。如果您使用的是容器映像，請將這些環境變量添加到 Dockerfile 中。但是，每個運行時都可以有自己的特質，您可能需要將更多的環境變量添加到以下列表中。有關運行時特定說明和如何為運行時設置應用程序的示例的更多信息，請參閱入門下的AWS Distro 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 Otel 收集器不接受指標記錄。它只接受指標跟踪。

運行時設置示例

下面的例子演示了使用 ADOT 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

當您的服務源是映像時，您可以直接檢測 Docker 文件，該文件控制構建容器映像並在映像中運行應用程序。下面的例子顯示了一個 Python 應用程序的檢測碼頭文件。儀器添加以粗體強調。

範例 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 配置文件設置間接檢測您的映像。這些設置控制應用程序運行器生成的 Docker 文件，並用於為您的應用程序構建映像。下列範例會顯示 Python 應用程式的已檢測應用程式執行器組態檔案。儀器添加以粗體強調。

範例 阿普魯人. 羊
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 服務使用 X-Ray 追蹤，您必須向服務執行個體提供與 X-Ray 服務互動的權限。您可以將執行個體角色與服務建立關聯，並新增具有 X-Ray 權限的受管政策。如需有關應用程式執行個體角色的詳細資訊，請參閱實例角色。將AWSXRayDaemonWriteAccess受管政策新增至執行個體角色，並在建立期間將其指派給您的服務。

為您的應用程式執行器服務啟用 X-Ray

當您建立服務時，應用程式執行器預設會停用追蹤。您可以為您的服務啟用 X-Ray 追蹤，做為規劃可觀測性的一部分。如需詳細資訊，請參閱 管理可觀測性。

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

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

查看應用程序運行器服務的 X-Ray 跟踪數據

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

顯示可觀察性選項卡應用程序運行器服務儀表板

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