Correlare metriche e tracce utilizzando gli esempi

Questo documento descrive gli esemplari, ovvero punti dati di esempio allegati a un punto dati della metrica. Un utilizzo degli esemplari è quello di memorizzare 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 esemplari.

Informazioni sugli esempi

Gli esemplari sono un modo per associare dati arbitrari ai dati delle metriche. Puoi utilizzarli per collegare dati non metrici alle misurazioni. Un utilizzo degli esemplari è quello di associare i dati di traccia ai dati delle metriche. In Cloud Monitoring, gli esemplari possono essere allegati ai dati delle metriche con il tipo di valore Distribution. Le metriche basate sulla 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, ma solo i conteggi dei bucket. Per ulteriori informazioni, consulta la sezione Informazioni sulle metriche basate sulla distribuzione.

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

I dati dell'istogramma vengono in genere visualizzati utilizzando una mappa termica. Quando un "punto" contiene un esemplare, Cloud Monitoring annota la mappa di calore con un punto:

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

Ad esempio, l'esempio di strumentazione Go utilizza OpenTelemetry per scrivere dati delle metriche, dati di traccia ed esemplari. Lo screenshot seguente mostra il valore della metrica prometheus/http_server_duration_milliseconds/histogram dopo diverse esecuzioni dell'applicazione:

Esempio di mappa termica che mostra più esemplari.

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

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

Esempio dei dettagli della traccia per un esemplare.

Se le informazioni visualizzate non sono sufficientemente dettagliate, puoi selezionare Visualizza in Trace, che apre la pagina Esplora tracce. In questa pagina puoi visualizzare gli attributi di 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 l'attuale span di una traccia a una misurazione della metrica. Tuttavia, per scrivere gli esempi devi:

  1. Configura gli SDK OpenTelemetry per metriche e tracce.

  2. Per includere gli esemplari nella strumentazione personalizzata, assicurati che la metrica venga registrata in un intervallo e di passare il contesto dall'intervallo 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 viene posticipata. Nota anche 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 esempio, vedi Aggiungere tracce e metriche personalizzate alla tua app.

Passaggi successivi