診断コレクタの使用

現在、Apigee ハイブリッド バージョン 1.7 のドキュメントを表示しています。このバージョンのサポートは終了しています。新しいバージョンにアップグレードする必要があります。詳細については、サポートされているバージョンをご覧ください。

Version 1.7 (unsupported)

   Supported versions:

• v1.11 (latest)                        
• v1.10                                        
• List of supported versions

   Unsupported versions:

• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

診断コレクタは、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 コンテナ、診断データを取得する個別の Pod を選択します。診断コレクタの overrides.yaml を構成するをご覧ください。
2. 次の apigeectl コマンドを使用して、診断コレクタを実行します。

   apigeectl diagnostic -f OVERRIDES_FILE

   OVERRIDES_FILE は overrides.yaml ファイルのパスです。

3. ログを調べます。
   1. apigee-diagnostic Namespace の 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 Namespace	このコンテナ内の 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 Namespace。diagnostic.container で指定したコンテナ用の正しい Namespace にする必要があります。
• 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