Ajouter des traces et des métriques personnalisées à votre application

Ce document explique comment ajouter du code d'observabilité à votre application à l'aide d'OpenTelemetry. OpenTelemetry fournit des bibliothèques d'instrumentation qui génèrent des données de télémétrie pour les frameworks courants. Vous pouvez enrichir le contenu généré par la bibliothèque de télémétrie en ajoutant une instrumentation personnalisée qui mesure le comportement spécifique à l'application.

Les principes et concepts décrits dans ce document peuvent être appliqués aux applications écrites dans tous les langages compatibles avec OpenTelemetry. Pour en savoir plus sur l'instrumentation, consultez les documents suivants :

L'exemple de code, qui est la même application Go que celle décrite dans l'exemple d'instrumentation Go, est disponible dans GitHub. Pour afficher l'exemple complet, cliquez sur  Plus, puis sélectionnez Afficher sur GitHub.

Avant de commencer

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Créer des traces personnalisées

Pour générer des traces personnalisées à partir de votre application, ajoutez les éléments suivants au code d'instrumentation qui crée des segments OpenTelemetry. Dans OpenTelemetry, les segments sont les éléments de base des traces.

Pour créer un segment, procédez comme suit :

  1. Modifiez votre application pour acquérir un Tracer OpenTelemetry. Dans OpenTelemetry, un traceur est un créateur de segments. Vous pouvez vous procurer un traceur comme indiqué dans le code suivant :

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    Le nom du traceur, représenté par scopeName, identifie le champ d'application d'instrumentation des traces générées.

  2. Utilisez l'instance tracer pour créer des segments. Dans l'exemple de code suivant, la fonction computeSubrequests génère un segment chaque fois qu'elle est appelée :

    func computeSubrequests(r *http.Request, subRequests int) error {
	// Add custom span representing the work done for the subrequests
	ctx, span := tracer.Start(r.Context(), "subrequests")
	defer span.End()

	// Make specified number of http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(ctx); err != nil {
			return err
		}
	}
	// record number of sub-requests made
	subRequestsHistogram.Record(ctx, int64(subRequests))
	return nil
}

    Dans l'exemple de code précédent, le segment généré à partir de la fonction computeSubrequests représente le travail effectué par l'ensemble de la fonction. En effet, la première étape de la fonction consiste à démarrer un nouveau segment à l'aide de tracer.Start, et le mot clé defer avant l'élément span.End() garantit que le segment prend fin juste avant la fin de la fonction.

Création de métriques personnalisées

Pour générer des métriques à partir de votre application, vous devez ajouter un code d'instrumentation qui enregistre les mesures effectuées lors de l'exécution de votre application.

Pour créer des métriques, procédez comme suit :

  1. Modifiez votre application pour acquérir un Meter OpenTelemetry. Dans OpenTelemetry, un compteur permet d'accéder aux instruments de métrique pour enregistrer des métriques. Vous pouvez acquérir un compteur comme illustré dans le code suivant :

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    Le nom du compteur, représenté par scopeName, identifie le champ d'application d'instrumentation des métriques générées.

  2. Utilisez l'instance meter pour créer des instruments capables d'enregistrer des métriques. Par exemple, dans le code suivant, nous utilisons meter pour créer un histogramme OpenTelemetry :

    sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
	metric.WithUnit("s"))
if err != nil {
	panic(err)
}

    Le code précédent génère un histogramme nommé sleepHistogram.

  3. Utilisez l'instance sleepHistogram pour enregistrer le temps de mise en veille, qui est déterminé lorsque la fonction randomSleep est appelée :

    func randomSleep(r *http.Request) time.Duration {
	// simulate the work by sleeping 100 to 200 ms
	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
	time.Sleep(sleepTime)

	hostValue := attribute.String("host.value", r.Host)
	// custom histogram metric to record time slept in seconds
	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
	return sleepTime
}

    Les métriques enregistrées par ces outils sont exportées de votre application sur la base de la configuration de votre exportateur OpenTelemetry.

Étape suivante