使用診斷收集器

系統會擷取哪些資料？

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

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

資料會受到什麼影響？

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

您可以選擇在建立支援單時，將這類資料提供給 Google Apigee 支援團隊。

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

使用診斷收集器前，請先完成下列先決條件：

Google Cloud Storage 值區

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

例如：

gcloud storage buckets create gs://apigee_diagnostic_data

Creating gs://apigee_diagnostic_data/...

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

服務帳戶

在專案中建立具有Storage 管理員角色 (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

請參閱：

• 建立及管理服務帳戶。
• 建立及管理服務帳戶金鑰。
• 瞭解角色：Cloud Storage 角色。

使用診斷收集器

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

1. 在 overrides.yaml 檔案中設定「診斷」節，選取所需資訊類型、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.loggingDetails.logDuration
  • diagnostic.loggingDetails.loggerNames
  • diagnostic.loggingDetails.logLevel
• diagnostic.bucket：Google Cloud Storage 值區的名稱，診斷資料會儲存於此處。這是您在前置條件中建立的值區。
• diagnostic.container：指定要擷取哪種類型的 Pod 資料。值可以是下列其中一個：

  container 值	Apigee 元件	Kubernetes 命名空間	這個容器中的 Pod 名稱範例
  apigee-cassandra	Cassandra	apigee	apigee-cassandra-default-0
  istio-proxy	Istio 入口	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 Collectors 時，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 需要很長的時間處理要求，導致客戶看到較高的 Proxy 延遲時間。您需要收集 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 gateway 容器上執行診斷作業。

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 入口閘道中選取兩個 Pod。
6. 使用 Istio 輸入 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