Ce document fournit une brève présentation sur la manière d'instrumenter votre application pour Cloud Trace. Pour obtenir des instructions détaillées sur la configuration de Cloud Trace, consultez les pages de configuration spécifiques à chaque langage.
Cloud Trace fournit des données de traçage distribuées pour vos applications. Après avoir instrumenté votre application, vous pouvez inspecter les données de latence d'une seule requête et afficher la latence globale d'une application entière dans la console Cloud Trace.
Quand instrumenter votre application
Lorsque les données de trace ne sont pas automatiquement capturées, vous devez instrumenter votre application pour les collecter.
Vous pouvez instrumenter votre application afin qu'elle collecte des informations spécifiques à l'application. Plusieurs frameworks d'instrumentation Open Source vous permettent de collecter des métriques, des journaux et des traces à partir de votre application, et d'envoyer ces données à n'importe quel fournisseur, y compris Google Cloud. Pour instrumenter votre application, nous vous recommandons d'utiliser un framework d'instrumentation Open Source neutre du point du vue du fournisseur, tel qu'OpenTelemetry, plutôt que des API spécifiques aux fournisseurs et aux produits ou des bibliothèques clientes.
Pour en savoir plus sur l'instrumentation de vos applications à l'aide de frameworks d'instrumentation neutres à l'égard des fournisseurs, consultez la section Instrumentation et observabilité.
Instrumenter des applications
Pour instrumenter vos applications afin de collecter des données de trace, vous pouvez procéder comme suit:
Vous pouvez utiliser OpenTelemetry et l'exportateur Cloud Trace associé pour les langages de programmation suivants:
SDK OpenTelemetry Exemple SDK Go Exemple de trace et de métriques pour Go SDK Java Exemple de trace et de métriques pour Java SDK Node.js Exemple de trace et de métriques pour Node.js SDK Python Exemple de trace et de métriques pour Python SDK C++ Exemple de trace pour C++ SDK Ruby Consultez la documentation OpenTelemetry. Si vous écrivez des applications exécutées sur Compute Engine, vous pouvez utiliser l'agent Ops et le récepteur du protocole OpenTelemetry (OTLP) pour collecter des traces et des métriques à partir de votre application. L'agent Ops peut également collecter des journaux, mais pas à l'aide d'OTLP. Pour en savoir plus, consultez les pages Utiliser l'agent Ops et OTLP et Présentation de l'agent Ops.
Vous pouvez utiliser les bibliothèques clientes ou appeler directement l'API Cloud Trace pour envoyer des données de traçage à Cloud Trace. Toutefois, nous vous recommandons d'utiliser OpenTelemetry lorsque votre langage est compatible avec cette bibliothèque.
Vous pouvez configurer un serveur Zipkin pour recevoir des traces de clients Zipkin, puis les transférer vers Cloud Trace pour analyse. Pour en savoir plus sur cette approche, consultez la section Utiliser Cloud Trace avec Zipkin.
Vous pouvez configurer les applications Spring Boot pour qu'elles transfèrent les données de trace qu'elles collectent vers Cloud Trace. Pour en savoir plus sur cette procédure, consultez Spring Cloud pour Google Cloud: Cloud Trace.
Quand créer des délais
Les bibliothèques clientes Cloud Trace gèrent généralement un contexte de trace global contenant des informations sur le délai actuel, y compris son ID de trace et si la trace est échantillonnée. Ces bibliothèques créent généralement des délais sur les limites RPC. Cependant, vous devrez peut-être créer des délais si l'algorithme de création par défaut n'est pas suffisant pour vos besoins.
Le délai actif actuel est accessible par le contexte de trace global, parfois encapsulé dans un objet Traceur. Vous pouvez ajouter des informations pertinentes à votre application en utilisant des annotations et des tags personnalisés pour les délais existants, ou créer des délais enfants avec leurs propres annotations et tags pour suivre le comportement de l'application avec une plus grande précision. Comme le contexte est global, les applications multithread qui mettent à jour le contexte doivent utiliser l'isolation appropriée.
Quand fournir des identifiants d'authentification
En général, vous n'avez pas besoin de fournir des identifiants d'authentification à votre application ni de spécifier votre ID de projet Google Cloud dans votre application lorsque vous exécutez sur Google Cloud. Pour certains langages, vous devez spécifier votre ID de projet Google Cloud même si vous exécutez sur Google Cloud. De plus, si vous utilisez le mode Autopilot pour Google Kubernetes Engine ou si vous activez la fédération d'identité de charge de travail pour GKE, vous devez configurer votre application pour qu'elle utilise la fédération d'identité de charge de travail pour GKE.
Si vous exécutez en dehors de Google Cloud, vous devez fournir des identifiants d'authentification à votre application. Vous devez également spécifier votre ID de projet Google Cloud dans votre application.
Pour en savoir plus, consultez les pages de configuration propres à chaque langue.
Forcer le traçage d'une requête
Sauf si votre application échantillonne toujours chaque intervalle, il n'est généralement pas possible de forcer le traçage d'une requête de bout en bout, car chaque composant d'une requête de bout en bout prend sa propre décision d'échantillonnage. Toutefois, vous pouvez influencer la décision en ajoutant à l'en-tête de trace un indicateur sampled
, avec cet indicateur défini sur true
. Ce paramètre est un indice pour les composants enfants d'échantillonner la requête.
Pour en savoir plus sur les en-têtes de trace, consultez la section Protocoles de propagation du contexte.
Pour les composants en aval dont vous êtes propriétaire, vous devez déterminer si votre logique d'instrumentation respecte l'indicateur sampled
.
Par exemple, lorsque vous utilisez OpenTelemetry pour l'instrumentation, vous pouvez utiliser l'échantillonneur ParentBased
pour vous assurer que l'indicateur d'échantillonnage parent est respecté.
Les services Google Cloud qui enregistrent des informations de traçage dans Cloud Trace acceptent généralement l'indicateur d'échantillonnage parent comme indice. Toutefois, la plupart des services limitent également l'échantillonnage. Chaque service Google Cloud détermine s'il est compatible avec le traçage, comment l'indicateur d'échantillonnage parent est utilisé et la limite de débit de l'échantillonnage.
Corréler des données métriques et de trace
Vous pouvez corréler les données de métriques à valeurs de distribution avec des traces en joignant des exemples aux points de données de métrique. Si vous suivez les étapes de configuration nécessaires, OpenTelemetry, qui est la bibliothèque d'instrumentation recommandée, ajoute automatiquement ces exemples. Pour en savoir plus, consultez la section Corréler des métriques et des traces à l'aide d'exemples.
Configurer votre projet et votre plate-forme
Assurez-vous que l'API Cloud Trace est activée.
Par défaut, l'API Cloud Trace est activée pour les projets Google Cloud et aucune action n'est requise de votre part. Toutefois, les contraintes de sécurité définies par votre organisation peuvent avoir désactivé l'API. Pour obtenir des informations de dépannage, consultez la section Développer des applications dans un environnement Google Cloud limité.
Enable the Cloud Trace API.
Configurez votre plate-forme.
Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.
Google Cloud: lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Toutefois, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.
Pour les configurations suivantes, les paramètres de niveau d'accès par défaut incluent le niveau d'accès de l'API Cloud Trace:
Si vous utilisez des niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé. Par exemple, si vous utilisez Google Cloud CLI pour créer un cluster GKE et si vous spécifiez l'option
--scopes
, assurez-vous que le champ d'application incluttrace.append
. La commande suivante illustre la définition de l'indicateur--scopes
:gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
Exécution en local et ailleurs: si votre application s'exécute en dehors de Google Cloud, vous devez fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit disposer du rôle Agent Cloud Trace (
roles/cloudtrace.agent
). Pour en savoir plus sur les rôles, consultez la section Contrôler l'accès avec IAM.Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous pouvez fournir ces identifiants de l'une des trois manières suivantes:
Exécuter
gcloud auth application-default login
Placez le compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Vous trouverez ci-dessous les chemins d'accès par défaut pour Windows et Linux:
Windows :
%APPDATA%/gcloud/application_default_credentials.json
Linux :
$HOME/.config/gcloud/application_default_credentials.json
Définissez la variable d'environnement
GOOGLE_APPLICATION_CREDENTIALS
sur le chemin d'accès à votre compte de service:Linux/macOS
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Powershell :
$env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"
Étape suivante
Pour obtenir des informations détaillées sur la configuration, des exemples et des liens vers GitHub et d'autres dépôts Open Source, accédez à la page de configuration de votre langue.
Exemples OpenTelemetry: