診断コレクタの使用

現在、Apigee ハイブリッド バージョン 1.7 のドキュメントを表示しています。詳細については、サポートされているバージョンをご覧ください。

診断コレクタは、Apigee ハイブリッド インスタンスの Kubernetes コンポーネントで診断データをオンデマンドでキャプチャし、Google Cloud Storage バケットに保存するツールです。apigeectl diagnostic コマンドを使用して、診断コレクタを呼び出します。

収集されるシステムデータ

診断コレクタは、次の種類のデータをキャプチャします。

• ログレベルの変更。
• Jstack。
• POD 構成 yaml。
• PS -ef 出力。
• TCP ダンプ。
• TOP 出力。

データの処理方法

診断コレクタがデータをキャプチャすると、Google Cloud プロジェクトのストレージ バケットにアップロードされます。保存されたデータは、Google Cloud Platform: Cloud Storage ブラウザで表示できます。

必要に応じて、サポート チケットの作成時に Google Apigee サポートとこのデータを共有することもできます。

注:診断コレクタによって収集されるデータでは、ユーザー ランタイム データや機密情報は収集されません。

診断コレクタを実行するための前提条件

診断コレクタを使用するには、次の前提条件を満たす必要があります。

Google Cloud Storage バケット

Google Cloud プロジェクトに一意の名前で Google Cloud Storage バケットを作成します。バケットの作成と管理は、gsutil コマンドまたは Google Cloud Platform: Cloud Storage ブラウザを使用して行います。

次に例を示します。

gsutil mb gs://apigee_diagnostic_data

Creating gs://apigee_diagnostic_data/...

バケット名は、組織外のものも含め、すべての Google Cloud プロジェクトでグローバルに一意である必要があります。

手順については、ストレージ バケットの作成をご覧ください。

サービス アカウント

プロジェクトでストレージ管理者のロール（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 コンテナ、診断データを取得する個別のポッドを選択します。診断コレクタ用の 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: 前提条件でストレージ管理者のロールを持つサービス アカウントのサービス アカウント キー ファイルへのパス。
• 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 ingress	istio-system	istio-ingressgateway-696879cdf8-9zzzf
  apigee-mart-server	MART	apigee	apigee-mart-hybrid-example-d89fed1-151-jj2ux-l7nlb
  apigee-runtime	Message Processor	apigee	apigee-runtime-hybrid-example-3b2ebf3-151-s64bh-g9qmv
  apigee-synchronizer	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 ハイブリッド バージョン 1.6.0 でサポートされている値は ALL のみです。つまり、すべてのロガーです。次に例を示します。

  diagnostic:
   …
   loggingDetails:
     loggerNames:
     - ALL

• diagnostic.logLevel: 収集するロギングデータの粒度を指定します。Apigee ハイブリッド 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

一般的なユースケース

次の例は、一般的な状況で診断コレクタを構成して使用する方法を示しています。

高プロキシのレイテンシ

この場合、Apigee ランタイムはリクエストの処理に時間がかかり、プロキシのレイテンシが高くなっています。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 ゲートウェイから 2 つの 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

プロキシが予期しないエラーをスローしているか、新しい契約が適用されない

この場合、デバッグするログレベルを少なくとも 5 分間、この例では 10 分間変更する必要があります。これによりログの量が増えますが、有用な情報がログに記録されます。診断コレクタは 2 回（Apigee ランタイムで 1 回、Apigee Synchronizer で 1 回）実行します。

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. Synchronizer Pod を 2 つ選択します。
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