Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

啟用分散式追蹤記錄

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁面說明如何為 Apigee 執行階段設定分散式追蹤。如果您剛開始使用分散式追蹤系統，想瞭解更多資訊，請參閱「瞭解分散式追蹤記錄」。

如要進一步瞭解本頁面使用的術語，請參閱 Cloud Trace 總覽。

簡介

分散式追蹤系統可讓您追蹤軟體系統中的要求，這些要求會分散在多個應用程式、服務和資料庫，以及 Proxy 等中介程式。這些追蹤系統會產生報表，顯示要求在每個步驟所花費的時間。追蹤報表也能提供要求期間呼叫的各種服務的詳細檢視畫面，讓您深入瞭解軟體系統中每個步驟發生的情況。

Apigee Edge 的追蹤工具和 Apigee 的偵錯工具，有助於排解 API Proxy 問題及監控 API Proxy。不過，這些工具不會將任何資料傳送至分散式追蹤伺服器，例如 Cloud Trace、Jaeger 或 OpenTelemetry Collector。

如要在分散式追蹤記錄報表中查看 Apigee 執行階段資料，您必須在 Apigee 執行階段中明確啟用分散式追蹤記錄。啟用追蹤功能後，執行階段就能將追蹤資料傳送至分散式追蹤伺服器，並參與現有的追蹤作業。因此，您可以在單一位置查看 Apigee 生態系統內外的資料。

您可以在分散式追蹤報表中查看下列資訊：

整個流程的執行時間。
收到要求的時間。
要求傳送至目標的時間。
從目標收到回應的時間。
流程中每項政策的執行時間。
服務呼叫和目標流程的執行時間。
將回應傳送給用戶端的時間。

在分散式追蹤報表中，您可以將流程的執行詳細資料視為「範圍」。時距是指追蹤記錄中流程所用的時間。執行流程所需的時間會顯示為執行流程中各項政策所需時間的總和。您可以將下列每個流程視為個別範圍：

階段	端點	Flow
要求	Proxy	Preflow
	Proxy	PostFlow
	目標	Preflow
	目標	PostFlow
回應	Proxy	Preflow
	Proxy	PostFlow
	目標	Preflow
	目標	PostFlow

啟用分散式追蹤後，Apigee 執行階段預設會追蹤一組預先定義的變數。詳情請參閱「追蹤報表中的預設追蹤變數」。您可以使用 TraceCapture 政策擴充預設的執行階段行為，並追蹤其他流程、政策或自訂變數。詳情請參閱 TraceCapture 政策。

追蹤報表中的預設追蹤變數

啟用分散式追蹤記錄後，您可以在追蹤記錄報表中查看下列預先定義的變數。變數會顯示在下列範圍中：

RESP_SENT：系統會在收到目標伺服器的回應後新增這個範圍。這個範圍會攜帶 RESP_SENT 範圍中「變數」下方列出的目標端屬性。
PROXY_POST_RESP_SENT：這個範圍會在 Proxy 回應傳送至用戶端後新增。其中包含「Variables in the PROXY_POST_RESP_SENT span」(PROXY_POST_RESP_SENT 範圍中的變數) 下方列出的 Proxy 端屬性。
EVENT_FLOW_RESP 和 EVENT_FLOW_END：這些範圍是為處理串流伺服器傳送事件 (SSE) 回應的 API 代理項目新增。EVENT_FLOW_RESP 會標示 SSE 回應流程 (每個回應訊息執行一次)。EVENT_FLOW_END 會標示 SSE 串流的結尾。這些範圍目前不會攜帶預設屬性，而是以具名範圍的形式顯示在追蹤記錄中，讓您在追蹤報告中查看代理項目的 SSE 階段。

預設範圍屬性 (OpenTelemetry)

使用 OpenTelemetry 時，Apigee 執行階段發出的每個時距都會包含下列預設屬性，以及下列各節說明的時距專屬變數：

屬性	說明
`apigee.proxy.name`	識別與範圍相關聯的父項 API Proxy。
`cloud.provider`	託管 Apigee 執行階段的雲端服務供應商。一律為 `gcp`。
`cloud.resource.id`	與時距相關聯的機構和環境詳細資料。
`gcp.project_id`	與時距相關聯的 Google Cloud 專案 ID。

`RESP_SENT` 範圍內的變數

RESP_SENT 範圍會顯示下列變數：

變數	屬性	說明
`REQUEST_URL`	`request.url`	Proxy 收到的傳入用戶端要求完整網址。
`REQUEST_VERB`	`request.verb`	傳入用戶端要求的 HTTP 動詞 (例如 `GET` 或 `POST`)。
`RESPONSE_STATUS_CODE`	`response.status.code`	目標伺服器傳回的回應狀態碼。
`ROUTE_NAME`	`route.name`	選取這項要求目標的轉送規則名稱。
`ROUTE_TARGET`	`route.target`	路由規則選取的目標端點名稱。
`TARGET_BASE_PATH`	`target.basepath`	目標網址的基礎路徑部分。
`TARGET_HOST`	`target.host`	Proxy 連線的目標伺服器主機名稱。
`TARGET_IP`	`target.ip`	目標伺服器解析的 IP 位址。
`TARGET_NAME`	`target.name`	API Proxy 中定義的目標端點名稱。
`TARGET_PORT`	`target.port`	用來連線至目標伺服器的 TCP 通訊埠。
`TARGET_RECEIVED_END_TIMESTAMP`	`target.received.end.timestamp`	Proxy 結束接收目標伺服器回應的時間戳記 (Epoch 毫秒)。
`TARGET_RECEIVED_START_TIMESTAMP`	`target.received.start.timestamp`	Proxy 開始接收目標伺服器回應的時間戳記 (Epoch 毫秒)。
`TARGET_SENT_END_TIMESTAMP`	`target.sent.end.timestamp`	Proxy 結束將要求傳送至目標伺服器的時間戳記 (以毫秒為單位的紀元時間)。
`TARGET_SENT_START_TIMESTAMP`	`target.sent.start.timestamp`	Proxy 開始將要求傳送至目標伺服器的時間戳記 (Epoch 毫秒)。
`TARGET_SSL_ENABLED`	`target.ssl.enabled`	布林值，指出連線至目標伺服器時是否使用 TLS。
`TARGET_URL`	`target.url`	Proxy 連線的目標伺服器完整網址。

<0x0A>`PROXY_POST_RESP_SENT` 範圍中的變數

下列變數會顯示在 PROXY_POST_RESP_SENT 範圍中：

變數	屬性	說明
`API_PROXY_REVISION`	`apiproxy.revision`	處理要求的 API Proxy 修訂版本號碼。
`APIPROXY_NAME`	`apiproxy.name`	處理要求的 API Proxy 名稱。
`CLIENT_RECEIVED_END_TIMESTAMP`	`client.received.end.timestamp`	Proxy 結束接收用戶端要求時的時間戳記 (以 Epoch 毫秒為單位)。
`CLIENT_RECEIVED_START_TIMESTAMP`	`client.received.start.timestamp`	Proxy 開始接收用戶端要求時的時間戳記 (以 Epoch 紀元時間起算的毫秒數表示)。
`CLIENT_SENT_END_TIMESTAMP`	`client.sent.end.timestamp`	Proxy 結束將回應傳送給用戶端的時間戳記 (以毫秒為單位的紀元時間)。
`CLIENT_SENT_START_TIMESTAMP`	`client.sent.start.timestamp`	Proxy 開始將回應傳送給用戶端的時間戳記 (Epoch 毫秒)。
`ENVIRONMENT_NAME`	`environment.name`	執行 Proxy 的 Apigee 環境名稱。
`FAULT_SOURCE`	`message.header.X-Apigee-fault-source`	Proxy 執行期間發生錯誤時的故障來源。只會在錯誤流程中填入。
`IS_ERROR`	`is.error`	布林值，指出 Proxy 執行是否以錯誤流程結束。
`MESSAGE_ID`	`message.id`	Apigee 指派給要求的專屬 ID，可用於關聯記錄和追蹤範圍。
`MESSAGE_STATUS_CODE`	`message.status.code`	最終回應狀態碼，包括沒有目標的呼叫和錯誤流程。
`PROXY_BASE_PATH`	`proxy.basepath`	與傳入要求相符的 API Proxy 基準路徑。
`PROXY_CLIENT_IP`	`proxy.client.ip`	傳送要求給 Proxy 的用戶端 IP 位址。
`PROXY_NAME`	`proxy.name`	API Proxy 中處理要求的 Proxy 端點名稱。
`PROXY_PATH_SUFFIX`	`proxy.pathsuffix`	要求網址路徑中，Proxy 底層路徑後方的部分。
`PROXY_URL`	`proxy.url`	從用戶端收到的 Proxy 端點完整網址。

支援的分散式追蹤系統

您可以設定 Apigee 執行階段，將追蹤資料傳送至下列分散式追蹤系統：

分散式追蹤系統	說明
搭配 OpenTelemetry 使用 Cloud Trace	非常適合想透過 OpenTelemetry 進行簡單設定，且主要或唯一追蹤後端是 Cloud Trace 的使用者。如要使用 OpenTelemetry 將追蹤記錄資料傳送至 Cloud Trace，請按照下列步驟操作：設定 Apigee 執行階段的 Cloud Trace。使用 OpenTelemetry 為 Cloud Trace 啟用分散式追蹤。注意：將追蹤資料傳送至 Cloud Trace 的所有相關費用，皆由您負責支付。詳情請參閱「定價」和「配額」頁面。
OpenTelemetry Collector	管理自己的 OpenTelemetry Collector，控管追蹤資料的收集和處理作業。如果您需要將資料傳送至多個系統 (包括非 Google 系統)，或自訂資料的處理、分組或強化方式，這就是理想做法。如要將追蹤資料傳送至 OpenTelemetry Collector，請執行下列操作：部署及管理 OpenTelemetry Collector，詳情請參閱「OpenTelemetry Collector」。為 OpenTelemetry Collector 啟用分散式追蹤記錄。如要瞭解啟用這個選項前必須符合的網路可連線性、TLS、傳輸和費用規定，請參閱「使用 OpenTelemetry Collector 時的注意事項」。
搭配 OpenCensus 使用 Cloud Trace	如要使用 OpenCensus 將追蹤資料傳送至 Cloud Trace，請按照下列步驟操作：為 Cloud Trace (OpenCensus) 設定 Apigee 執行階段。使用 OpenCensus 為 Cloud Trace 啟用分散式追蹤。注意：將追蹤資料傳送至 Cloud Trace 的所有相關費用，皆由您負責支付。詳情請參閱「定價」和「配額」頁面。
搭配 OpenCensus 使用 Jaeger	如要使用 OpenCensus 將追蹤記錄資料傳送至 Jaeger，請為 Jaeger 啟用分散式追蹤。

環境變數

本頁的程序會使用下列環境變數。建議您先在環境中設定這些變數，再開始操作。

TOKEN="Authorization: Bearer $(gcloud auth application-default print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

其中：

TOKEN 會使用承載權杖定義 Authentication 標頭。呼叫 Apigee API 時，您會使用這個標頭。詳情請參閱 print-access-token 指令的參考頁面。
ENV_NAME 是貴機構中某個環境的名稱。
PROJECT_ID 是 Google Cloud 專案的 ID。

為 OpenTelemetry 或 OpenCensus 設定 Apigee 執行階段

Apigee 執行階段支援兩種追蹤標準：OpenTelemetry (建議用於新部署作業) 和 OpenCensus。選擇適合您環境的追蹤標準，然後按照下方分頁中的對應設定步驟操作。

對於 OpenTelemetry，Apigee 執行階段會辨識 W3C 標頭格式，包括 traceparent 和 tracestate 標頭。即使要求中存在 B3 標頭，系統也會忽略。

OpenTelemetry (建議)

為 Cloud Trace (OpenTelemetry) 設定 Apigee 執行階段

Apigee 執行階段和 Apigee Hybrid 執行階段都支援使用 Cloud Trace 進行分散式追蹤。如果您使用客戶管理的 OpenTelemetry Collector，可以略過本節，直接前往「為 OpenTelemetry Collector 啟用分散式追蹤」。

設定 Cloud Trace 適用的 ApigeeX 執行階段

如要為 Cloud Trace 設定 Apigee 執行階段，您的 Google Cloud 專案必須啟用下列 API：

Cloud Trace API (trace.googleapis.com)
Telemetry API (telemetry.googleapis.com)
Service Usage API (serviceusage.googleapis.com)

啟用這些 API 後， Google Cloud 專案就能透過 OpenTelemetry 接收來自已驗證來源的追蹤資料。

如要啟用 API，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「API 和服務」：
前往「APIs and Services」(API 和服務) 頁面
點選「啟用 API 和服務」。
啟用 Cloud Trace API、Telemetry API 和 Service Usage API。

除了啟用 API 之外，您還必須將下列角色授予服務代理程式帳戶：

roles/telemetry.tracesWriter
roles/serviceusage.serviceUsageConsumer

具體服務帳戶取決於 Apigee 環境：

Apigee (非混合式)：將角色授予 Apigee 服務代理程式。服務代理程式帳戶通常採用 service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com 格式。
Apigee Hybrid：如「設定 Cloud Trace 的 Apigee Hybrid 執行階段」一文所述，將角色授予執行階段服務帳戶。

請參閱「使用 Google Cloud 控制台授予 IAM 角色」。

設定 Cloud Trace 適用的 Apigee Hybrid 執行階段

如要為 Cloud Trace 設定 Apigee Hybrid 執行階段，請啟用「為 Cloud Trace 設定 Apigee 執行階段」一文所述的 API。

除了啟用 API，您還必須新增 iam.gserviceaccount.com 服務帳戶，才能搭配混合式執行階段使用 Cloud Trace。如要新增服務帳戶，以及必要的角色和金鑰，請完成下列步驟：

建立新的服務帳戶：

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

將 IAM 政策繫結新增至服務帳戶，授予必要角色：

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/telemetry.tracesWriter --project PROJECT_ID

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/serviceusage.serviceUsageConsumer --project PROJECT_ID

建立服務帳戶金鑰：
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
如未妥善管理服務帳戶金鑰，可能會產生安全性風險，您有責任保護私密金鑰的安全，並執行「管理服務帳戶金鑰的最佳做法」一文所述的其他作業。假如無法建立服務帳戶金鑰，可能是因為貴組織已停用這項功能。詳情請參閱這篇文章。
如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「外部來源憑證的安全規定」一節。

將服務帳戶新增至 overrides.yaml 檔案。

envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json

使用 Helm 將變更套用至執行階段：

helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

啟用分散式追蹤記錄 (OpenTelemetry)

啟用分散式追蹤前，請先建立必要的環境變數。

使用 OpenTelemetry 啟用 Cloud Trace 的分散式追蹤功能

下列範例說明如何使用 OpenTelemetry 為 Cloud Trace 啟用分散式追蹤：

執行下列 Apigee API 呼叫：
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP"
        }'
```
要求主體範例包含下列元素：
- 如要透過 OpenTelemetry 支援 Cloud Trace，請將 exporter 參數設為 OPEN_TELEMETRY_CLOUD_TRACE，並將 traceProtocol 參數設為 OTLP。
- samplingRate 設為 0.05，表示大約 5% 的 API 呼叫會傳送至分散式追蹤。如果是 OpenTelemetry，您可以指定最高 1.0 (100%) 的取樣率。詳情請參閱效能考量。
- endpoint 參數設為應接收追蹤資料的 Google Cloud 專案 ID (純專案 ID 字串，而非網址)。
  注意：endpoint 參數必須設為與設定步驟中設定的服務帳戶相關聯的專案。
  
  警告：endpoint 參數一經設定就無法更新。
成功的回應會與下列內容相似：
```
{
  "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP"
}
```

為 OpenTelemetry Collector 啟用分散式追蹤記錄

如要為客戶管理的 OpenTelemetry Collector 啟用分散式追蹤，請執行下列 Apigee API 呼叫：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP"
        }'

要求主體範例包含下列元素：

如要支援客戶管理的 OpenTelemetry Collector，請將 exporter 參數設為 OPEN_TELEMETRY_COLLECTOR，並將 traceProtocol 參數設為 OTLP。
endpoint 參數會設為 OpenTelemetry Collector 的 OTLP 擷取端點完整 HTTPS 網址 (例如 https://my-otel-collector.example.com:4318/v1/traces)。與採用裸露 Google Cloud 專案 ID 的 Cloud Trace 匯出工具不同，OPEN_TELEMETRY_COLLECTOR 匯出工具需要包含架構、主機、通訊埠和路徑的完整網址。
注意：endpoint 參數一經設定就無法更新。
samplingRate 設為 0.05，表示大約 5% 的 API 呼叫會傳送至分散式追蹤。詳情請參閱「效能考量」。

成功的回應會與下列內容相似：

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP"
}

使用 OpenTelemetry Collector 的注意事項

啟用分散式追蹤功能，將資料傳送至客戶管理的 OpenTelemetry Collector 前，請先詳閱下列規定。

網路可連線性

確認 Apigee 可以連上 OpenTelemetry Collector。
如要連線至未公開於網際網路的收集器，請使用 Private Service Connect (PSC)。
如果是 Apigee Hybrid，如果已設定轉送 Proxy，追蹤資料會透過該 Proxy 傳遞至 OpenTelemetry Collector 和後端。

傳輸通訊協定

OpenTelemetry Collector 僅支援 OTLP/HTTP 傳輸 (依 OTLP 慣例，通訊埠為 4318，路徑為 /v1/traces)。系統不支援 OTLP/gRPC (通訊埠 4317)。

TLS 和 mTLS

TLS 伺服器憑證驗證：當收集器端點使用 https:// 時，Apigee 執行階段會根據 JDK 預設信任儲存庫驗證伺服器憑證，該儲存庫包含一組標準的公開信任憑證授權單位。因此，收集器必須出示公開信任的 CA 核發的憑證。Apigee 不接受自行簽署的憑證和私人 CA 核發的憑證；在 Apigee Hybrid 中，您可以透過 JVM 設定，將私人 CA 新增至訊息處理器的信任儲存區。
不支援相互傳輸層安全標準 (mTLS)：Apigee 不會向收集器提供用戶端憑證。如果收集器需要用戶端憑證驗證，請在收集器前方放置不需要 mTLS 的 TLS 終止 Proxy。

端點網址限制

系統會在設定時，於伺服器端驗證收集器 endpoint 值。為防止伺服器端偽造要求 (SSRF) 探查內部 Google Cloud 基礎架構，系統會拒絕具有下列任一端點形狀的要求，並傳回 FailedPrecondition 錯誤：

http 或 https 以外的配置。
內嵌憑證的網址 (例如 https://user:password@host:4318/v1/traces)。端點網址不得提供憑證。
主機名稱 localhost、metadata 或 metadata.google.internal。
解析為回送 (127.0.0.0/8、 ::1)、連結本機 (169.254.0.0/16，包括 169.254.169.254 雲端中繼資料位址)、未指定 (0.0.0.0、::) 或網際網路工程任務組 (IETF) 私人網路範圍 (10.0.0.0/8、172.16.0.0/12、 192.168.0.0/16) 的 IP 常值。
解碼後會變成上述任何遭封鎖位址的 IPv4 數字編碼 (例如 http://2130706433/、http://0x7f000001/ 和 http://0177.0.0.1/ 解碼後都會變成 127.0.0.1，因此會遭到拒絕)。

費用

您必須支付與 OpenTelemetry Collector 相關的所有費用。

OpenCensus

設定 Cloud Trace (OpenCensus) 適用的 Apigee 執行階段

Apigee 執行階段和 Apigee Hybrid 執行階段都支援使用 Cloud Trace 和 OpenCensus 進行分散式追蹤。如果您使用 Jaeger，可以略過本節，直接前往「使用 OpenCensus 為 Jaeger 啟用分散式追蹤」。

設定 Apigee 執行階段的 Cloud Trace

如要為 Cloud Trace 設定 Apigee 執行階段，您的 Google Cloud 專案必須啟用 Cloud Trace API。

如要啟用 API，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「API 和服務」：
前往「APIs and Services」(API 和服務) 頁面
點選「啟用 API 和服務」。
啟用 Cloud Trace API。

設定 Cloud Trace 適用的 Apigee Hybrid 執行階段

如要為 Cloud Trace 設定 Apigee Hybrid 執行階段，請啟用 Cloud Trace API。

除了啟用 API，您還必須新增 iam.gserviceaccount.com 服務帳戶，才能搭配混合式執行階段使用 Cloud Trace。如要新增服務帳戶，以及必要的 roles/cloudtrace.agent 角色和金鑰，請按照下列步驟操作：

建立新的服務帳戶：

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

將 IAM 政策繫結新增至服務帳戶：

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

建立服務帳戶金鑰，並按照下列步驟更新 overrides.yaml。
建立服務帳戶金鑰：
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
如未妥善管理服務帳戶金鑰，可能會產生安全性風險，您有責任保護私密金鑰的安全，並執行「管理服務帳戶金鑰的最佳做法」一文所述的其他作業。假如無法建立服務帳戶金鑰，可能是因為貴組織已停用這項功能。詳情請參閱這篇文章。
如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「外部來源憑證的安全規定」一節。

將服務帳戶新增至 overrides.yaml 檔案。

envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json

使用 Helm 將變更套用至執行階段：

helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

啟用分散式追蹤記錄 (OpenCensus)

啟用分散式追蹤前，請先建立必要的環境變數。

使用 OpenCensus 為 Cloud Trace 啟用分散式追蹤

以下範例說明如何使用 OpenCensus 為 Cloud Trace 啟用分散式追蹤：

執行下列 Apigee API 呼叫：
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}
        }'
```
要求主體範例包含下列元素：
- 如要支援 Cloud Trace，請將 exporter 參數設為 CLOUD_TRACE。未指定的 traceProtocol 參數預設為 OpenCensus。
- endpoint 參數會設為要傳送追蹤記錄的 Google Cloud 專案。
- samplingRate 設為 0.1，表示大約 10% 的 API 呼叫會傳送至分散式追蹤。對於 OpenCensus，可設定的取樣率上限為 0.5。
  注意：endpoint 參數一經設定就無法更新。
成功的回應會與下列內容相似：
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

使用 OpenCensus 為 Jaeger 啟用分散式追蹤記錄

以下範例說明如何為 Jaeger 啟用分散式追蹤：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

在這個例子中：

如要支援 Jaeger，請將 exporter 參數設為 JAEGER。未指定的 traceProtocol 參數預設為 OpenCensus。
endpoint 參數設為 Jaeger 的安裝和設定位置。
注意：endpoint 參數一經設定即無法更新。
samplingRate 設為 0.4，表示大約 40% 的 API 呼叫會傳送至分散式追蹤。

為 Apigee 執行階段環境啟用分散式追蹤功能時，預期會對效能造成影響，例如增加記憶體用量、提高 CPU 需求，以及增加延遲。影響程度取決於 API Proxy 的複雜度 (例如政策數量) 和機率取樣率 (設定為 samplingRate)。取樣率越高，對效能的影響就越大。

詳情請參閱「效能注意事項」。

注意：設定傳播延遲。如果 PATCH .../traceConfig 傳回的 API 回應成功，表示控制層已接受設定。Apigee 執行階段會輪詢設定更新，因此變更通常會在 API 回應後約一到兩分鐘內生效。驗證設定變更時，請先等待這段傳播時間，再進一步調查。使用 API 傳回的 revisionId 和 updateTime 欄位 (請參閱「查看分散式追蹤設定」)，確認控制平面狀態。

查看分散式追蹤設定

如要查看執行階段中現有的分散式追蹤設定，請登入執行階段，然後執行下列指令：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

執行指令後，您會看到類似以下的回應：

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

revisionId 會在每次成功更新時遞增，而 updateTime 則會反映最近一次變更的伺服器時間戳記。使用這兩個欄位確認控制層已接受設定更新；這兩個欄位也會由 PATCH .../traceConfig 回應傳回。

更新分散式追蹤設定

下列指令說明如何更新 Cloud Trace 的現有分散式追蹤設定：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

執行指令後，您會看到類似以下的回應：

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}

在這個範例中，取樣率會更新為 0.6。

如要更新 Jaeger 的設定，請將要求中的 exporter 欄位設為 JAEGER。

停用分散式追蹤設定

以下範例說明如何停用為 Cloud Trace 設定的分散式追蹤：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "OFF"}
        }'

注意：無論 samplingRate 值為何，將 sampler 設為 OFF 都會停用追蹤功能。只有在 sampler 為 PROBABILITY 時，執行階段才會查詢 samplingRate。

執行指令後，您會看到類似以下的回應：

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

覆寫 API Proxy 的追蹤設定

在 Apigee 執行階段啟用分散式追蹤功能後，執行階段中的所有 API Proxy 都會使用相同的追蹤設定。不過，您可以覆寫 API Proxy 或 API Proxy 群組的分散式追蹤設定。這樣就能更精細地控管追蹤設定。

以下範例會覆寫 hello-world API Proxy 的分散式追蹤設定：

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

您可以覆寫設定，針對特定 API Proxy 排除問題，不必變更所有 API Proxy 的設定。

更新追蹤設定覆寫

如要更新 API Proxy 或 API Proxy 群組的追蹤設定覆寫，請按照下列步驟操作：

使用下列指令擷取追蹤設定的現有覆寫項目：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

這項指令應會傳回類似下列內容的回應，其中包含「name」欄位，用於識別由覆寫項目控管的一或多個 Proxy：

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

如要更新 Proxy，請使用「name」欄位的值，將 POST 要求傳送至該 Proxy 的覆寫設定，並附上更新的欄位值。例如：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

刪除追蹤設定覆寫

如要刪除 API Proxy 或 API Proxy 群組的追蹤設定覆寫，請按照下列步驟操作：

使用下列指令擷取追蹤設定的現有覆寫項目：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

這項指令應會傳回類似下列內容的回應，其中包含「name」欄位，用於識別由覆寫項目控管的一或多個 Proxy：

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

如要刪除 Proxy，請使用「name」欄位的值，將 DELETE 要求傳送至該 Proxy 的覆寫設定，並提供更新的欄位值。例如：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \

效能注意事項

為 Apigee 執行階段環境啟用分散式追蹤功能時，預期會對效能造成影響，導致記憶體用量增加、CPU 需求增加，以及延遲時間增加。影響程度取決於 API Proxy 的複雜度 (例如政策數量)、機率取樣率 (設為 samplingRate)，以及最重要的追蹤流量相對於每個訊息處理器 (MP) 跨度匯出容量的比例。

Apigee MP 的時距匯出速率有限。使用預設設定時，單一 MP 每秒可持續匯出約 820 個範圍。一般 API Proxy 執行作業會發出約 10 個範圍 (Proxy PreFlow、目標流程、PostFlow、附加政策)，因此單一 MP 在 100% 取樣率下，每秒可持續追蹤約 82 個要求。擴充 MP 副本數量會以線性方式增加總上限。

下表摘要列出兩種流量狀態下，samplingRate=1.0 (100% 可能性) 的預期影響：

流量制度 (每個 MP)	預計影響時間：`samplingRate=1.0`	建議做法
流量較低 (每個 MP 每秒追蹤的要求數約少於 82 個)	處理量會減少約 1% 至 2%；平均延遲時間會增加約 1%；p99 延遲時間會增加約 15% 至 20%。實際影響微乎其微。	可放心啟用 100% 的功能。
流量過大 (明顯高於每個 MP 大約每秒 82 個追蹤要求)	輸送量會減少約 14%；平均延遲時間會增加約 24%；p75 延遲時間會增加約 52%；錯誤率會增加約 1 個百分點。	請降低 `samplingRate` (例如降至 `0.1` 或 `0.05`)，或增加 MP 副本數量，讓每個 MP 每秒處理的追蹤要求減少。

對於流量高且延遲時間要求嚴格的環境，建議的機率取樣率小於或等於 10%。如要使用分散式追蹤功能進行疑難排解，請考慮透過每個 Proxy 的覆寫值，僅針對特定 API Proxy 提高機率取樣 (samplingRate)。

偵測捨棄的範圍

如果追蹤的流量超過 Apigee MP 跨度處理容量，或目的地無法接受流量，系統會在跨度抵達追蹤後端前捨棄跨度。如要偵測捨棄的範圍，請使用下列後端專屬信號：

Cloud Trace (OPEN_TELEMETRY_CLOUD_TRACE 或 CLOUD_TRACE)：檢查目的地專案的 Cloud Trace 配額和限制；如果配額持續發生錯誤，系統就會捨棄時距。在 Google Cloud 控制台中監控 Cloud Trace API 配額用量。
客戶管理的 OpenTelemetry 收集器：監控收集器的標準接收器指標 (例如 otelcol_receiver_refused_spans 和 otelcol_exporter_send_failed_spans)，偵測遭拒或無法轉送至下游後端的範圍。

排解分散式追蹤記錄問題

如要排解分散式追蹤問題，請按照下列步驟操作：

使用 traceConfig API 驗證分散式追蹤設定，確保符合您的需求。
確認服務帳戶在目標專案中具備正確的 IAM 權限 (角色)。
如果搭配 OpenTelemetry 使用 Cloud Trace，請檢查傳入的時距，以及是否有任何 API 啟用或配額錯誤。
如果使用客戶管理的 OpenTelemetry Collector，請執行下列步驟：
- 確認 Apigee 可以連上 Collector 端點。如果使用 Private Service Connect (PSC)，請檢查設定。
- 檢查 OpenTelemetry Collector 記錄，找出資料或連線問題。
- 確認收集器的 TLS 憑證有效。
檢查 Apigee 執行階段記錄，找出追蹤記錄匯出錯誤。

啟用分散式追蹤記錄 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

追蹤報表中的預設追蹤變數

預設範圍屬性 (OpenTelemetry)

RESP_SENT 範圍內的變數

<0x0A>PROXY_POST_RESP_SENT 範圍中的變數

支援的分散式追蹤系統

環境變數

為 OpenTelemetry 或 OpenCensus 設定 Apigee 執行階段

OpenTelemetry (建議)

為 Cloud Trace (OpenTelemetry) 設定 Apigee 執行階段

設定 Cloud Trace 適用的 ApigeeX 執行階段

設定 Cloud Trace 適用的 Apigee Hybrid 執行階段

啟用分散式追蹤記錄 (OpenTelemetry)

使用 OpenTelemetry 啟用 Cloud Trace 的分散式追蹤功能

為 OpenTelemetry Collector 啟用分散式追蹤記錄

使用 OpenTelemetry Collector 的注意事項

網路可連線性

傳輸通訊協定

TLS 和 mTLS

端點網址限制

費用

OpenCensus

設定 Cloud Trace (OpenCensus) 適用的 Apigee 執行階段

設定 Apigee 執行階段的 Cloud Trace

設定 Cloud Trace 適用的 Apigee Hybrid 執行階段

啟用分散式追蹤記錄 (OpenCensus)

使用 OpenCensus 為 Cloud Trace 啟用分散式追蹤

使用 OpenCensus 為 Jaeger 啟用分散式追蹤記錄

查看分散式追蹤設定

更新分散式追蹤設定

停用分散式追蹤設定

覆寫 API Proxy 的追蹤設定

更新追蹤設定覆寫

刪除追蹤設定覆寫

效能注意事項

偵測捨棄的範圍

排解分散式追蹤記錄問題

啟用分散式追蹤記錄

`RESP_SENT` 範圍內的變數

<0x0A>`PROXY_POST_RESP_SENT` 範圍中的變數