Choisir une approche d'instrumentation

Vous pouvez choisir l'approche d'instrumentation la plus efficace pour votre application en fonction de votre Google Cloud plate-forme de calcul et de vos exigences en matière de télémétrie. Ce guide fournit des recommandations pour Google Kubernetes Engine (GKE), Compute Engine et Cloud Run. Il vous aide à choisir entre le collecteur OpenTelemetry intégré à Google, l'agent Ops et l'exportation OpenTelemetry directe dans le processus.

Ce document fournit des recommandations générales, ainsi que des conseils pour les plates-formes suivantes :

• GKE
• Compute Engine
• Cloud Run
• Fonctions Cloud Run
• App Engine

Pour obtenir des exemples d'applications, consultez la section Exemples et guides d'implémentation.

Les recommandations figurant sur cette page ne sont pas les seules solutions, et d'autres approches peuvent fonctionner. Pour obtenir des conseils supplémentaires, contactez l'équipe Cloud Customer Care.

Recommandations générales

Cette section contient des recommandations générales sur la façon d'instrumenter votre application. Pour obtenir des conseils spécifiques à une plate-forme, consultez la section Recommandations par plate-forme.

• Données de journal : nous vous recommandons d'utiliser un framework pouvant être configuré pour générer des journaux structurés JSON pour Cloud Logging. Pour écrire des données de journal, nous vous recommandons de procéder comme suit :

  • Go : slog.
  • Python : logging.
  • JavaScript: Pino.
  • Java : SLF4J avec Log4j2

• Données de métriques : nous vous recommandons d'utiliser OpenTelemetry ou des bibliothèques clientes Prometheus :

  • OpenTelemetry fournit un framework Open Source indépendant du fournisseur et des bibliothèques clientes pour instrumenter les applications pour les métriques.
  • Les bibliothèques clientes Prometheus (Go, Java, Python, etc.) génèrent des métriques qui peuvent être exposées sur un point de terminaison HTTP et récupérées par un agent.

• Données de trace : nous vous recommandons d'utiliser OpenTelemetry pour générer des données de trace distribuées à partir du code de votre application.

Architectures de collecte OpenTelemetry

Lorsque vous instrumentez une application avec des bibliothèques OpenTelemetry, vous pouvez acheminer la télémétrie via le collecteur OpenTelemetry autonome ou l'exporter directement à partir du processus de votre application. Le fichier de configuration du collecteur OpenTelemetry contrôle la façon dont le collecteur reçoit, traite et exporte la télémétrie. En général, nous vous recommandons que les collecteurs reçoivent et exportent la télémétrie à l'aide du protocole OpenTelemetry (OTLP). L'API Telemetry (OTLP) implémente ce protocole.

Il existe deux approches fondamentales pour envoyer des données de télémétrie à votre Google Cloud projet :

• Exportation basée sur un collecteur (indépendante du fournisseur) : vous instrumentez le code de votre application avec le SDK OpenTelemetry et utilisez l'exportateur OTLP dans le processus pour envoyer des données à un collecteur OpenTelemetry, tel que le collecteur OpenTelemetry intégré à Google ou un récepteur d'agent Ops. Le collecteur reçoit les données de télémétrie et les transfère à votre Google Cloud projet. Le code de votre application reste totalement indépendant du fournisseur.

• Exportation directe (spécifique au fournisseur) : vous instrumentez le code de votre application avec le SDK OpenTelemetry et configurez OpenTelemetry pour envoyer des données de télémétrie à votre projet à l'aide de l'API Telemetry. Vous n'avez pas besoin de déployer de collecteur, mais le code de votre application inclut des dépendances spécifiques au fournisseur.

Nous vous recommandons d'utiliser un collecteur OpenTelemetry lorsque votre environnement de calcul en prend un en charge. Pour les environnements dans lesquels l'exécution d'un processus de collecteur distinct n'est pas pratique, utilisez l'exportation directe dans le processus.

Recommandations par plate-forme

Étant donné que Google Cloud les environnements de calcul ont des cycles de vie et des capacités de side-car différents, le modèle de collecte optimal varie selon la plate-forme. Les sections suivantes fournissent des recommandations spécifiques pour votre environnement de déploiement.

GKE

Pour obtenir des informations générales sur GKE, consultez la page Présentation de GKE.

Type	Recommandation
Métriques	Nous vous recommandons d'utiliser Google Cloud Managed Service pour Prometheus. Pour l'instrumentation, effectuez l'une des opérations suivantes: Utilisez les bibliothèques clientes Prometheus. Si vous utilisez cette approche, nous vous recommandons également d'utiliser la collecte gérée, qui inclut des instructions d'installation de l'exportateur qui peuvent être copiées et collées pour les applications courantes. Utilisez les bibliothèques OpenTelemetry et le collecteur OpenTelemetry : Déployez le collecteur OpenTelemetry intégré à Google sur Google Kubernetes Engine. Utilisez le SDK OpenTelemetry et l'exportateur OTLP pour votre langage. Le collecteur reçoit les données de métriques de l'exportateur OTLP dans le processus du SDK, les traite, puis les exporte. Assurez-vous de configurer le collecteur pour exporter les données de métriques vers Managed Service pour Prometheus. Pour en savoir plus, consultez la section Premiers pas avec le collecteur OpenTelemetry.
Traces	Procédez comme suit : Déployez le collecteur OpenTelemetry intégré à Google sur Google Kubernetes Engine. Le collecteur reçoit les données de trace de l'exportateur OTLP dans le processus du SDK, les traite, puis les envoie à votre Google Cloud projet à l'aide de l'API Telemetry (OTLP). Utilisez le SDK OpenTelemetry et l'exportateur OTLP pour votre langage.
Journaux	Configurez votre application pour générer des journaux structurés JSON vers stdout et stderr. Pour obtenir la liste des frameworks, consultez la page Frameworks de journalisation recommandés. GKE collecte automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez la page À propos des journaux GKE.

Compute Engine

Pour obtenir des informations générales sur Compute Engine, consultez la page Instances de machines virtuelles.

Type	Recommandation
Métriques et traces	Procédez comme suit : utiliser l'agent Ops pour collecter des métriques et des traces. Pour obtenir un exemple, consultez la section Collecter les métriques et les traces OpenTelemetry Protocol (OTLP). Ce guide explique comment configurer l'agent Ops pour recevoir des données de métriques et de traces des exportateurs OTLP dans le processus du SDK, transformer ces données, puis les envoyer à votre Google Cloud projet. Les données de métriques sont envoyées à l'aide de l'API Cloud Monitoring, et les données de trace à l'aide de l'API Cloud Trace. Utilisez le SDK OpenTelemetry et l'exportateur OTLP pour votre langage. Par ailleurs, si vous souhaitez configurer uniquement la collecte pour les métriques au format Prometheus, utilisez le récepteur Prometheus de l'agent Ops pour collecter les métriques instrumentées à l'aide des bibliothèques clientes Prometheus ou du SDK OpenTelemetry.
Journaux	Procédez comme suit : Configurez votre application pour générer des journaux structurés JSON dans un fichier. Pour obtenir la liste des frameworks, consultez la page Frameworks de journalisation recommandés. installer l'agent Ops et configurer un récepteur. Pour obtenir un exemple, consultez la section Récepteurs de journalisation.

Cloud Run

Pour obtenir des informations générales sur Cloud Run, consultez la page Qu'est-ce que Cloud Run ?

Type	Recommandation
Métriques et traces	Procédez comme suit : Utilisez le SDK OpenTelemetry et l'exportateur OTLP pour votre langage. Déployez un side-car OpenTelemetry pour collecter des métriques et des traces. Pour obtenir des exemples, consultez les documents suivants : Écrire des métriques OTLP à l'aide d'un side-car OpenTelemetry. Déployer le collecteur OpenTelemetry intégré à Google sur Cloud Run. Le collecteur reçoit les données de journaux, de métriques et de traces des exportateurs OTLP dans le processus du SDK, puis les transforme. Ensuite, il exporte les données de métriques à l'aide de l' googlemanagedprometheus exportateur, et il exporte les données de journaux et de métriques à l'aide des Google Cloud exportateurs. Pour votre service Cloud Run, utilisez la facturation basée sur les instances. Avec la facturation basée sur les instances, le processeur est alloué pendant tout le cycle de vie de l'instance , ce qui est nécessaire, car l'instrumentation OpenTelemetry effectue un traitement en arrière-plan. Pour en savoir plus, consultez la section Paramètres de facturation des services Cloud Run. Par ailleurs, si vous souhaitez configurer uniquement la collecte pour les métriques au format Prometheus, utilisez le side-car Prometheus pour Cloud Run afin de collecter les métriques instrumentées à l'aide des bibliothèques clientes Prometheus ou du SDK OpenTelemetry.
Journaux	Configurez votre application pour générer des journaux structurés JSON vers stdout et stderr. Pour obtenir la liste des frameworks, consultez la page Frameworks de journalisation recommandés. Cloud Run collecte automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez la section Écrire des journaux de conteneur.

Cloud Run Functions

Pour obtenir des informations générales sur les fonctions Cloud Run, consultez la page Présentation des fonctions Cloud Run.

Type	Recommandation
Métriques	L'écriture directe de données de métriques n'est pas disponible dans les fonctions Cloud Run. Vous pouvez générer des métriques basées sur les journaux.
Traces	Utilisez le SDK OpenTelemetry et l'exportateur Cloud Trace pour votre langage.
Journaux	Configurez votre application pour générer des journaux structurés JSON vers stdout et stderr. Pour obtenir la liste des frameworks, consultez la page Frameworks de journalisation recommandés. Les fonctions Cloud Run collectent automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez la section Fonctions Cloud Run : présentation de la surveillance et de la journalisation.

App Engine

Pour obtenir des informations générales sur App Engine, consultez la page Présentation d'App Engine.

Type	Recommandation
Métriques	Utilisez le SDK OpenTelemetry et l'exportateur Cloud Monitoring pour votre langage.
Traces	Utilisez le SDK OpenTelemetry et l'exportateur Cloud Trace pour votre langage.
Journaux	Configurez votre application pour générer des journaux structurés JSON vers stdout et stderr. Pour obtenir la liste des frameworks, consultez la page Frameworks de journalisation recommandés. App Engine collecte automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez la section Écrire et afficher des journaux.

Exemples et guides d'implémentation

• La présentation des exemples décrit l'architecture et les rôles Identity and Access Management requis pour les exemples de code suivants basés sur un collecteur :

  • Go
  • Java
  • Node.js
  • Python

• Migrer de l'exportateur Trace vers le point de terminaison OTLP explique comment mettre à jour une application qui utilise l'exportation directe pour envoyer des données de trace au format OTLP.

• Instrumenter des applications d'IA générative explique comment instrumenter ou activer des agents d'IA générative créés avec LangGraph ou le framework Agent Development Kit (ADK).

Documentation OpenTelemetry

Cette section fournit des liens vers le SDK OpenTelemetry et les exportateurs pour OTLP, Cloud Trace et Cloud Monitoring.

Références générales:

• API et SDK de langages
• Exportateur OTLP

Go

• SDK Go
• Exportateur OTLP pour Go
• Exportateur Cloud Trace pour Go
• Exportateur Cloud Monitoring pour Go

Java

• SDK Java
• Exportateur OTLP pour Java
• Exportateur Cloud Trace pour Java
• Exportateur Cloud Monitoring pour Java

JavaScript

• SDK JavaScript
• Exportateur OTLP pour JavaScript
• Exportateur Cloud Trace pour JavaScript
• Exportateur Cloud Monitoring pour JavaScript

Python

• SDK Python
• Exportateur OTLP pour Python
• Exportateur Cloud Trace pour Python
• Exportateur Cloud Monitoring pour Python