啟用分散式追蹤記錄

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明為 Apigee 執行階段設定分散追蹤所需的步驟。如果您是分散式追蹤系統的新手，並想進一步瞭解相關資訊，請參閱「瞭解分散式追蹤」。

簡介

分散式記錄追蹤系統可讓您追蹤分散在多個應用程式、服務和資料庫中的軟體系統要求，以及代理程式等中介服務。這些追蹤系統會產生報表，顯示要求在每個步驟所需的時間。追蹤報表還可提供詳細的視圖，讓您瞭解在要求期間呼叫的各種服務，進一步瞭解軟體系統中各個步驟發生的情況。

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

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

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

在分散式追蹤報表中，您可以查看流程的執行詳細資料，以跨度的形式呈現。範圍是指追蹤記錄中流程所需的時間。執行流程所需的時間會以匯總方式顯示，匯總項目為執行流程中每項政策所需的時間。您可以將下列各個流程視為個別區間：

  • 請求
    • Proxy
      • 預先流程
      • PostFlow
    • 指定目標
      • 預先流程
      • PostFlow
  • 回應
    • Proxy
      • 預先流程
      • PostFlow
    • 指定目標
      • 預先流程
      • PostFlow

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

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

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

  • POST_RESP_SENT:在從目標伺服器收到回應後，系統會新增這個區段。
  • POST_CLIENT_RESP_SENT:將 Proxy 回應傳送至用戶端後，系統會新增這個區間。

POST_RESP_SENT 區段中的變數

下列變數會顯示在 POST_RESP_SENT span 中：
  • 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 span 中會顯示下列變數：
  • 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 呼叫以進行追蹤。詳情請參閱「效能考量事項」。

為 Cloud Trace 設定 Apigee 執行階段

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

為 Cloud Trace 設定 Apigee 執行階段

如要在 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 disabled」，則表示這個 API 尚未啟用，請按一下「Enable」。

為 Cloud Trace 設定 Apigee Hybrid 執行階段

您必須啟用 Cloud Trace API，才能搭配 Apigee 混合式執行階段使用 Cloud Trace。如要確認已啟用 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 檔案。
    5. 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

啟用分散式追蹤記錄

為 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。

停用分散式追蹤記錄設定

以下範例說明如何停用為 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」欄位的值，為該 Proxy 傳送 DELETE 要求，並附上更新的欄位值。例如： 
    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)。