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

L'ajout d'une instrumentation OpenTelemetry personnalisée au code de votre application vous permet d'enregistrer des segments de trace et des métriques personnalisés qui mesurent le comportement spécifique à l'application au-delà de ce que collectent les bibliothèques de framework standards. Vous pouvez appliquer les concepts de ce document aux applications écrites dans n'importe quel langage compatible avec OpenTelemetry. Pour en savoir plus, consultez Observabilité pour les développeurs d'applications et Choisir une approche d'instrumentation.

Les exemples de ce document utilisent l'exemple d'application Go décrit dans Exemple d'instrumentation Go, disponible sur GitHub.

Avant de commencer

Activez les API Cloud Logging, Cloud Monitoring et Cloud Trace, si elles ne le sont pas déjà.

Rôles requis pour activer les API

Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

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. Pour afficher l'exemple complet, sélectionnez le logo GitHub dans la barre d'outils de l'exemple.

    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, le code suivant utilise 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