Instrumenter une application pour la surveillance des applications

Ce document explique comment configurer une application App Hub afin que les métriques et les données de trace qu'elle génère contiennent des libellés spécifiques à l'application. Il explique également comment faire en sorte que votre application exporte une métrique utilisée par la surveillance des applications pour signaler le niveau de trafic, le taux d'erreurs du serveur ou la latence des charges de travail de requêtes HTTP qui s'exécutent sur Google Kubernetes Engine.

À propos des libellés spécifiques aux applications

Les libellés spécifiques à une application font référence aux libellés ou attributs insérés dans les données de journaux, de métriques ou de trace. Ces libellés identifient le service ou la charge de travail qui ont généré les données. Vous pouvez utiliser des libellés spécifiques aux applications comme n'importe quels autres libellés. Par exemple, vous pouvez filtrer les données par ID d'application. La télémétrie générée par l'infrastructure compatible inclut automatiquement ces libellés. Avec l'instrumentation, les métriques et les traces écrites par votre application peuvent inclure ces libellés.

Dans cette section, interprétez a.b.{x,y} comme a.b.x et a.b.y.

Les données de métriques issues de l'instrumentation que vous avez ajoutée à vos applications peuvent inclure les libellés de métriques suivants :

  • metric.labels.apphub_application_{container,id,location}
  • metric.labels.apphub_workload_{criticality_type,environment_type,id}

Les spans Trace générés par l'instrumentation que vous avez ajoutée à vos applications peuvent inclure les attributs de ressources suivants :

  • gcp.apphub.application.{container,id,location}
  • gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

À propos des métriques de serveur HTTP OpenTelemetry

Il n'existe aucune métrique système pour les charges de travail exécutées sur Google Kubernetes Engine qui peut indiquer le niveau de trafic, le taux d'erreur du serveur ou la latence des requêtes HTTP. Toutefois, les valeurs de ces signaux d'or peuvent être dérivées de http.server.request.duration, qui est une métrique collectée automatiquement par la bibliothèque de client HTTP OpenTelemetry.

L'exportateur googlemanagedprometheus convertit la métrique OpenTelemetry http.server.request.duration en métrique Prometheus présentant les propriétés suivantes :

  • Nom : prometheus/http_server_request_duration_seconds/histogram
  • Métrique : prometheus.googleapis.com/http_server_request_duration_seconds/histogram
  • Types de ressources : prometheus_target
  • Unité : s
  • Type : CUMULATIVE
  • Type de valeur : DISTRIBUTION

Lorsque votre projet Google Cloud contient la métrique http_server_request_duration_seconds, vos tableaux de bord Application Monitoring affichent le niveau de trafic, le taux d'erreur du serveur et la latence des requêtes HTTP.

Pour savoir comment configurer votre application afin d'exporter la métrique http_server_request_duration_seconds, consultez la section Utiliser OpenTelemetry sur Kubernetes de ce document.

Ajouter des libellés d'application aux données de métriques

Google Cloud Observability tente d'identifier la source des métriques Prometheus en comparant les attributs associés aux métriques Prometheus envoyées à votre projet avec les données renvoyées par l'API App Hub. Le reste de cette section liste les configurations qui permettent à Google Cloud Observability d'identifier l'application App Hub.

Utiliser OpenTelemetry sur Kubernetes

Pour que Google Cloud Observability associe des libellés d'application aux données de métriques générées par les charges de travail de votre application qui s'exécutent dans Google Kubernetes Engine, procédez comme suit :

  1. Instrumentez l'application avec OpenTelemetry.

  2. Déployez le collecteur conçu par Google ou le collecteur OpenTelemetry, puis configurez-le comme suit :

    • Exportez les données de métriques avec l'exportateur googlemanagedprometheus.
    • Configurez le processeur k8sattributes pour extraire les métadonnées, comme namespace, de l'environnement.
    • Configurez le processeur transform/collision pour définir les attributs project_id, location, cluster et namespace.
    • Configurez le processeur transform/aco-gke pour remplir les libellés top_level_controller_name et top_level_controller_type.

    Pour obtenir un exemple, consultez otlp-k8s-ingest/config/collector.yaml, qui est le fichier de configuration du collecteur Google. Pour en savoir plus sur ce collecteur, consultez Déployer le collecteur OpenTelemetry conçu par Google sur GKE.

  3. Enregistrez les charges de travail de votre application auprès d'App Hub.

Utiliser Google Cloud Managed Service pour Prometheus sur GKE

Pour que Google Cloud Observability associe des libellés d'application aux données de métriques générées par les charges de travail de votre application qui s'exécutent sur des clusters Google Kubernetes Engine, procédez comme suit :

  1. Utilisez Google Cloud Managed Service pour Prometheus avec la collecte gérée.

  2. Déployez vos charges de travail sur un cluster Google Kubernetes Engine dont la version est au moins 1.32.1-gke.1439000.

  3. Enregistrez les charges de travail de votre application auprès d'App Hub.

Google Cloud Managed Service pour Prometheus découvre les valeurs des libellés d'application grâce aux métadonnées de service discovery, puis ajoute les libellés top_level_controller_{name,type} à targetLabels.metadata. Lors de l'ingestion des métriques, Google Cloud Observability utilise les libellés top_level_controller_{name,type} et l'API App Hub pour identifier votre application App Hub et ajouter les libellés appropriés à vos données de métriques.

Utiliser Cloud Run

Pour que Google Cloud Observability associe des libellés d'application aux données de métriques générées par vos charges de travail Cloud Run, procédez comme suit :

  1. Instrumentez votre application à l'aide d'OpenTelemetry ou du side-car Managed Service pour Prometheus pour Cloud Run. Pour en savoir plus sur ces approches, consultez les documents suivants :

  2. Enregistrez les charges de travail de votre application auprès d'App Hub.

Vérifier les libellés des métriques

Pour vérifier que votre application envoie des métriques Prometheus à votre projet, procédez comme suit :

  1. Vérifiez que votre application envoie des métriques Prometheus à votre projet :

    1. Dans la console Google Cloud , accédez à la page  Explorateur de métriques.

      Accéder à l'Explorateur de métriques

      Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

    2. Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion du dossier compatible avec les applications.
    3. Dans l'élément Métrique, développez le menu Sélectionner une métrique, saisissez Prometheus Target dans la barre de filtre, puis utilisez les sous-menus pour sélectionner un type de ressource et des métriques spécifiques :
      1. Dans le menu Ressources actives, sélectionnez Cible Prometheus.
      2. Pour sélectionner une métrique, utilisez les menus Catégories de métriques actives et Métriques actives.
      3. Cliquez sur Appliquer.

    4. Pour ajouter des filtres qui suppriment des séries temporelles des résultats de la requête, utilisez l'élément Filtre.

    5. Configurez le mode d'affichage des données.

      Pour afficher les libellés, développez le menu Filtrer. Chaque entrée du filtre correspond à un libellé.

      Pour plus d'informations sur la configuration d'un graphique, consultez Sélectionner des métriques lorsque vous utilisez l'explorateur de métriques.

    Si vous ne voyez aucune métrique Prometheus, vérifiez votre configuration.

Si vos métriques Prometheus ne contiennent pas de libellés d'application, procédez comme suit :

  1. Vérifiez que vous avez enregistré votre charge de travail ou votre service dans App Hub.

  2. Examinez vos journaux pour déterminer s'il y a des erreurs.

    Par exemple, si vous déployez un collecteur OpenTelemetry ou le collecteur conçu par Google et que vous exécutez Google Kubernetes Engine, vous pouvez procéder comme suit :

    1. Dans la console Google Cloud , accédez à la page Charges de travail :

      Accéder à la page Charges de travail

      Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Kubernetes Engine.

    2. Sélectionnez le déploiement de votre collecteur, puis l'onglet Journaux.

  3. Si vous utilisez un collecteur OpenTelemetry ou le collecteur Google, vérifiez la configuration de votre collecteur. Votre collecteur doit effectuer les opérations suivantes :

    • Exportez les données de métriques avec l'exportateur googlemanagedprometheus.
    • Configurez le processeur k8sattributes pour extraire les métadonnées, comme namespace, de l'environnement.
    • Configurez le processeur transform/collision pour définir les attributs project_id, location, cluster et namespace.
    • Configurez le processeur transform/aco-gke pour remplir les libellés top_level_controller_name et top_level_controller_type.

    Pour obtenir un exemple, consultez le fichier de configuration du collecteur conçu par Google : otlp-k8s-ingest/config/collector.yaml.

Ajouter des attributs d'application aux spans de trace

Vous n'instrumentez pas votre application de sorte que des attributs spécifiques à l'application soient associés aux spans envoyés à votre projet Google Cloud . Au lieu de cela, Google Cloud Observability utilise les attributs de ressource OpenTelemetry et l'API App Hub pour identifier l'application App Hub associée à une étendue, puis ajoute les attributs spécifiques à l'application avant de stocker l'étendue.

Pour que Google Cloud Observability associe des attributs de ressources spécifiques à l'application aux données de trace générées par les services et les charges de travail de l'application, procédez comme suit :

Pour en savoir plus sur ces attributs, consultez Conventions sémantiques d'App Hub.Google Cloud

Attributs obligatoires

Cette section s'applique aux configurations dans lesquelles vous n'utilisez pas l'un des collecteurs recommandés. Par exemple, vous pouvez écrire votre propre collecteur ou préférer exporter directement vos données de trace.

Attributs qui identifient votre projet et l'emplacement de vos ressources

Définissez les attributs suivants :

  • Définissez cloud.provider sur "gcp".
  • cloud.account.id : définie sur l'ID de votre projet.
  • cloud.availability_zone ou cloud.region : définissez la zone ou la région où se trouvent vos ressources. Vous pouvez définir les deux attributs.

Les détecteurs de ressources peuvent vous aider à définir les attributs précédents :

Attributs pour les charges de travail Google Kubernetes Engine

Pour une charge de travail Google Kubernetes Engine, configurez votre collecteur ou votre instrumentation pour effectuer les opérations suivantes :

  • Extrayez les métadonnées, comme namespace, de l'environnement.
  • Extrayez les métadonnées pertinentes du processeur k8sattributes.
  • Définissez les attributs project_id, location, cluster et namespace.
  • Définissez les libellés top_level_controller_name et top_level_controller_type.

Pour obtenir un exemple basé sur un collecteur, consultez otlp-k8s-ingest/config/collector.yaml. Ce collecteur utilise le processeur k8sattributesprocessor.

Attributs pour les charges de travail de VM

Si vous déployez votre application sur une VM, celle-ci doit être associée à un groupe d'instances géré (MIG). Vous devez également joindre les attributs suivants :

  • gcp.gce.instance_group_manager.name
  • gcp.gce.instance_group_manager.region ou gcp.gce.instance_group_manager.zone