Correlare metriche e tracce utilizzando gli esempi

Puoi utilizzare gli esemplari per correlare i dati delle metriche e delle tracce. Un esemplare è una richiesta di campione rappresentativo o uno span associato a una misurazione della metrica. La tua applicazione può creare e allegare esemplari ai dati delle metriche. In alternativa, Google Cloud Observability può generarli dinamicamente quando traccia i risultati delle query. Collegando un singolo ID traccia a una metrica aggregata, gli esemplari ti aiutano a esaminare rapidamente la causa principale dei picchi di latenza o degli errori.

Questo documento descrive come configurare OpenTelemetry per creare e allegare esemplari di traccia ai dati delle metriche.

Se tracci i risultati delle query SQL su una dashboard, Google Cloud Observability può anche generare automaticamente gli esemplari. Per saperne di più, vedi Generare e visualizzare gli esemplari di traccia.

Informazioni sugli esemplari

Gli esemplari sono un modo per associare dati arbitrari ai dati delle metriche. Puoi utilizzarli per allegare dati non metrici alle misurazioni. Un utilizzo degli esemplari è l'associazione dei dati di traccia ai dati delle metriche. In Cloud Monitoring, gli esemplari possono essere allegati ai dati delle metriche con il Distribution tipo di valore. 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, solo i conteggi dei bucket. Per saperne di più, vedi Informazioni sulle metriche con valori di distribuzione.

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

I dati dell'istogramma vengono in genere visualizzati utilizzando una mappa termica. Quando un "punto" contiene un esemplare, Cloud Monitoring annota la mappa termica 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, il campione 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ù esemplari. La descrizione comando di un esemplare è espansa e mostra la data, il nome della traccia, i percentili e un valore di latenza.

Quando viene selezionata l'annotazione, 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 per aprire la pagina Esplora tracce. In questa pagina puoi visualizzare gli attributi della traccia e accedere ai link alle voci di log.

Come abilitare gli esemplari di OpenTelemetry

Come illustrato nell'esempio precedente, puoi configurare OpenTelemetry per scrivere esemplari che collegano l'intervallo corrente span di una traccia a una misurazione della metrica. Tuttavia, per scrivere gli esemplari, devi:

  1. Configurare gli SDK delle metriche e delle tracce di OpenTelemetry.

  2. Per includere gli esemplari nella strumentazione personalizzata, assicurati che la metrica venga registrata all'interno di 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 rinviata. 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 saperne di più su questo esempio, vedi Aggiungere tracce e metriche personalizzate alla tua app.

Passaggi successivi