Activer les signaux de télémétrie dans les bibliothèques clientes Cloud pour Java

Google Cloud propose une suite très performante d'outils de surveillance, de journalisation et de diagnostic pour les applications Java.

Les bibliothèques clientes Java sont instrumentées pour émettre des données de traçage, de métriques et de journalisation. L'instrumentation est facultative. Vous devez l'activer explicitement. Ce document décrit les signaux disponibles et explique comment les activer.

Signaux disponibles

Les signaux d'or incluent les données de télémétrie suivantes, conformément aux OpenTelemetry conventions sémantiques :

  • Traces : traces HTTP/gRPC de bas niveau représentant les requêtes réseau effectuées par les bibliothèques clientes.
  • Métriques : métriques de requêtes clientes, qui suivent la latence et les taux de requêtes. La métrique principale est gcp.client.request.duration.
  • Journaux : journaux d'erreurs exploitables au niveau DEBUG, fournissant des informations sur les requêtes ayant échoué au niveau de la couche de transport, même si elles finissent par être retentées avec succès.

Les signaux incluent des attributs OpenTelemetry standards (par exemple, http.response.status_code et rpc.system.name) et Google Cloud-spécifiques attributs personnalisés, qui peuvent inclure les attributs suivants et d'autres similaires :

  • gcp.client.service : nom du service (par exemple, pubsub ou storage).
  • gcp.client.repo: dépôt de la bibliothèque cliente (par exemple, googleapis/google-cloud-java).
  • gcp.client.version : version de la bibliothèque cliente.
  • gcp.client.artifact: chemin d'accès au module spécifique (par exemple, com.google.cloud:google-cloud-secretmanager).
  • gcp.resource.destination.id : ID de la ressource sur laquelle l'action est effectuée.
  • gcp.errors.domain : domaine d'erreur pour les journaux d'erreurs exploitables.
  • gcp.errors.metadata.<key> : clés de métadonnées d'erreur supplémentaires pour les requêtes ayant échoué (aplaties).

Pour obtenir la liste complète des attributs standards, consultez les conventions sémantiques HTTP et gRPC d'OpenTelemetry.

Activer la télémétrie

Pour protéger les données sensibles, les signaux de télémétrie sont désactivés par défaut. Vous devez les activer explicitement.

Traçage et métriques

Dans les bibliothèques clientes Java générées, vous devez activer le traçage et les métriques de manière programmatique en fournissant la fabrique de traceurs appropriée aux paramètres de votre client lors de l'initialisation :

  • Traçage : configurez le client avec une OpenTelemetryTracingFactory.
  • Métriques : configurez le client avec une OpenTelemetryMetricsFactory.
  • Les deux : si vous souhaitez activer à la fois le traçage et les métriques, configurez le client avec une CompositeTracerFactory qui encapsule les deux fabriques.

Journalisation

Les journaux d'erreurs exploitables sont intégrés directement dans le framework ApiTracer de base. Pour activer les journaux d'erreurs exploitables de manière globale dans vos Google Cloud bibliothèques clientes, utilisez la variable d'environnement suivante :

export GOOGLE_SDK_JAVA_LOGGING=true

Propagation du contexte de trace

La propagation du contexte de trace dans les bibliothèques clientes Java nécessite que le traçage soit explicitement activé.

Lorsque la génération de traces est activée (par exemple, en configurant une OpenTelemetryTracingFactory) et que votre application comporte une étendue OpenTelemetry active dans le contexte actuel lorsqu'une méthode de bibliothèque cliente est appelée, la bibliothèque l'utilise pour fournir un contexte de traçage pour les requêtes sortantes. Cela permet de corréler les traces au niveau de l'application avec les journaux et les comportements des service de backend.

Exporter la télémétrie

Une fois la télémétrie activée dans les bibliothèques clientes, votre application doit être configurée pour collecter et exporter ces données vers votre backend d'observabilité.

Traçage et métriques

Pour exporter les traces et les métriques générées par les bibliothèques clientes Java, initialisez le SDK OpenTelemetry avec l'exportateur de votre choix (par exemple, OTLP) et configurez le propagateur de carte de texte globale dans votre application.

Pour en savoir plus sur la collecte et l'exportation de données OpenTelemetry vers Cloud Monitoring ou Cloud Trace, consultez Choisir une approche d'instrumentation.

Journalisation

Les bibliothèques clientes Java utilisent des frameworks de journalisation standards tels que SLF4J et java.util.logging. Lorsque GOOGLE_SDK_JAVA_LOGGING=true est défini, les journaux d'erreurs exploitables sont émis au niveau DEBUG.

Pour acheminer ces journaux structurés vers Cloud Logging, configurez votre framework de journalisation (par exemple, Logback) pour écrire du code JSON dans la sortie standard (stdout). Si vous effectuez un déploiement dans un environnement tel que Google Kubernetes Engine ou Cloud Run, les agents intégrés récupèrent automatiquement ces journaux.

Pour obtenir des instructions détaillées sur la configuration de Logback ou java.util.logging afin de générer du code JSON compatible avec Cloud Logging, y compris la corrélation des traces, consultez Configurer la journalisation structurée pour Java.