Correlare metriche e tracce utilizzando gli esempi

Questo documento descrive gli esemplari, ovvero punti di dati di esempio associati a un punto di dati della metrica. Un utilizzo degli esempi è archiviare un link a una traccia, che ti consente di correlare i dati delle metriche e delle tracce. Questo documento descrive anche come utilizzare OpenTelemetry per generare esempi.

Informazioni sugli esempi

Gli esemplari sono un modo per associare dati arbitrari ai dati delle metriche. Puoi utilizzarli per associare dati non metrici alle misurazioni. Un utilizzo degli esempi è associare i dati traccia ai dati delle metriche. In Cloud Monitoring, gli esempi possono essere collegati ai dati delle metriche con il tipo di valore Distribution. Le metriche con valori di distribuzione raccolgono molte misurazioni e le raggruppano in bucket. Ogni "punto" è un istogramma, ovvero un array che elenca i conteggi dei bucket. Le misurazioni effettive non vengono conservate, vengono conteggiati solo i bucket. Per ulteriori informazioni, consulta Informazioni sulle metriche con valori di distribuzione.

Quando viene scritto un punto dati della metrica, a questi dati può essere associato un array di oggetti Exemplar. Se vengono utilizzati, gli esemplari collegano informazioni utili ai dati delle metriche. Ad esempio, quando OpenTelemetry scrive un esemplare, allega un link all'intervallo corrente di una traccia.

I dati degli istogrammi vengono in genere visualizzati utilizzando una mappa termica. Quando un "punto" contiene un esempio, Cloud Monitoring annota la mappa di calore con un punto:

  • Per visualizzare le informazioni di riepilogo relative al punto della metrica, attiva la descrizione comando per l'annotazione.
  • Per accedere alla traccia, seleziona l'annotazione.

Ad esempio, l'applicazione di esempio descritta in Generare tracce e metriche con Go utilizza OpenTelemetry per scrivere dati delle metriche, dati delle tracce ed esempi. Lo screenshot seguente mostra il valore della metrica prometheus/http_server_duration_milliseconds/histogram dopo diverse esecuzioni dell'applicazione:

Esempio di una mappa termica che mostra più esempi.

Lo screenshot precedente mostra più esemplari. La descrizione comando di un esemplare è espansa e mostra la data, il nome della traccia, i percentile e un valore di latenza.

Quando l'annotazione è selezionata, viene visualizzata la traccia collegata nell'esemplare:

Esempio dei dettagli della traccia per un esemplare.

Quando le informazioni visualizzate non sono sufficientemente dettagliate, puoi selezionare Visualizza in Trace per aprire la pagina Esplora tracce. In questa pagina puoi visualizzare gli attributi traccia e accedere ai link alle voci di log.

Come attivare gli esemplari OpenTelemetry

Come illustrato nell'esempio precedente, puoi configurare OpenTelemetry per scrivere esemplari che collegano lo span corrente di una traccia a una misurazione metrica. Tuttavia, affinché gli esempi vengano scritti, devi:

  1. Configura sia gli SDK di traccia che quelli delle metriche OpenTelemetry.

  2. Per includere gli esempi nella tua strumentazione personalizzata, assicurati che la metrica venga registrata all'interno di uno span e che tu trasmetta il contesto dallo span con la misurazione della metrica.

    Ad esempio, la funzione computeSubrequests segue le indicazioni precedenti. La funzione subRequestsHistogram.Record viene richiamata dopo tracer.Start e prima di span.End, che è differita. Inoltre, tieni presente che il contesto ctx viene passato da tracer.Start alla funzione Record:

    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
}

    Per ulteriori informazioni su questo sample, consulta Aggiungere metriche e tracce personalizzate all'app.

Passaggi successivi