追蹤您的 API

部署可擴充服務 Proxy (ESP) 或可擴充服務 Proxy V2 (ESPv2) 和 API 的後端程式碼後，Proxy 會先攔截所有要求並執行必要的檢查，然後再將要求轉送至 API 後端。當後端回應時，Proxy 會收集並回報遙測資料。代理程式擷取的一部分遙測資料，是使用 Cloud Trace 擷取的追蹤記錄。

本頁面說明如何：

  • 在 Google Cloud 控制台中查看追蹤記錄。
  • 預估您的 Trace 費用。
  • 設定 Proxy 以停用追蹤記錄取樣功能。

查看追蹤記錄

追蹤記錄會追蹤傳入 API 的要求以及各種事件 (例如遠端程序呼叫或檢測的程式碼區段)，以及精確的檢測時間。這些事件在追蹤記錄中以「時距」表示。

如要查看專案的追蹤記錄，請前往 Google Cloud console中的 Cloud Trace 頁面：

前往「Trace」

您可以在「Trace explorer」頁面中細查個別追蹤記錄，並查看 ESP 在追蹤記錄中建立的時距。您可以使用篩選器查看單一 API 或作業的追蹤記錄。

為 API 建立的追蹤記錄和時距，會因 API 使用 ESPv2 或 ESP 而有所不同。以下摘要說明每個實作項目的追蹤記錄格式。

如要進一步瞭解「Trace Explorer」頁面，請參閱「尋找及探索追蹤記錄」一文。

ESPv2 建立的時距

ESPv2 會以以下格式建立追蹤記錄：

包含 ESPv2 跨度的追蹤記錄範例

ESPv2 至少會為每個追蹤記錄建立 2 個時距：

  • 整個要求和回應的 ingress OPERATION_NAME 時距。
  • router BACKEND egress 時距：ESPv2 等待後端處理要求並回應的時間。這包括 ESPv2 和後端之間的網路跳躍。

視您的 API 設定而定，ESPv2 可能會建立其他時距：

  • 如果您的 API 需要驗證，ESPv2 會快取需要驗證的公開金鑰，並保留 5 分鐘。如果公開金鑰不在快取中，ESPv2 會擷取並快取公開金鑰，並建立 JWT Remote PubKey Fetch 時距。
  • 如果您的 API 需要 API 金鑰，ESPv2 會快取驗證 API 金鑰所需的資訊。如果該資訊不在快取中，ESPv2 會呼叫 Service Control 並建立 Service Control remote call: Check 時距。

一般來說，ESPv2 只會為封鎖傳入要求的網路呼叫建立跨度。系統不會追蹤非阻斷式要求。任何本機處理作業都會建立時間事件，而非跨度。例如：

  • 配額執行需要遠端呼叫，但這些呼叫不會發生在 API 要求的路徑中，且在追蹤記錄中不會與任何區間相關聯。
  • ESPv2 會將 API 金鑰快取一段時間，任何使用快取的請求都會在追蹤記錄中顯示相關聯的時間事件。

ESP 建立的時距

ESP 會以以下格式建立追蹤記錄：

包含 ESP 跨度的追蹤記錄範例

ESP 會為每筆追蹤記錄建立至少 4 個時距：

  • 整個要求和回應的時距。
  • 呼叫 Service Control 的 services.check 方法以取得 API 設定的 CheckServiceControl 時距。
  • 檢查 API 上是否設定了配額的 QuotaControl 時距。
  • 追蹤在您的 API 後端程式碼中耗費時間的 Backend 時距。

視您的 API 設定而定，ESP 還會建立其他時距：

  • 如果您的 API 需要驗證，ESP 會在每筆追蹤記錄中建立 CheckAuth 時距。為了驗證要求，ESP 會快取對驗證所需的公開金鑰，並保留 5 分鐘。如果公開金鑰不在快取中，ESP 會擷取並快取公開金鑰，並建立 HttpFetch 時距。
  • 如果您的 API 需要 API 金鑰，ESP 會在每筆追蹤記錄中建立 CheckServiceControlCache 時距。ESP 會快取驗證 API 金鑰所需的資訊。如果該資訊不在快取中，ESP 會呼叫 Service Control 並建立 Call ServiceControl server 時距。
  • 如果您已為您的 API 設定配額，ESP 會在每筆追蹤記錄中建立 QuotaServiceControlCache 時距。ESP 會快取檢查配額所需的資訊。如果該資訊不在快取中，ESP 會呼叫 Service Control 並建立 Call ServiceControl server 時距。

追蹤記錄取樣率

ESP 會對 API 要求進行小量取樣以取得追蹤記錄資料。為了控制取樣率，ESP 會維護要求計數器和計時器。取樣率取決於 API 的每秒要求數。如果一秒內沒有任何要求，ESP 就不會傳送追蹤記錄。

如果一秒內的要求數為：

  • 小於等於 999，ESP 會傳送 1 筆追蹤記錄。
  • 在 1000 到 1999 之間，ESP 會傳送 2 筆追蹤記錄。
  • 在 2000 到 2999 之間，ESP 會傳送 3 筆追蹤記錄。
  • 而其他人員也會有資料管理的需求。

總之，您可以使用 ceiling 函式來預估取樣率：ceiling(requests per second/1000)

預估追蹤 Trace 的費用

如要預估 Trace 的費用，您必須估算 ESP 在一個月內傳送到 Trace 的時距數。

如要預估每月的時距數：

  1. 預估 API 的每秒要求數。如要取得這項預估值，您可以使用「Endpoints」 >「Services」頁面或 Cloud Logging 上的「Requests」圖表。詳情請參閱「監控您的 API」。
  2. 計算 ESP 每秒傳送到 Trace 的追蹤記錄數：ceiling(requests per second/1000)
  3. 預估追蹤記錄中的時距數。如要取得這項預估值，您可以使用 ESP 建立的時距一文中的資訊，或檢視「Trace List」(追蹤記錄清單) 頁面，以查看您的 API 追蹤記錄。
  4. 預估一個月內 API 獲得流量所需的秒數。例如，有些 API 只會在每天的某些時段收到要求，有些 API 偶爾才會收到要求。
  5. 將該月的秒數乘以時距數。

例如：

  1. 假設 API 的每秒要求數上限是 5 個。
  2. 追蹤記錄取樣率為 ceiling (5/1000) = 1
  3. API 未設定配額、不需要 API 金鑰，也不需要驗證。因此，ESP 為每筆追蹤記錄建立的時距數為 4 個。
  4. 這個 API 只會在週一到週五的營業時間內收到要求。API 在一個月內獲得流量的秒數約為：3600 X 8 X 20 = 576,000
  5. 每月的時距數約為：576,000 x 4 = 2,304,000

知道一個月內的約略時距數後，請參閱「追蹤記錄計價」頁面，查看詳細的定價資訊。

停用追蹤記錄取樣功能

如果您想讓 ESP 停止對要求進行取樣以及傳送追蹤記錄，您可以設定 ESP 啟動選項，然後重新啟動 ESP。ESP 傳送至 Cloud Trace 的追蹤記錄與「Endpoints」 >「Services」頁面上顯示的圖形無關。停用追蹤記錄取樣後，該圖形仍會繼續顯示。

下節假設您已部署 API 和 ESP，或者您已熟悉部署程序。詳情請參閱部署 API 後端。

App Engine

如要在 App Engine 彈性環境中停用 ESP 追蹤記錄取樣功能：

  1. 編輯 app.yaml 檔案。在 endpoints_api_service 區段中新增 trace_sampling 選項，並將其值設為 false。例如：
    endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed
  trace_sampling: false

    如果您的應用程式以微服務為基礎，則必須在每個 app.yaml 檔案中加入 trace_sampling: false。

  2. 如果您最近未更新 Google Cloud CLI，請執行下列指令：
    gcloud components update
  3. 儲存 app.yaml 檔案 (或多個檔案)。
  4. 將後端程式碼和 ESP 部署到 App Engine：
    gcloud app deploy

如何重新啟用追蹤記錄取樣功能：

  1. 從 app.yaml 中移除 trace_sampling 選項。
  2. 將後端程式碼和 ESP 部署到 App Engine：
    gcloud app deploy

Compute Engine

如要在搭配 Docker 的 Compute Engine 中停用 ESP 追蹤記錄取樣功能：

  1. 連線至您的 VM 執行個體：
    gcloud compute ssh [INSTANCE_NAME]
  2. 在 docker run 指令的 ESP 標記中，新增 --disable_cloud_trace_auto_sampling 選項：
    sudo docker run \
    --name=esp \
    --detach \
    --publish=80:8080 \
    --net=esp_net \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=[SERVICE_NAME] \
    --rollout_strategy=managed \
    --backend=[YOUR_API_CONTAINER_NAME]:8080 \
    --disable_cloud_trace_auto_sampling
  3. 發出 docker run 指令以重新啟動 ESP。

如何重新啟用追蹤記錄取樣功能：

  1. 移除 --disable_cloud_trace_auto_sampling。
  2. 發出 docker run 指令以重新啟動 ESP。

GKE

如要在 GKE 中停用 ESP 追蹤記錄取樣功能：

  1. 開啟您的部署資訊清單檔案 (稱為 deployment.yaml)，並在 containers 區段中新增下列內容：
    containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=[SERVICE_NAME]",
    "--rollout_strategy=managed",
    "--disable_cloud_trace_auto_sampling"
  ]
  2. 使用 kubectl create 指令啟動 Kubernetes 服務：
    kubectl create -f deployment.yaml

如何重新啟用追蹤記錄取樣功能：

  1. 移除 --disable_cloud_trace_auto_sampling 選項。
  2. 啟動 Kubernetes 服務：
    kubectl create -f deployment.yaml

如果您是在沒有 Docker 容器的 Compute Engine VM 執行個體上執行 ESP，則 --disable_cloud_trace_auto_sampling 選項沒有對等的 VM 執行個體中繼資料鍵/值組合。如果您要停用追蹤記錄取樣功能，則必須在容器中執行 ESP。

如「強制追蹤要求」一文所述，用戶端可以在要求中新增 X-Cloud-Trace-Context 標頭來強制追蹤要求。如果要求包含 X-Cloud-Trace-Context 標頭，即使您已停用追蹤記錄取樣功能，ESP 仍會將追蹤記錄資料傳送到 Trace。

追蹤內容傳播

針對分散式追蹤，要求標頭可包含指定追蹤 ID 的追蹤記錄內容。當 ESPv2 建立新的追蹤記錄範圍並傳送至 Cloud Trace 時，就會使用追蹤 ID。追蹤 ID 可用於搜尋單一要求的所有追蹤記錄和跨接。如果要求中未指定追蹤記錄內容，且已啟用追蹤記錄，系統會為所有追蹤記錄區間產生隨機的追蹤記錄 ID。

在以下範例中，Cloud Trace 會將 ESPv2 (1) 建立的時距與後端 (2) 建立的時距，與單一要求相關聯。這有助於偵錯整個系統的延遲問題：

ESPv2 的追蹤內容傳播範例

詳情請參閱「OpenTelemetry 核心概念：內容傳播」

支援的標頭

ESPv2 支援下列追蹤內容傳播標頭：

  • traceparent：標準 W3C 追蹤內容傳播標頭。大多數現代化追蹤架構都支援此功能。
  • x-cloud-trace-context：GCP 的追蹤記錄內容傳播標頭。舊版追蹤架構和 Google 程式庫支援此追蹤方法，但僅適用於特定供應商。
  • grpc-trace-bin：gRPC 後端搭配 OpenCensus 追蹤記錄程式庫使用的追蹤記錄內容傳播標頭。

如果您要建構新的應用程式，建議您使用 traceparent 追蹤內容傳播功能。根據預設，ESPv2 會擷取並散發這個標頭。如要進一步瞭解如何變更預設行為，請參閱「ESPv2 追蹤啟動選項」。