AWS App Runner 不再開放給新客戶。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[AWS App Runner 可用性變更](https://docs.aws.amazon.com/apprunner/latest/dg/apprunner-availability-change.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 X-Ray 追蹤 App Runner 應用程式
AWS X-Ray 是一項 服務，可收集應用程式提供的請求相關資料，並提供可用來檢視、篩選和深入了解該資料的工具，以識別問題和最佳化的機會。對於應用程式的任何追蹤請求，您不僅可以查看請求和回應的詳細資訊，還可以查看應用程式對下游 AWS 資源、微服務、資料庫和 HTTP Web APIs發出的呼叫的詳細資訊。
X-Ray 使用來自支援雲端應用程式 AWS 的資源的追蹤資料來產生詳細的服務圖表。此服務圖表顯示用戶端、前端服務和後端服務，而前端服務會呼叫後端服務來處理請求和保留資料。使用服務圖形來識別瓶頸、延遲劇增的狀況和待解決的其他問題，以提升應用程式的效能。
如需 X-Ray 的詳細資訊，請參閱[《AWS X-Ray 開發人員指南》](https://docs.aws.amazon.com/xray/latest/devguide/)。
## 檢測您的應用程式以進行追蹤
使用可攜式遙測規格 [OpenTelemetry](https://github.com/open-telemetry) 檢測 App Runner 服務應用程式以進行追蹤。目前，App Runner 支援 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) (ADOT)，這是使用 AWS 服務收集和呈現遙測資訊的 OpenTelemetry 實作。X-Ray 實作追蹤元件。
根據您在應用程式中使用的特定 ADOT 開發套件，ADOT 最多支援兩種檢測方法：*自動*和*手動*。如需使用 SDK 進行檢測的詳細資訊，請參閱 [ADOT 文件](https://aws-otel.github.io/docs/introduction)，然後在導覽窗格中選擇您的 SDK。
### 執行期設定
以下是檢測 App Runner 服務應用程式以進行追蹤的一般執行期設定指示。
**設定執行時間的追蹤**
1. 遵循 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) (ADOT) 中針對執行時間提供的指示來檢測您的應用程式。
1. 如果您使用的是原始碼儲存庫，請在 `apprunner.yaml` 檔案的 `build`區段中安裝必要的`OTEL`相依性；如果您使用的是容器映像，請在 Dockerfile 中安裝必要的相依性。
1. 如果您使用原始碼儲存庫，請在 `apprunner.yaml` 檔案中設定您的環境變數；如果您使用容器映像，請在 Dockerfile 中設定您的環境變數。
**Example 環境變數**
**注意**
下列範例列出要新增至 `apprunner.yaml` 檔案的重要環境變數。如果您使用容器映像，請將這些環境變數新增至 Dockerfile。不過，每個執行時間都可以有自己的特性，您可能需要將更多環境變數新增至下列清單。如需執行時間特定指示的詳細資訊，以及如何為執行時間設定應用程式的範例，請參閱*入門*下的 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) 並前往執行時間。
```
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](https://aws-otel.github.io/docs/getting-started/python-sdk) 自動檢測您的應用程式。軟體開發套件會自動產生遙測資料，說明應用程式中 Python 架構使用的值，而不會新增單行 Python 程式碼。您只需要在兩個來源檔案中新增或修改幾行。
首先，新增一些相依性，如下列範例所示。
**Example requirements.txt**
```
opentelemetry-distro[otlp]>=0.24b0
opentelemetry-sdk-extension-aws~=2.0
opentelemetry-propagator-aws-xray~=1.0
```
然後，檢測您的應用程式。執行此作業的方式取決於您的服務來源 - 來源映像或來源碼。
------
#### [ Source image ]
當您的服務來源是映像時，您可以直接檢測控制建置容器映像並在映像中執行應用程式的 Dockerfile。下列範例顯示 Python 應用程式的檢測 Dockerfile。檢測新增項目以粗體強調。
**Example 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 組態檔案。檢測新增項目以粗體強調。
**Example 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 執行個體角色的詳細資訊，請參閱 [執行個體角色](security_iam_service-with-iam.md#security_iam_service-with-iam-roles-service.instance)。將 `AWSXRayDaemonWriteAccess`受管政策新增至執行個體角色，並在建立期間將其指派給您的服務。
## 為您的 App Runner 服務啟用 X-Ray 追蹤
當您[建立服務](manage-create.md)時，App Runner 預設會停用追蹤。您可以在設定可觀測性時為服務啟用 X-Ray 追蹤。如需詳細資訊，請參閱[管理可觀測性](manage-configure-observability.md#manage-configure-observability.manage)。
如果您使用 App Runner API 或 AWS CLI，則 ObservabilityConfiguration 資源物件中的 [TraceConfiguration](https://docs.aws.amazon.com/apprunner/latest/api/API_TraceConfiguration.html) 物件會包含追蹤設定。 [ObservabilityConfiguration](https://docs.aws.amazon.com/apprunner/latest/api/API_ObservabilityConfiguration.html) 若要停用追蹤，請勿指定`TraceConfiguration`物件。
在主控台和 API 案例中，請務必將上一節討論的執行個體角色與 App Runner 服務建立關聯。
## 檢視 App Runner 服務的 X-Ray 追蹤資料
在 App Runner 主控台中[服務儀表板頁面](console.md#console.dashboard)的**可觀測性**索引標籤上，選擇**檢視服務映射**以導覽至 Amazon CloudWatch 主控台。
使用 Amazon CloudWatch 主控台來檢視應用程式提供之請求的服務映射和追蹤。服務映射會顯示請求延遲以及與其他應用程式 AWS 和服務互動等資訊。您新增至程式碼的自訂註釋可讓您輕鬆搜尋追蹤。如需詳細資訊，請參閱《*Amazon CloudWatch 使用者指南*》中的[使用 ServiceLens 監控應用程式的運作](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ServiceLens.html)狀態。