Le traçage OpenTelemetry vous permet d'identifier et de suivre la latence de diverses opérations de la bibliothèque cliente Pub/Sub, telles que le traitement par lot, la gestion des baux et le contrôle du flux. La collecte de ces informations peut vous aider à déboguer les problèmes liés à la bibliothèque cliente.
Voici quelques cas d'utilisation potentiels du traçage OpenTelemetry :
- La latence de publication de votre service est plus élevée que d'habitude.
- Vous constatez un nombre élevé de nouvelles distributions de messages.
- Une modification de la fonction de rappel de votre client abonné entraîne un traitement plus long que d'habitude.
Avant de commencer
Avant de configurer OpenTelemetry, effectuez les tâches suivantes :
- Configurez Pub/Sub à l'aide de l'une des bibliothèques clientes.
- Installez le SDK OpenTelemetry, puis configurez un exportateur de trace et un fournisseur de traceur.
- Activez l'API Cloud Trace.
- Découvrez comment lire les traces Cloud Observability.
Rôles requis
Pour vous assurer que le compte de service dispose des autorisations nécessaires pour exporter des traces vers Cloud Trace, demandez à votre administrateur de lui accorder les rôles IAM suivants sur votre projet :
-
Tous :
Agent Cloud Trace (
roles/cloudtrace.agent
)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Ces rôles prédéfinis contiennent les autorisations requises pour exporter des traces vers Cloud Trace. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises
Les autorisations suivantes sont requises pour exporter des traces vers Cloud Trace :
-
Tous :
cloudtrace.traces.patch
Votre administrateur peut également attribuer au compte de service ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Workflow de traçage OpenTelemetry
Pour configurer le traçage OpenTelemetry, vous utilisez les bibliothèques clientes Pub/Sub et le SDK OpenTelemetry. Avec le SDK, vous devez configurer un exportateur de trace et un fournisseur de trace avant de vous connecter aux bibliothèques Pub/Sub. Dans certaines bibliothèques, la configuration d'un fournisseur de traceur est facultative.
Exportateur de trace. Le SDK OpenTelemetry utilise l'exportateur de trace pour déterminer où envoyer les traces.
Fournisseur de traceur. Les bibliothèques clientes Pub/Sub utilisent le fournisseur de traceur pour créer des traces.
Pour configurer le traçage, procédez comme suit :
- Instanciez un exportateur Cloud Trace OpenTelemetry.
- Si nécessaire, instanciez et enregistrez un fournisseur de traceur à l'aide du SDK OpenTelemetry.
- Configurez votre client avec l'option d'activation du traçage OpenTelemetry.
- Utilisez les bibliothèques clientes Pub/Sub pour publier un message.
Fonctionnement du traçage
Pour chaque message publié, la bibliothèque cliente crée une trace. Cette trace représente l'ensemble du cycle de vie du message, depuis le moment où vous publiez un message jusqu'à ce qu'il soit confirmé. Une trace encapsule des informations telles que la durée des opérations, les spans parents et enfants, et les spans associés.
Une trace se compose d'un span racine et de ses spans enfants correspondants. Ces portées représentent le travail effectué par la bibliothèque cliente lors du traitement d'un message. Chaque trace de message contient les éléments suivants :
- Pour la publication : Contrôle du flux, planification des clés de commande, traitement par lot et longueur du RPC de publication.
- Pour les abonnements : Contrôle de simultanéité, planification des clés de commande et gestion des baux.
Pour propager les informations du côté publication au côté abonnement, les bibliothèques clientes injectent un attribut de traçage spécifique du côté publication. Le mécanisme de propagation du contexte n'est activé que lorsque le traçage est activé et qu'il est précédé du préfixe googclient_
.
Publier des messages avec le traçage
L'exemple de code suivant montre comment activer le traçage à l'aide de la bibliothèque cliente Pub/Sub et du SDK OpenTelemetry. Dans cet exemple, les résultats du traçage sont exportés vers Cloud Trace.
Remarques
Lorsque vous instanciez le fournisseur de traceur, vous configurez un taux d'échantillonnage avec le SDK OpenTelemetry. Ce ratio détermine le nombre de traces que le SDK doit échantillonner. Un taux d'échantillonnage plus faible peut vous aider à réduire les coûts de facturation et à éviter que votre service ne dépasse le quota de spans Cloud Trace.
Go
C++
Python
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.
TypeScript
Node.js
Java
Recevoir des messages avec le traçage
Go
C++
Python
TypeScript
Node.js
Java
Analyser une trace
Les sections suivantes fournissent des informations détaillées sur le suivi et l'analyse d'une trace dans la console Google Cloud .
Remarques
- Lors de la publication d'un lot de messages, la portée RPC de publication est capturée dans une trace distincte.
- Un RPC de publication comporte plusieurs portées d'origine, car plusieurs appels de création peuvent entraîner un RPC de publication lorsqu'ils sont regroupés.
Dans OpenTelemetry, les segments peuvent avoir zéro ou un segment parent.
Les spans représentant des opérations par lot, comme publish batch (qui devrait logiquement avoir plusieurs parents), ne peuvent pas être représentés à l'aide de zéro ou d'un seul span parent.
Suivre les spans créés au cours du cycle de vie du message
L'image suivante montre un exemple de spans créés dans une seule trace pour un seul message.
Chaque span peut comporter des attributs supplémentaires qui fournissent des informations supplémentaires, telles que la taille en octets du message et les informations de clé de tri.
Les attributs de portée transmettent des métadonnées supplémentaires telles que la clé de tri du message, l'ID du message et la taille du message.
Les principales étendues de publication et d'abonnement sont augmentées avec des événements d'étendue qui correspondent au moment où un appel réseau est émis et à celui où il est terminé.
Résoudre les problèmes courants
Les problèmes suivants peuvent entraîner des problèmes de traçage :
- Le compte de service que vous utilisez pour exporter les traces ne dispose pas du rôle
roles/cloudtrace.agent
requis. - Le quota du nombre maximal de spans ingérés dans Cloud Trace a été atteint.
- Votre application est arrêtée sans appeler la fonction de vidage appropriée.