Aperçu

Cette page 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 au 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.

Cloud Trace recommande d'utiliser OpenTelemetry. OpenTelemetry est un produit Open Source issu de la fusion entre OpenCensus et OpenTracing.

Quand instrumenter votre application

Pour que votre application puisse envoyer des traces à Cloud Trace, elle doit être instrumentée. Vous pouvez instrumenter votre code à l'aide des bibliothèques clientes Google. Toutefois, il est recommandé d'utiliser OpenTelemetry ou OpenCensus pour instrumenter votre application. Il s'agit de packages de traçage Open Source. OpenTelementry est en développement actif et constitue le package privilégié.

Instrumenter le traçage des applications

Il existe trois façons de mettre en œuvre le traçage pour vos applications :

  • Utiliser OpenTelementry et la bibliothèque cliente Cloud Trace associée. Il s'agit de la méthode recommandée pour instrumenter vos applications.

  • Utiliser OpenCensus si aucune bibliothèque cliente OpenTelemetry n'est disponible pour votre langage.

  • Utiliser l'API Cloud Trace et écrire des méthodes personnalisées pour envoyer des données de traçage à Cloud Trace.

Le tableau suivant répertorie la bibliothèque cliente recommandée pour chaque langage de programmation :

Langue Bibliothèque cliente recommandée
Python OpenCensus
Java OpenCensus
Node.js Cloud Trace API
Go OpenCensus
C# .NET Cloud Trace API
PHP OpenCensus
Ruby Cloud Trace API

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

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.

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

Cloud Trace n'échantillonne pas toutes les requêtes. Par exemple, si vous utilisez Java et OpenCensus, seule une requête sur 10 000 est tracée. Si vous utilisez App Engine, les requêtes sont échantillonnées à raison de 0,1 requête par seconde pour chaque instance App Engine. Si vous utilisez l'API Cloud Trace, vous pouvez configurer les tarifs des clients. Certains packages, tels que le package Java OpenCensus, sont compatibles avec la configuration du taux d'échantillonnage.

Pour forcer le traçage d'une requête spécifique, ajoutez un en-tête X-Cloud-Trace-Context à la requête. La spécification d'en-tête est :

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

Où :

  • TRACE_ID est une valeur hexadécimale de 32 caractères. Elle représente un nombre de 128 bits. Elle doit être unique pour votre requête, à moins que vous ne vouliez volontairement regrouper des requêtes. Vous pouvez utiliser des UUID ;

  • SPAN_ID est la représentation décimale de l'ID de délai (non signé). Il doit être généré de manière aléatoire et unique dans votre trace. Pour les requêtes suivantes, définissez SPAN_ID sur l'ID de délai de la requête parente. Consultez la description de TraceSpan (REST, RPC) pour en savoir plus sur les traces imbriquées.

  • TRACE_TRUE doit être défini sur 1 pour suivre cette requête. Indiquez 0 pour ne pas suivre la requête.

Par exemple, pour forcer une trace avec curl :

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

Créer des exemples Cloud Trace

OpenCensus crée des exemples Cloud Trace lorsqu'il écrit des données de séries temporelles pour les services gRPC. Pour les consulter, créez un graphique et utilisez la barre d'outils du graphique pour activer l'affichage. Pour en savoir plus, consultez la page Utiliser la barre d'outils du graphique.

Si vous souhaitez écrire vos propres métriques personnalisées, consultez les ressources suivantes :

Si vous écrivez des métriques personnalisées, vous pouvez créer des exemples. L'extrait de code Go suivant montre comment créer un seul Point dans une série temporelle. Le premier élément correspond à l'intervalle de temps, libellé par Interval, et le second à la valeur. La valeur correspond à une instance d'un objet TypedValue et doit renvoyer une valeur distributionValue.

import (
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					&distributionpb.Distribution_Exemplar{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					&distributionpb.Distribution_Exemplar{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

Configurer votre projet Google Cloud

Pour utiliser Cloud Trace, l'API Cloud Trace doit être activée pour votre projet Google Cloud. Ce paramètre permet à votre projet Google Cloud de recevoir des données de trace provenant de sources authentifiées.

Par défaut, l'API Cloud Trace est activée pour les projets Google Cloud et aucune action n'est requise de votre part. Si vous avez modifié les niveaux d'accès de votre projet Google Cloud et souhaitez vérifier vos paramètres, procédez comme suit :

  1. Dans Google Cloud Console, accédez à API et services :

    Accéder aux API et aux services

  2. Cliquez sur + Enable APIs AND Services.(Activer des API et des services)

  3. Dans la barre de recherche, saisissez API Trace.

  4. Si l'option API activée est affichée, cette API est déjà activée et vous n'avez rien à faire. Sinon, cliquez sur Activer.

É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 langage :