Utiliser le collecteur de diagnostics

Le collecteur de diagnostics est un outil qui capture les données de diagnostic des composants Kubernetes d'une instance Apigee hybrid à la demande et les stocke dans des buckets de stockage Google Cloud. Vous appelez le collecteur de diagnostics à l'aide de la commande apigeectl diagnostic.

Quelles sont les données système capturées ?

Le collecteur de diagnostics capture les types de données suivants :

Modification des niveaux de journalisation.
Jstack.
Fichier de configuration YAML pour POD.
Sortie PS -ef.
Vidage TCP.
Sortie TOP.

Qu'advient-il des données ?

Lorsque le collecteur de diagnostics capture les données, elles sont importées dans un bucket de stockage de votre projet Google Cloud. Vous pouvez afficher les données stockées dans le navigateur Google Cloud Platform : Cloud Storage.

Vous pouvez éventuellement choisir de partager ces données avec l'assistance Google Apigee lorsque vous créez une demande d'assistance.

Conditions préalables à l'exécution du collecteur de diagnostics

Avant d'utiliser le collecteur de diagnostics, vous devez remplir les conditions préalables suivantes :

Bucket Google Cloud Storage

Créez un bucket Google Cloud Storage avec un nom unique dans votre projet Google Cloud. Vous pouvez créer et gérer des buckets à l'aide des commandes gcloud storage ou du navigateur Google Cloud Platform : Cloud Storage.

Exemple :

gcloud storage buckets create gs://apigee_diagnostic_data

Creating gs://apigee_diagnostic_data/...

Consultez la page Créer des buckets de stockage pour obtenir des instructions.

Compte de service

Créez un compte de service avec le rôle Administrateur de l'espace de stockage (roles/storage.admin) dans votre projet, puis téléchargez le fichier de clé .json du compte de service.

Le compte de service peut avoir n'importe quel nom unique. Ce guide utilise "apigee-diagnostic" comme nom de compte de service.

Exemple :

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

Consultez les pages suivantes :

Utiliser le collecteur de diagnostics

Pour utiliser le collecteur de diagnostics, procédez comme suit :

Configurez le stanza de diagnostic dans votre fichier overrides.yaml pour sélectionner le type d'informations, le conteneur Apigee et les pods individuels à partir desquels vous souhaitez obtenir les données de diagnostic. Consultez la section Configurer overrides.yaml pour le collecteur de diagnostics.
Exécutez le collecteur de diagnostics à l'aide de la commande apigeectl suivante.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Où OVERRIDES_FILE est le chemin d'accès au fichier overrides.yaml.
Vérifiez les journaux :
1. Récupérez les pods dans l'espace de noms apigee-diagnostic.
```
kubectl get pods -n apigee-diagnostic
```
2. Notez le pod dont le nom contient diagnostic-collector.
3. Vérifiez les journaux à l'aide de la commande suivante :
```
kubectl -n apigee-diagnostic logs -f POD_NAME
```
  Où POD_NAME correspond au nom du pod du collecteur de diagnostics.
  
  Vous pouvez également consulter les journaux collectés dans le navigateur Google Cloud Platform : Cloud Storage.
Une fois les données collectées, supprimez le collecteur de diagnostics. Vous ne pouvez pas l'exécuter à nouveau tant que vous ne l'avez pas supprimé.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```

Configurer `overrides.yaml` pour le collecteur de diagnostics

Avant de pouvoir exécuter le collecteur de diagnostics, vous devez le configurer dans votre fichier overrides.yaml.

Pour obtenir la documentation de référence complète sur les propriétés de configuration diagnostic, consultez la documentation de référence sur les propriétés de configuration : diagnostic.

Propriétés obligatoires

Les propriétés suivantes sont requises pour exécuter le collecteur de diagnostics.

diagnostic.serviceAccountPath : chemin d'accès à un fichier de clé de compte de service doté du rôle "Administrateur de l'espace de stockage" dans Conditions préalables.
diagnostic.operation : indique si vous souhaitez collecter toutes les statistiques ou seulement les journaux.
Les valeurs sont : "ALL" ou "LOGGING".

Si vous définissez diagnostic.operation sur "LOGGING", les propriétés suivantes sont requises :
diagnostic.bucket : nom du bucket de stockage Google Cloud dans lequel vos données de diagnostic seront consignées. Il s'agit du bucket que vous avez créé dans la section Conditions préalables.

diagnostic.container : spécifie le type de pod à partir duquel vous capturez des données. Les valeurs peuvent être les suivantes :

Valeur `container`	Composant Apigee	Espace de noms Kubernetes	Exemple de nom de pod dans ce conteneur
`apigee-cassandra`	Cassandra	`apigee`	`apigee-cassandra-default-0`
`istio-proxy`	Entrée Istio	`istio-system`	`istio-ingressgateway-696879cdf8-9zzzf`
`apigee-mart-server`	MART	`apigee`	`apigee-mart-hybrid-example-d89fed1-151-jj2ux-l7nlb`
`apigee-runtime`	Processeur de messages	`apigee`	`apigee-runtime-hybrid-example-3b2ebf3-151-s64bh-g9qmv`
`apigee-synchronizer`	Synchronisateur	`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 : espace de noms Kubernetes dans lequel résident les pods à partir desquels vous collectez les données. L'espace de noms doit être correct pour le conteneur que vous spécifiez avec diagnostic.container.

diagnostic.podNames : noms des pods individuels pour lesquels vous souhaitez collecter des données de diagnostic Par exemple :

diagnostic:
 …
 podNames:
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
 - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

Propriétés requises seulement lorsque l'opération est définie sur `LOGGING`

Les propriétés suivantes ne sont requises que si l'exécution du collecteur de diagnostics avec diagnostic.operation est LOGGING.

diagnostic.loggerNames : spécifie le nom des enregistreurs à partir desquels collecter les données. Pour la version 1.6.0 d'Apigee hybrid, la seule valeur acceptée est ALL, ce qui signifie tous les enregistreurs. Par exemple :
```
diagnostic:
 …
 loggingDetails:
   loggerNames:
   - ALL
```
diagnostic.logLevel : indique la précision des données de journalisation à collecter. Dans Apigee hybrid 1.6, seule la valeur FINE est compatible.
diagnostic.logDuration : durée en millisecondes des données de journalisation collectées. Une valeur type est 30000.

Propriétés facultatives

Les propriétés suivantes sont facultatives.

diagnostic.tcpDumpDetails.maxMsgs : définit le nombre maximal de messages tcpDump à collecter. Apigee recommande une valeur maximale ne dépassant pas 1000.
diagnostic.tcpDumpDetails.timeoutInSeconds : définit le délai d'attente en secondes au terme duquel tcpDump renvoie des messages.
diagnostic.threadDumpDetails.delayInSeconds : délai en secondes entre la collecte de chaque vidage de thread. Doit être utilisée avec diagnostic.threadDumpDetails.iterations.
diagnostic.threadDumpDetails.iterations : nombre d'itérations de vidage de thread jstack à collecter. Doit être utilisée avec diagnostic.threadDumpDetails.delayInSeconds.

Exemple général

Voici un exemple de stanza diagnostic affichant toutes les entrées possibles :

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

Cas d'utilisation courants

Les exemples suivants montrent comment configurer et utiliser le collecteur de diagnostics dans certaines situations courantes.

Latence élevée de proxy

Dans ce cas, la propriété "Apigee-runtime" met beaucoup de temps à traiter les requêtes, ce qui entraîne une latence élevée de proxy pour les clients. Vous devez collecter les sorties Jstack et TOP.

Sélectionnez deux pods d'exécution.

Créez votre stanza diagnostic avec la structure suivante :

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

Après avoir configuré le stanza diagnostic, exécutez le collecteur de diagnostics.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Collectez les journaux et supprimez le collecteur de diagnostics.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```

Problèmes de connectivité/réseau

Vous devez exécuter des diagnostics sur "apigee-runtime" ainsi que sur les pods de passerelle d'entrée.

Sélectionnez deux pods d'exécution.

Créez votre stanza diagnostic avec la structure suivante :

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

Après avoir configuré le stanza diagnostic, exécutez le collecteur de diagnostics.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Collectez les journaux et supprimez le collecteur de diagnostics.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```
Sélectionnez deux pods dans la passerelle d'entrée Istio.

Reconfigurez votre stanza diagnostic avec les pods d'entrée Istio :

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

Après avoir configuré le stanza diagnostic, exécutez le collecteur de diagnostics.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Collectez les journaux et supprimez le collecteur de diagnostics.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```

Les proxys génèrent des erreurs inattendues ou les nouveaux contrats ne sont pas appliqués

Dans ce cas, les niveaux de journalisation doivent être modifiés pour déboguer pendant au moins cinq minutes, voire 10 minutes, comme dans cet exemple. La quantité de journaux augmente, mais des informations utiles sont consignées. Vous exécuterez le collecteur de diagnostics deux fois, une fois sur l'environnement d'exécution Apigee, puis sur le synchronisateur Apigee.

Sélectionnez deux pods d'exécution.

Créez votre stanza diagnostic avec la structure suivante :

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

Après avoir configuré le stanza diagnostic, exécutez le collecteur de diagnostics.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Collectez les journaux et supprimez le collecteur de diagnostics.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```
Sélectionnez deux pods de synchronisateur.

Créez votre stanza diagnostic avec la structure suivante :

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

Après avoir configuré le stanza diagnostic, exécutez le collecteur de diagnostics.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Collectez les journaux et supprimez le collecteur de diagnostics.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```

Utiliser le collecteur de diagnostics

Quelles sont les données système capturées ?

Qu'advient-il des données ?

Conditions préalables à l'exécution du collecteur de diagnostics

Bucket Google Cloud Storage

Compte de service

Utiliser le collecteur de diagnostics

Configurer overrides.yaml pour le collecteur de diagnostics

Propriétés obligatoires

Propriétés requises seulement lorsque l'opération est définie sur LOGGING

Propriétés facultatives

Exemple général

Cas d'utilisation courants

Latence élevée de proxy

Problèmes de connectivité/réseau

Les proxys génèrent des erreurs inattendues ou les nouveaux contrats ne sont pas appliqués

Configurer `overrides.yaml` pour le collecteur de diagnostics

Propriétés requises seulement lorsque l'opération est définie sur `LOGGING`