啟用分散式追蹤記錄

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

查看 Apigee Edge 說明文件。

預先發布版

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本頁說明如何設定 Apigee 執行階段的分散式追蹤功能。如果您是分散式追蹤系統的新手，想瞭解更多資訊，請參閱「瞭解分散式追蹤」。

簡介

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

Apigee Edge 中的追蹤工具和 Apigee 中的偵錯工具，有助於排解 API Proxy 問題及監控 API Proxy。不過，這些工具不會將任何資料傳送至分散式追蹤伺服器，例如 Cloud Trace 或 Jaeger。如要在分散式追蹤記錄報表中查看 Apigee 執行階段資料，您必須在 Apigee 執行階段中明確啟用分散式追蹤記錄。啟用追蹤功能後，執行階段就能將追蹤資料傳送至分散式追蹤伺服器，並參與現有的追蹤作業。因此，您可以在單一位置查看 Apigee 生態系統內外的資料。

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

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

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

• 要求
  • Proxy
    • Preflow
    • PostFlow
  • 目標
    • Preflow
    • PostFlow
• 回覆
  • Proxy
    • Preflow
    • PostFlow
  • 目標
    • Preflow
    • PostFlow

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

傳送至 Apigee 的 API 呼叫可能包含追蹤標頭，因為該呼叫是現有追蹤記錄的一部分。在本例中，Apigee 會參與現有的追蹤作業，並將標頭傳播至外送 API 呼叫。Apigee 執行階段會解讀 Zipkin B3 標頭格式。因此，當參與現有追蹤記錄時，系統會辨識 x-b3-traceid、x-b3-spanid 和 x-b3-sampled 標頭。不過，如果傳入的 API 呼叫中沒有追蹤標頭，Apigee 會新增追蹤標頭，並將其傳播至傳出的 API 呼叫。其他服務可以存取標頭，並視需要參與追蹤。

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

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

• POST_RESP_SENT:從目標伺服器收到回應後，系統會新增這個範圍。
• POST_CLIENT_RESP_SENT:將 Proxy 回應傳送給用戶端後，系統會新增這個範圍。

POST_RESP_SENT 範圍中的變數

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

• REQUEST_URL (request.url)
• REQUEST_VERB (request.verb)
• RESPONSE_STATUS_CODE (response.status.code)
• ROUTE_NAME (route.name)
• ROUTE_TARGET (route.target)
• TARGET_BASE_PATH (target.basepath)
• TARGET_HOST (target.host)
• TARGET_IP (target.ip)
• TARGET_NAME (target.name)
• TARGET_PORT (target.port)
• TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
• TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
• TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
• TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
• TARGET_SSL_ENABLED (target.ssl.enabled)
• TARGET_URL (target.url)

POST_CLIENT_RESP_SENT 範圍中的變數

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

• API_PROXY_REVISION (apiproxy.revision)
• APIPROXY_NAME (apiproxy.name)
• CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
• CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
• CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
• CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
• ENVIRONMENT_NAME (environment.name)
• FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
• IS_ERROR (is.error)
• MESSAGE_ID (message.id)
• MESSAGE_STATUS_CODE (message.status.code)
• PROXY_BASE_PATH (proxy.basepath)
• PROXY_CLIENT_IP (proxy.client.ip)
• PROXY_NAME (proxy.name)
• PROXY_PATH_SUFFIX (proxy.pathsuffix)
• PROXY_URL (proxy.url)

支援的分散式追蹤系統

Apigee 執行階段支援下列分散式追蹤系統：

• Cloud Trace
• Jaeger

您可以設定 Apigee 執行階段，將追蹤資料傳送至 Cloud Trace 或 Jaeger 系統。

由於追蹤 Apigee 執行階段中的所有 API 呼叫會影響效能，因此 Apigee 允許您設定機率取樣率。您可以透過取樣率，指定要傳送多少 API 呼叫以進行分散式追蹤。舉例來說，如果您將取樣率指定為 0.4，表示有 40% 的 API 呼叫會傳送以供追蹤。詳情請參閱「效能注意事項」。

可設定的取樣率上限為 0.5。

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

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

設定 Apigee 執行階段的 Cloud Trace

如要搭配 Apigee 執行階段使用 Cloud Trace，Google Cloud 專案必須啟用 Cloud Trace API。這項設定可讓 Google Cloud 專案接收來自已驗證來源的追蹤記錄資料。

如要確認 Cloud Trace API 是否已啟用，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「API 和服務」：

   前往「APIs and Services」(API 和服務) 頁面

2. 點選「啟用 API 和服務」。
3. 在搜尋列中輸入「Trace API」。
4. 如果畫面顯示「API enabled」(API 已啟用)，代表 API 已啟用，您不必採取任何行動。否則，請按一下「Enable」(啟用)。

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

如要搭配 Apigee Hybrid 執行階段使用 Cloud Trace，必須啟用 Cloud Trace API。如要確認 Cloud Trace API 是否已啟用，請按照「為 Cloud Trace 設定 Apigee 執行階段」一文中的步驟操作。

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

1. 建立新的服務帳戶：

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

2. 將 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

3. 建立服務帳戶金鑰：

   gcloud iam service-accounts keys \
       create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com

   如未妥善管理服務帳戶金鑰，可能會產生安全性風險，您必須負責維護私密金鑰的安全性，以及執行 管理服務帳戶金鑰的最佳做法一文所述的其他作業。如果無法建立服務帳戶金鑰，可能是因為貴機構已停用這項功能。詳情請參閱「 管理預設安全機構資源」。

   如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「 外部來源憑證的安全規定」。

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

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

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

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

在 Apigee Hybrid 環境中，您可以搭配使用 Anthos 服務網格和 Cloud Trace。如要進一步瞭解如何在服務網格中啟用 Cloud Trace，請參閱「存取 Cloud Trace 中的追蹤記錄」。

啟用分散式追蹤記錄

為 Cloud Trace 或 Jaeger 啟用分散式追蹤功能前，請先建立下列環境變數：

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

其中：

• TOKEN 定義含持有人權杖的驗證標頭。呼叫 Apigee API 時，您可以使用這個標頭。詳情請參閱 print-access-token 指令的參考頁面。
• ENV_NAME 是貴機構中某個環境的名稱。
• PROJECT_ID 是 Google Cloud 專案的 ID。

為 Cloud Trace 啟用分散式追蹤記錄

以下範例說明如何啟用 Cloud Trace 的分散式追蹤功能：

1. 執行這項 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}}'

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

   • samplingRate 設為 0.1。也就是說，大約 10% 的 API 呼叫會傳送至分散式追蹤。如要進一步瞭解如何為執行階段環境設定 samplingRate，請參閱「效能注意事項」。
   • exporter 參數設為 CLOUD_TRACE。
   • 端點會設為要傳送追蹤記錄的 Google Cloud 專案。注意：這必須與設定步驟中的服務帳戶相符。

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

   {
     "exporter": "CLOUD_TRACE",
     "endpoint": "staging",
     "samplingConfig": {
       "sampler": "PROBABILITY",
       "samplingRate": 0.1
     }
   }

為 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"
    }'

在這個例子中：

• samplingRate 設為 0.4。這表示大約 40% 的 API 呼叫會傳送至分散式追蹤。
• exporter 參數設為 JAEGER。
• 端點會設為 Jaeger 的安裝和設定位置。

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

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

查看分散式追蹤設定

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

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

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

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

更新分散式追蹤記錄設定

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

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

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

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

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

如要更新 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 '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

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

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

覆寫 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 群組的追蹤設定覆寫，請按照下列步驟操作：

1. 使用下列指令擷取追蹤設定的任何現有覆寫：

   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
         }
       }
     ]
   }

2. 如要更新 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 群組的追蹤設定覆寫，請按照下列步驟操作：

1. 使用下列指令擷取追蹤設定的任何現有覆寫：

   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
         }
       }
     ]
   }

2. 如要刪除 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 代理程式的複雜度 (例如政策數量) 和機率取樣率 (設為 samplingRate)。取樣率越高，對效能的影響就越大。雖然效能受多項因素影響，但使用分散式追蹤時，效能預計會下降 10% 至 20%。

對於流量高且延遲時間要求嚴格的環境，建議的機率取樣率為 10% 以下。如要使用分散式追蹤功能進行疑難排解，請考慮只針對特定 API Proxy 提高機率取樣 (samplingRate)。