Diagnose-Collector verwenden

Der Diagnose-Collector ist ein Tool, das bei Bedarf Diagnosedaten zu den Kubernetes-Komponenten einer Apigee Hybrid-Instanz erfasst und in Google Cloud Storage-Buckets speichert. Sie rufen den Diagnose-Collector mit dem Befehl apigeectl diagnostic auf.

Welche Systemdaten werden erfasst?

Der Diagnose-Collector erfasst folgende Datentypen:

  • Änderungen bei Logebenen.
  • Jstack.
  • YAML der POD-Konfiguration.
  • PS ef-Ausgabe.
  • TCP-Dump.
  • TOP-Ausgabe.

Was geschieht mit den Daten?

Wenn der Diagnose-Collector die Daten erfasst, werden sie in einen Storage-Bucket in Ihrem Google Cloud-Projekt hochgeladen. Sie können dann die gespeicherten Daten im Cloud Storage-Browser der Google Cloud Platform aufrufen.

Optional haben Sie die Möglichkeit, diese Daten an den Google Apigee-Support weiterzugeben, wenn Sie ein Support-Ticket erstellen.

Voraussetzungen für das Ausführen des Diagnose-Collectors

Bevor Sie den Diagnose-Collector verwenden können, müssen Sie folgende Aufgaben ausführen:

Google Cloud Storage-Bucket

Erstellen Sie einen Google Cloud Storage-Bucket mit einem eindeutigen Namen in Ihrem Google Cloud-Projekt. Sie können Buckets mit gsutil-Befehlen oder im Cloud Storage-Browser der Google Cloud Platform erstellen und verwalten.

Beispiel: 

gsutil mb gs://apigee_diagnostic_data
Creating gs://apigee_diagnostic_data/...

Informationen dazu finden Sie unter Storage-Buckets erstellen.

Dienstkonto

Erstellen Sie in Ihrem Projekt ein Dienstkonto mit der Rolle Storage-Administrator (roles/storage.admin) und laden Sie die .json-Schlüsseldatei des Dienstkontos herunter.

Das Dienstkonto kann einen beliebigen eindeutigen Namen haben. In dieser Anleitung wird "apigee-diagnostic" als Dienstkontoname verwendet.

Beispiel: 

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

Weitere Informationen:

Diagnose-Collector verwenden

Für die Verwendung des Diagnose-Collectors gilt folgende Sequenz:

  1. Konfigurieren Sie die Diagnose-Stanza in Ihrer Datei overrides.yaml, um den Informationstyp, den Apigee-Container und die einzelnen Pods auszuwählen, von denen Sie Diagnosedaten erfassen möchten. Weitere Informationen finden Sie unter overrides.yaml für den Diagnose-Collector konfigurieren.
  2. Führen Sie den Diagnose-Collector mit dem folgenden apigeectl-Befehl aus: 
    apigeectl diagnostic -f OVERRIDES_FILE

    Dabei ist OVERRIDES_FILE der Pfad zu Ihrer overrides.yaml-Datei.

  3. Prüfen Sie die Logs:
    1. Rufen Sie die Pods im Namespace apigee-diagnostic ab: 
      kubectl get pods -n apigee-diagnostic
    2. Notieren Sie sich den Pod, der im Namen diagnostic-collector enthält.
    3. Prüfen Sie die Logs mit dem folgenden Befehl: 
      kubectl -n apigee-diagnostic logs -f POD_NAME

      Dabei ist POD_NAME der Name des Diagnose-Collector-Pods.

      Sie können die erfassten Logs auch mit dem Cloud Storage-Browser der Google Cloud Platform aufrufen.

  4. Nachdem Sie die Daten erfasst haben, löschen Sie den Diagnose-Collector. Sie können ihn erst wieder ausführen, wenn Sie ihn zuvor gelöscht haben. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

overrides.yaml für den Diagnose-Collector konfigurieren

Bevor Sie den Diagnose-Collector ausführen können, müssen Sie ihn in der Datei overrides.yaml konfigurieren.

Eine vollständige Referenz der diagnostic-Konfigurationsattribute finden Sie unter Referenz zu Konfigurationsattributen: diagnostic.

Erforderliche Attribute

Die folgenden Attribute sind zum Ausführen des Diagnose-Collectors erforderlich:

  • diagnostic.serviceAccountPath: Der Pfad zu einer Dienstkontoschlüsseldatei für das Dienstkonto mit der Rolle "Storage-Administrator" unter Voraussetzungen.
  • diagnostic.operation: Gibt an, ob alle Statistiken oder nur Logs erfasst werden sollen.

    Mögliche Werte sind "ALL" und "LOGGING"

    Wenn Sie für diagnostic.operation den Wert "LOGGING" festlegen, sind die folgenden Attribute erforderlich:

  • diagnostic.bucket: Der Name des Google Cloud Storage-Buckets, in dem die Diagnosedaten gespeichert werden. Dies ist das Projekt, das Sie unter Voraussetzungen erstellt haben.
  • diagnostic.container: Damit wird angegeben, aus welchem Pod-Typ Daten erfasst werden. Folgende Werte sind möglich:
    container WertApigee-KomponenteKubernetes-NamespaceBeispiel für einen Pod-Namen in diesem Container
    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: Der Kubernetes-Namespace, in dem sich die Pods befinden, zu denen Sie Daten erfassen. Der Namespace muss für den Container richtig sein, den Sie mit diagnostic.container angeben:
  • diagnostic.podNames: Die Namen der einzelnen Pods, zu denen Sie Diagnosedaten erfassen möchten. Beispiel: 
    diagnostic:
 …
 podNames:
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

Attribute, die nur erforderlich sind, wenn der Vorgang auf LOGGING gesetzt ist.

Die folgenden Attribute sind nur erforderlich, wenn der Diagnose-Collector mit diagnostic.operation auf LOGGING ausgeführt wird.

  • diagnostic.loggerNames: Gibt die Namen der Logger an, von denen Daten erfasst werden sollen. Bei der Apigee Hybrid-Version 1.6.0 ist der einzige unterstützte Wert ALL. Dieser umfasst alle Logger. Beispiel: 
    diagnostic:
 …
 loggingDetails:
   loggerNames:
   - ALL
  • diagnostic.logLevel: Gibt den Detaillierungsgrad der Logging-Daten an, die erfasst werden sollen. In Apigee Hybrid 1.6 wird nur FINE unterstützt.
  • diagnostic.logDuration: Die Dauer der erfassten Logdaten in Millisekunden. Ein typischer Wert ist 30000.

Optionale Attribute

Die folgenden Attribute sind optional.

  • diagnostic.tcpDumpDetails.maxMsgs: Legt die maximale Anzahl der tcpDump-Nachrichten fest, die erfasst werden sollen. Apigee empfiehlt einen Höchstwert von 1000.
  • diagnostic.tcpDumpDetails.timeoutInSeconds: Legt die Wartezeit in Sekunden fest, bis tcpDump Nachrichten zurückgibt.
  • diagnostic.threadDumpDetails.delayInSeconds: Die Verzögerung zwischen der Erfassung der einzelnen Thread-Dumps in Sekunden. Muss zusammen mit diagnostic.threadDumpDetails.iterations verwendet werden.
  • diagnostic.threadDumpDetails.iterations: Die Anzahl der Jstack-Thread-Dump-Iterationen, die erfasst werden sollen. Muss zusammen mit diagnostic.threadDumpDetails.delayInSeconds verwendet werden.

Allgemeines Beispiel

Das folgende Beispiel zeigt eine diagnostic-Stanza mit allen möglichen Einträgen: 

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

Gängige Anwendungsfälle

Die folgenden Beispiele zeigen, wie der Diagnose-Collector in gängigen Situationen konfiguriert und verwendet wird.

Hohe Proxy-Latenz

In diesem Fall dauert die Verarbeitung der Anfragen durch die Apigee-Laufzeitumgebung sehr lange, sodass es für Kunden zu einer hohen Proxy-Latenz kommt. Sie müssen die Jstack- und TOP-Ausgabe erfassen.

  1. Wählen Sie zwei Laufzeit-Pods aus.
  2. Erstellen Sie die diagnostic-Stanza mit der folgenden Struktur: 
    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. Führen Sie nach der Konfiguration der diagnostic-Stanza den Diagnose-Collector aus. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Erfassen Sie die Logs und löschen Sie den Diagnose-Collector. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Probleme mit der Netzwerkverbindung

Sie müssen Diagnosen zu Apigee-Laufzeit- und Ingress-Gateway-Pods ausführen.

  1. Wählen Sie zwei Laufzeit-Pods aus.
  2. Erstellen Sie die diagnostic-Stanza mit der folgenden Struktur: 
    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. Führen Sie nach der Konfiguration der diagnostic-Stanza den Diagnose-Collector aus. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Erfassen Sie die Logs und löschen Sie den Diagnose-Collector. 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. Wählen Sie zwei Pods aus dem Istio-Ingress-Gateway aus.
  6. Konfigurieren Sie die diagnostic-Stanza mit den Istio-Ingress-Pods neu: 
    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. Führen Sie nach der Konfiguration der diagnostic-Stanza den Diagnose-Collector aus. 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. Erfassen Sie die Logs und löschen Sie den Diagnose-Collector. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Proxys geben unerwartete Fehler aus oder neue Verträge werden nicht angewendet

In diesem Fall müssen Sie die Logebenen für ein Debugging von mindestens 5 Minuten oder sogar von 10 Minuten wie in diesem Beispiel ändern. Dadurch wird zwar die Anzahl der Logs erhöht, es werden aber auch hilfreiche Informationen protokolliert. Sie führen den Diagnose-Collector zweimal aus, einmal in der Apigee-Laufzeit und dann im Apigee-Synchronizer.

  1. Wählen Sie zwei Laufzeit-Pods aus.
  2. Erstellen Sie die diagnostic-Stanza mit der folgenden Struktur: 
    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. Führen Sie nach der Konfiguration der diagnostic-Stanza den Diagnose-Collector aus. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Erfassen Sie die Logs und löschen Sie den Diagnose-Collector. 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. Wählen Sie zwei Synchronizer-Pods aus.
  6. Erstellen Sie die diagnostic-Stanza mit der folgenden Struktur: 
    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. Führen Sie nach der Konfiguration der diagnostic-Stanza den Diagnose-Collector aus. 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. Erfassen Sie die Logs und löschen Sie den Diagnose-Collector. 
    apigeectl diagnostic delete -f OVERRIDES_FILE