使用診斷收集器

診斷收集器是一種工具，可視需要擷取 Apigee Hybrid 執行個體 Kubernetes 元件的診斷資料，並將資料儲存在 Google Cloud Storage 值區。您可以使用 apigeectl diagnostic 指令叫用診斷收集器。

系統會擷取哪些系統資料？

診斷資訊收集器會擷取下列類型的資料：

  • 變更記錄層級。
  • Jstack。
  • POD 設定 YAML。
  • PS -ef 輸出內容。
  • TCP 傾印。
  • TOP 輸出內容。

資料會受到什麼影響？

診斷資訊收集器擷取資料後，會上傳至 Google Cloud 專案中的儲存空間 bucket。您可以在 Google Cloud Platform：Cloud Storage 瀏覽器中查看儲存的資料。

建立支援單時，您可以選擇是否要與 Google Apigee 支援團隊分享這項資料。

執行診斷收集器的必要條件

使用診斷資訊收集器前，請先完成下列必要條件：

Google Cloud Storage bucket

在 Google Cloud 專案中建立 Google Cloud Storage bucket，並給予不重複的名稱。您可以使用 gcloud storage 指令或 Google Cloud Platform：Cloud Storage 瀏覽器，建立及管理值區。

例如：

gcloud storage buckets create gs://apigee_diagnostic_data
 
Creating gs://apigee_diagnostic_data/...

如需操作說明，請參閱「建立儲存空間值區」。

服務帳戶

在專案中建立具有儲存空間管理員角色 (roles/storage.admin) 的服務帳戶，並下載服務帳戶 .json 金鑰檔案。

服務帳戶可使用任何不重複的名稱。本指南使用「apigee-diagnostic」做為服務帳戶名稱。

例如：

gcloud config set project ${PROJECT_ID}
 
gcloud iam service-accounts create apigee-diagnostic
 
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/storage.admin"
 
gcloud iam service-accounts keys create ${PROJECT_ID}-apigee-diagnostic.json \
    --iam-account=apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com

請參閱：

使用診斷收集器

使用診斷收集器的順序如下：

  1. 在 overrides.yaml 檔案中設定 Diagnostic 節，選取資訊類型、Apigee 容器，以及要從中取得診斷資料的個別 Pod。請參閱「為診斷收集器設定 overrides.yaml」。
  2. 使用下列 apigeectl 指令執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE

    其中 OVERRIDES_FILE 是 overrides.yaml 檔案的路徑。

  3. 檢查記錄：
    1. 取得 apigee-diagnostic 命名空間中的 Pod。 
      kubectl get pods -n apigee-diagnostic
    2. 記下名稱包含 diagnostic-collector 的 Pod
    3. 使用下列指令檢查記錄： 
      kubectl -n apigee-diagnostic logs -f POD_NAME

      其中 POD_NAME 是診斷收集器 Pod 的名稱。

      您也可以在 Google Cloud Platform 的 Cloud Storage 瀏覽器中查看收集到的記錄。

  4. 收集完資料後，請刪除診斷收集器。您必須先刪除，才能再次執行。
    apigeectl diagnostic delete -f OVERRIDES_FILE

設定診斷收集器的 overrides.yaml

您必須先在 overrides.yaml 檔案中設定診斷收集器，才能執行該工具。

如需 diagnostic 設定屬性的完整參考資料，請參閱設定屬性參考資料：diagnostic。

必要屬性

診斷收集器必須具備下列屬性才能執行。

  • diagnostic.serviceAccountPath：服務帳戶金鑰檔案的路徑，該服務帳戶在必要條件中具有 Storage Admin 角色。
  • diagnostic.operation：指定要收集所有統計資料，還是只收集記錄。

    值為："ALL" 或 "LOGGING"

    如果將 diagnostic.operation 設為 "LOGGING"，則必須使用以下屬性：

  • diagnostic.bucket：Google Cloud Storage 值區的名稱，診斷資料會存放在這個值區。這是您在必要條件中建立的值區。
  • diagnostic.container：指定要從哪個類型的 Pod 擷取資料。可能的值如下：
    container 值Apigee 元件Kubernetes 命名空間這個容器中的 Pod 名稱範例
    apigee-cassandra Cassandra apigee apigee-cassandra-default-0
    istio-proxy Istio Ingress istio-system istio-ingressgateway-696879cdf8-9zzzf
    apigee-mart-server MART apigee apigee-mart-hybrid-example-d89fed1-151-jj2ux-l7nlb
    apigee-runtime 訊息處理器 apigee apigee-runtime-hybrid-example-3b2ebf3-151-s64bh-g9qmv
    apigee-synchronizer 同步處理工具 apigee apigee-synchronizer-hybrid-example-3b2ebf3-151-xx4z6cg78
    apigee-udca UDCA apigee apigee-udca-hybrid-example-3b2ebf3-151-q4g2c-vnzg9
    apigee-watcher Watcher apigee apigee-watcher-hybrid-example-d89fed1-151-cpu3s-sxxdf
  • diagnostic.namespace：您要收集資料的 Pod 所在的 Kubernetes 命名空間。命名空間必須與您透過 diagnostic.container 指定的容器相符。
  • diagnostic.podNames：要收集診斷資料的個別 Pod 名稱。例如： 
    diagnostic:
 …
 podNames:
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

只有在作業設為 LOGGING 時才需要的屬性

只有在搭配 diagnostic.operation 執行診斷收集器時，才需要下列屬性。LOGGING

  • diagnostic.loggerNames：依名稱指定要從哪些記錄器收集資料。如果是 Apigee Hybrid 1.6.0 版，唯一支援的值是 ALL，也就是所有記錄器。例如： 
    diagnostic:
 …
 loggingDetails:
   loggerNames:
   - ALL
  • diagnostic.logLevel：指定要收集的記錄資料精細程度。 在 Apigee Hybrid 1.6 中，系統僅支援 FINE。
  • diagnostic.logDuration：收集記錄資料的時間長度 (以毫秒為單位)。一般值為 30000。

選用屬性

以下屬性為選用項目。

  • diagnostic.tcpDumpDetails.maxMsgs：設定要收集的 tcpDump 訊息數量上限。Apigee 建議最大值不超過 1000。
  • diagnostic.tcpDumpDetails.timeoutInSeconds：設定等待 tcpDump 傳回訊息的時間長度 (以秒為單位)。
  • diagnostic.threadDumpDetails.delayInSeconds：收集每個執行緒傾印之間的延遲時間 (以秒為單位)。必須搭配 diagnostic.threadDumpDetails.iterations 使用。
  • diagnostic.threadDumpDetails.iterations：要收集的 jstack 執行緒傾印疊代次數。必須搭配 diagnostic.threadDumpDetails.delayInSeconds 使用。

一般範例

以下是 diagnostic 節的範例，顯示所有可能的項目： 

diagnostic:
  # required properties:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "apigee-runtime"
  namespace: "apigee"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  # required if operation is Logging
  loggingDetails:
    loggerNames:
    - ALL
    logLevel: FINE
    logDuration: 30000

  # optional properties:
  tcpDumpDetails:
    maxMsgs: 10
    timeoutInSeconds: 100

  threadDumpDetails:
    iterations: 5
    delayInSeconds: 2

常見用途

以下範例說明如何在常見情況下設定及使用診斷收集器。

Proxy 延遲時間過長

在本例中，Apigee-runtime 處理要求的時間過長，導致客戶看到高代理伺服器延遲。您需要收集 Jstack 和 TOP 輸出內容。

  1. 選取任意 2 個執行階段 Pod。
  2. 請使用下列結構建立 diagnostic 節： 
    diagnostic:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "apigee-runtime"
  namespace: "apigee"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  tcpDumpDetails:
    maxMsgs: 10

  threadDumpDetails:
    iterations: 15
    delayInSeconds: 1
  3. 設定 diagnostic 節後，執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 收集記錄檔，然後刪除診斷收集器。 
    apigeectl diagnostic delete -f OVERRIDES_FILE

網路 / 連線問題

您需要對 apigee-runtime 和 Ingress 閘道 Pod 執行診斷。

  1. 選取任意 2 個執行階段 Pod。
  2. 請使用下列結構建立 diagnostic 節： 
    diagnostic:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "apigee-runtime"
  namespace: "apigee"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  tcpDumpDetails:
    maxMsgs: 1000
  3. 設定 diagnostic 節後，執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 收集記錄檔，然後刪除診斷收集器。 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. 從 Istio Ingress 閘道選取兩個 Pod。
  6. 使用 Istio Ingress Pod 重新設定 diagnostic 節： 
    diagnostic:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "istio-proxy"
  namespace: "istio-system"
  podNames:
  - istio-ingressgateway-696879cdf8-9zzzf
  - istio-ingressgateway-696879cdf8-6abc7

  tcpDumpDetails:
    maxMsgs: 1000
  7. 設定 diagnostic 節後，執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. 收集記錄檔，然後刪除診斷收集器。 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Proxy 發生非預期錯誤，或未套用新合約

在這種情況下，您需要將記錄層級變更為偵錯，至少 5 分鐘，甚至 10 分鐘 (如本範例所示)。這會增加記錄量，但記錄的資訊會很有幫助。 您將執行兩次診斷收集器，一次在 Apigee 執行階段，另一次在 Apigee 同步器。

  1. 選取任意 2 個執行階段 Pod。
  2. 請使用下列結構建立 diagnostic 節： 
    diagnostic:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "LOGGING"
  bucket: "diagnostics_data"
  namespace: "apigee"
  container: "apigee-runtime"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  loggingDetails:
    loggerNames:
    - ALL
    logLevel: FINE
    logDuration: 60000
  3. 設定 diagnostic 節後，執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 收集記錄檔，然後刪除診斷收集器。 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. 選取任意 2 個同步器 Pod。
  6. 請使用下列結構建立 diagnostic 節： 
    diagnostic:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "LOGGING"
  bucket: "diagnostics_data"
  namespace: "apigee"
  container: "apigee-synchronizer"
  podNames:
  - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-6cg78
  - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-1a2b3

  loggingDetails:
    loggerNames:
    - ALL
    logLevel: FINE
    logDuration: 60000
  7. 設定 diagnostic 節後，執行診斷收集器。 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. 收集記錄檔，然後刪除診斷收集器。 
    apigeectl diagnostic delete -f OVERRIDES_FILE