Choisir une approche d'instrumentation

Vous pouvez choisir l'approche d'instrumentation la plus efficace pour votre application en fonction de votre plate-forme de calcul Google Cloud et de vos exigences de télémétrie. Ce guide fournit des recommandations pour Google Kubernetes Engine (GKE), Compute Engine et Cloud Run, afin de vous aider à choisir entre le collecteur OpenTelemetry conçu par Google, l'agent Ops et l'exportation OpenTelemetry directe en cours de traitement.

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 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 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 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 les bibliothèques clientes Prometheus :

  • OpenTelemetry fournit un framework Open Source neutre du point de vue 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 au niveau d'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 depuis le processus de votre application. Le fichier de configuration du collecteur OpenTelemetry contrôle la façon dont le collecteur reçoit, traite et exporte les données de télémétrie. En général, nous recommandons que les collecteurs reçoivent et exportent la télémétrie à l'aide du protocole OTLP (OpenTelemetry Protocol). L'API Telemetry (OTLP) implémente ce protocole.

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

• Exportation basée sur un collecteur (neutre du point de vue du fournisseur) : vous instrumentez le code de votre application avec le SDK OpenTelemetry et utilisez l'exportateur OTLP en cours pour envoyer des données à un collecteur OpenTelemetry, tel que le collecteur OpenTelemetry conçu par Google ou un récepteur de l'agent Ops. Le collecteur reçoit la télémétrie et la transfère à votre projet Google Cloud . 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 un 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 accepte un. Pour les environnements dans lesquels l'exécution d'un processus de collecteur distinct n'est pas pratique, utilisez l'exportation directe en cours de traitement.

Recommandations de plates-formes

Étant donné que les environnements de calcul Google Cloud ont des fonctionnalités de cycle de vie et de side-car différentes, 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 conçu par 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 en cours d'exécution du SDK, les traite, puis les exporte. Veillez à configurer le collecteur pour exporter les données de métriques vers Managed Service pour Prometheus. Pour en savoir plus, consultez Premiers pas avec le collecteur OpenTelemetry.
Traces	Procédez comme suit : Déployez le collecteur OpenTelemetry conçu par Google sur Google Kubernetes Engine. Le collecteur reçoit les données de trace de l'exportateur OTLP en cours d'exécution du SDK, traite ces données, puis les envoie à votre projet Google Cloud à 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 les données de métriques et de traces des exportateurs OTLP en cours du SDK, transformer ces données, puis les envoyer à votre projet Google Cloud . Les données de métriques sont envoyées à l'aide de l'API Cloud Monitoring, et les données de trace sont envoyées à 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éployer 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éployez le collecteur OpenTelemetry conçu par Google sur Cloud Run. Le collecteur reçoit les données de journaux, de métriques et de traces des exportateurs OTLP en cours d'exécution du SDK, puis transforme les données reçues. Ensuite, il exporte les données de métriques à l'aide de l'exportateur googlemanagedprometheus, et il exporte les données de journaux et de métriques à l'aide des exportateurs Google Cloud . 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 Paramètres de facturation pour les services Cloud Run. Par ailleurs, si vous souhaitez uniquement configurer la collecte pour les métriques au format Prometheus, utilisez le side-car Prometheus pour Cloud Run afin de collecter des métriques instrumentées à l'aide de 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 Cloud Run Functions, consultez la page Présentation de Cloud Run Functions.

Type	Recommandation
Métriques	L'écriture directe des données de métriques n'est pas disponible dans Cloud Run Functions. Vous pouvez générer des métriques basées sur les journaux.
Traces	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. Cloud Run Functions collecte automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez 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 OTLP pour votre langage.
Traces	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. App Engine collecte automatiquement les journaux écrits dans stdout et stderr. Pour en savoir plus, consultez Écrire et afficher les journaux.

Exemples et guides d'implémentation

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

  • Go
  • Java
  • Node.js
  • Python

• La page 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.

• Observabilité pour les développeurs d'agents IA décrit 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 OTLP dans différents langages.

Références générales:

• API et SDK de langages
• Exportateur OTLP

Go

• SDK Go
• Exportateur OTLP pour Go

Java

• SDK Java
• Exportateur OTLP pour Java

JavaScript

• SDK JavaScript
• Exportateur OTLP pour JavaScript

Python

• SDK Python
• Exportateur OTLP pour Python