Generare tracce e metriche con Go

Questo documento descrive come modificare un'app Go per raccogliere tracce e dati delle metriche utilizzando il framework open source OpenTelemetry e come e scrivere log JSON strutturati su "Standard-out". Il presente documento fornisce inoltre le informazioni su un'app di esempio che puoi installare ed eseguire. La è configurata per generare metriche, tracce e log.

Per saperne di più sulla strumentazione, consulta i seguenti documenti:

• Strumentazione e osservabilità.
• Scegli un approccio di misurazione.

Informazioni sul contesto

Il contesto di OpenTelemetry è un meccanismo per trasportare valori basati sull'ambito di esecuzione tra le API all'interno di un processo. Un uso importante del contesto è quello di intervallo attivo corrente in modo che possa essere modificato o indicato come padre di qualsiasi i nuovi intervalli al momento della creazione. In sintesi:

• Per contesto si intende il meccanismo per propagare i valori basati sull'ambito di esecuzione, incluso l'intervallo attivo corrente, tra le API all'interno di un processo.

• Contesto span è un oggetto immutabile in ogni span che include l'ID traccia, l'ID span, i flag e lo stato della traccia.

• La propagazione è il meccanismo che sposta il contesto tra servizi e processi.

context.Context della libreria standard di Go trasporta anche i valori con ambito tra i confini delle API. Di solito, le funzioni gestore in un server un Context in arrivo e passarlo attraverso la catena di chiamate a qualsiasi per i clienti che effettuano richieste in uscita.

La libreria standard di Go context.Context viene utilizzata come implementazione del contesto OpenTelemetry in Go.

Prima di iniziare

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

Enable the APIs

Instrumenta l'app per raccogliere tracce, metriche e log

Per instrumentare l'app in modo che raccolga dati relativi a tracce e metriche e per scrivere da JSON strutturato a Standard Out, esegui i seguenti passaggi come descritto nelle sezioni successive del presente documento:

1. Configurare la funzione principale
2. Configurare OpenTelemetry
3. Configurare il logging strutturato
4. Aggiungere la misurazione al server HTTP
5. Collega intervalli di tracce con log e metriche
6. Aggiungere la strumentazione al client HTTP
7. Scrivere log strutturati

Configura la funzione principale

Per configurare l'app in modo che scriva log strutturati e raccolga metriche e dati traccia utilizzando OpenTelemetry, aggiorna la funzione main per configurare il pacchetto di logging strutturato di Go, slog, e per configurare OpenTelemetry.

Il seguente esempio di codice illustra una funzione main che chiama due funzioni di supporto, setupLogging() e setupOpenTelemetry(). Queste funzioni di supporto configurano il pacchetto di logging e OpenTelemetry.

Per visualizzare l'anteprima completa, fai clic su Altro, quindi seleziona Visualizza su GitHub.

func main() {
	ctx := context.Background()

	// Setup logging
	setupLogging()

	// Setup metrics, tracing, and context propagation
	shutdown, err := setupOpenTelemetry(ctx)
	if err != nil {
		slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err))
		os.Exit(1)
	}

	// Run the http server, and shutdown and flush telemetry after it exits.
	slog.InfoContext(ctx, "server starting...")
	if err = errors.Join(runServer(), shutdown(ctx)); err != nil {
		slog.ErrorContext(ctx, "server exited with error", slog.Any("error", err))
		os.Exit(1)
	}
}

Dopo aver configurato il pacchetto di logging, collega i log alla traccia devi passare il comando Go Context al logger. Per ulteriori informazioni, consulta la sezione Scrivere log strutturati della presente documentazione documento.

Configurare OpenTelemetry

Per raccogliere ed esportare tracce e metriche utilizzando il protocollo OTLP, configura le istanze TracerProvider e MeterProvider globali. Il seguente esempio di codice illustra la funzione setupOpenTelemetry, che viene chiamata dalla funzione main:

func setupOpenTelemetry(ctx context.Context) (shutdown func(context.Context) error, err error) {
	var shutdownFuncs []func(context.Context) error

	// shutdown combines shutdown functions from multiple OpenTelemetry
	// components into a single function.
	shutdown = func(ctx context.Context) error {
		var err error
		for _, fn := range shutdownFuncs {
			err = errors.Join(err, fn(ctx))
		}
		shutdownFuncs = nil
		return err
	}

	// Configure Context Propagation to use the default W3C traceparent format
	otel.SetTextMapPropagator(autoprop.NewTextMapPropagator())

	// Configure Trace Export to send spans as OTLP
	texporter, err := autoexport.NewSpanExporter(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	tp := trace.NewTracerProvider(trace.WithBatcher(texporter))
	shutdownFuncs = append(shutdownFuncs, tp.Shutdown)
	otel.SetTracerProvider(tp)

	// Configure Metric Export to send metrics as OTLP
	mreader, err := autoexport.NewMetricReader(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	mp := metric.NewMeterProvider(
		metric.WithReader(mreader),
	)
	shutdownFuncs = append(shutdownFuncs, mp.Shutdown)
	otel.SetMeterProvider(mp)

	return shutdown, nil
}

Il precedente esempio di codice configura TextMapPropagator globale in modo da utilizzare il formato W3C Trace Context per propagare il contesto traccia. Questa configurazione garantisce che gli intervalli abbiano la relazione padre-figlio corretta all'interno di una traccia.

Per garantire che tutti i dati di telemetria in sospeso siano stati eliminati e che le connessioni siano chiuse controllata, la funzione setupOpenTelemetry restituisce una funzione denominata shutdown, che esegue queste azioni.

Configura il logging strutturato

Per includere le informazioni sulla traccia all'interno dei log in formato JSON scritti nella standard output, configura il pacchetto di logging strutturato Go, slog. Il seguente esempio di codice illustra la funzione setupLogging: che viene richiamata dalla funzione main:

func setupLogging() {
	// Use json as our base logging format.
	jsonHandler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: replacer})
	// Add span context attributes when Context is passed to logging calls.
	instrumentedHandler := handlerWithSpanContext(jsonHandler)
	// Set this handler as the global slog handler.
	slog.SetDefault(slog.New(instrumentedHandler))
}

Il codice precedente chiama la funzione handlerWithSpanContext, che estrae informazioni dall'istanza Context e le aggiunge come attributi a un log. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:

• logging.googleapis.com/trace: nome della risorsa della traccia associata alla voce di log.
• logging.googleapis.com/spanId: l'ID intervallo con la traccia che è associati alla voce di log.
• logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

Per saperne di più su questi campi, consulta la LogEntry alla struttura del centro di costo.

func handlerWithSpanContext(handler slog.Handler) *spanContextLogHandler {
	return &spanContextLogHandler{Handler: handler}
}

// spanContextLogHandler is an slog.Handler which adds attributes from the
// span context.
type spanContextLogHandler struct {
	slog.Handler
}

// Handle overrides slog.Handler's Handle method. This adds attributes from the
// span context to the slog.Record.
func (t *spanContextLogHandler) Handle(ctx context.Context, record slog.Record) error {
	// Get the SpanContext from the golang Context.
	if s := trace.SpanContextFromContext(ctx); s.IsValid() {
		// Add trace context attributes following Cloud Logging structured log format described
		// in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
		record.AddAttrs(
			slog.Any("logging.googleapis.com/trace", s.TraceID()),
		)
		record.AddAttrs(
			slog.Any("logging.googleapis.com/spanId", s.SpanID()),
		)
		record.AddAttrs(
			slog.Bool("logging.googleapis.com/trace_sampled", s.TraceFlags().IsSampled()),
		)
	}
	return t.Handler.Handle(ctx, record)
}

func replacer(groups []string, a slog.Attr) slog.Attr {
	// Rename attribute keys to match Cloud Logging structured log format
	switch a.Key {
	case slog.LevelKey:
		a.Key = "severity"
		// Map slog.Level string values to Cloud Logging LogSeverity
		// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
		if level := a.Value.Any().(slog.Level); level == slog.LevelWarn {
			a.Value = slog.StringValue("WARNING")
		}
	case slog.TimeKey:
		a.Key = "timestamp"
	case slog.MessageKey:
		a.Key = "message"
	}
	return a
}

Aggiungi la misurazione al server HTTP

Per aggiungere strumentazione traccia e metrica alle richieste gestite dal utilizzare OpenTelemetry. Nell'esempio seguente viene utilizzato il gestore otelhttp per propagare il contesto e per la strumentazione di tracce e metriche:

func runServer() error {
	handleHTTP("/single", handleSingle)
	handleHTTP("/multi", handleMulti)

	return http.ListenAndServe(":8080", nil)
}

// handleHTTP handles the http HandlerFunc on the specified route, and uses
// otelhttp for context propagation, trace instrumentation, and metric
// instrumentation.
func handleHTTP(route string, handleFn http.HandlerFunc) {
	instrumentedHandler := otelhttp.NewHandler(otelhttp.WithRouteTag(route, handleFn), route)

	http.Handle(route, instrumentedHandler)
}

Nel codice precedente, l'handler otelhttp utilizza le istanze globali TracerProvider, MeterProvider e TextMapPropagator. La La funzione setupOpenTelemetry configura queste istanze.

Collega gli intervalli di traccia con log e metriche

Per collegare gli intervalli del server e del client e associare metriche e log, passa l'istanza Go Context alla richiesta HTTP e quando scrivi i log. L'esempio seguente mostra un gestore di route che estrae l'istanza Context di Go e la passa al logger e alla funzione callSingle, che effettua una richiesta HTTP in uscita:

func handleMulti(w http.ResponseWriter, r *http.Request) {
	subRequests := 3 + rand.Intn(4)
	// Write a structured log with the request context, which allows the log to
	// be linked with the trace for this request.
	slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

	err := computeSubrequests(r, subRequests)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadGateway)
		return
	}

	fmt.Fprintln(w, "ok")
}

Nel codice precedente, la chiamata di funzione r.Context() recupera il valore Go Context dalla richiesta HTTP.

Aggiungere la misurazione al client HTTP

a inserire il contesto della traccia nelle richieste HTTP in uscita e aggiungere traccia e strumentazione metrica, chiama la funzione otelhttp.Get. Nell'esempio seguente, la funzione callSingle esegue questa azione:

func callSingle(ctx context.Context) error {
	// otelhttp.Get makes an http GET request, just like net/http.Get.
	// In addition, it records a span, records metrics, and propagates context.
	res, err := otelhttp.Get(ctx, "http://localhost:8080/single")
	if err != nil {
		return err
	}

	return res.Body.Close()
}

Nel codice precedente, il gestore otelhttp utilizza il campo Istanze TracerProvider, MeterProvider e TextMapPropagator. La La funzione setupOpenTelemetry configura queste istanze.

Scrittura di log strutturati

Per scrivere log strutturati che rimandano a una traccia, utilizza il pacchetto di logging strutturato di Go, slog, e passa l'istanza Context di Go al logger. L'istanza Go Context è necessaria quando vuoi collegare un log a un intervallo. Ad esempio, la seguente istruzione mostra come chiamare l'elemento InfoContext per slog e spiega come aggiungere il campo subRequests all'istanza JSON:

slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

Esegui un'app di esempio configurata per raccogliere la telemetria

L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per ottenere metriche e tracce. Per instradare la telemetria a Google Cloud, questo esempio utilizza OpenTelemetry Collector configurato con gli esportatori Google. Il generatore di carico inviata all'app invia richieste ai percorsi dell'app.

Scarica ed esegui il deployment dell'app

Nota: consigliamo di eseguire l'app di esempio utilizzando Cloud Shell. Tuttavia, se vuoi eseguire l'app di esempio in locale su Linux o Mac, salta il primo passaggio delle istruzioni riportate di seguito.

Per eseguire l'esempio, segui questi passaggi:

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Clona il repository:

   git clone https://github.com/GoogleCloudPlatform/golang-samples
   

3. Vai alla directory OpenTelemetry:

   cd golang-samples/opentelemetry/instrumentation
   

4. Crea ed esegui il sample:

   docker compose up --abort-on-container-exit
   

   Se non esegui l'applicazione su Cloud Shell, eseguila con la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS che rimanda a un file delle credenziali. App predefinita Credenziali fornisce un file di credenziali all'indirizzo $HOME/.config/gcloud/application_default_credentials.json.

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

Visualizzare le metriche

La strumentazione OpenTelemetry nell'app di esempio genera Prometheus che puoi visualizzare utilizzando Esplora metriche:

• Prometheus/http_server_duration/histogram registra la durata delle richieste del server e archivia i risultati in un istogramma.

• Prometheus/http_server_request_content_length_total/counter registra la lunghezza dei contenuti della richiesta per /multi e /single route HTTP. Le misurazioni di questa metrica sono cumulative, il che significa che ogni valore rappresenta il totale dall'inizio della raccolta dei valori.

• Prometheus/http_server_response_content_length_total/counter registra la durata dei contenuti della risposta per le route HTTP /multi e /single. Le misurazioni di questa metrica sono cumulative.

Per visualizzare le metriche generate dall'app di esempio: segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina  Esplora metriche:

   Vai a Esplora metriche

   Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

2. Nell'elemento Metrica, espandi il menu Seleziona una metrica, inserisci http_server nella barra dei filtri, poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
   1. Nel menu Risorse attive, seleziona Destinazione Prometheus.
   2. Nel menu Categorie di metriche attive, seleziona Http.
   3. Nel menu Metriche attive, seleziona una metrica.
   4. Fai clic su Applica.
3. Configura la modalità di visualizzazione dei dati.
   

   Quando le misurazioni di una metrica sono cumulativi, Metrics Explorer normalizza automaticamente i dati misurati il periodo di allineamento, che determina la visualizzazione di un tasso nel grafico. Per maggiori informazioni, consulta Tipi, conversioni e tipi.

   Quando vengono misurati valori interi o doppi, ad esempio con le due metrichecounter, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati per le route HTTP /multi e /single, imposta il primo menu della voce Aggregazione su Nessuna.

   Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche quando utilizzi Esplora metriche.

Visualizza le tue tracce

Per visualizzare i dati di traccia, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Esplora tracce.

   Vai a Trace Explorer

   Puoi trovare questa pagina anche utilizzando la barra di ricerca.

2. Nel grafico a dispersione, seleziona una traccia con l'URI /multi.

3. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo contrassegnato come /multi.

   Viene visualizzato un riquadro che mostra le informazioni sulla richiesta HTTP. Questi tra cui metodo, codice di stato, numero di byte e e lo user agent del chiamante.

4. Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.

   La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per ulteriori informazioni sull'utilizzo di Trace Explorer, consulta Trovare ed esplorare le tracce.

Visualizza i log

Da Esplora log, puoi ispezionare i log e anche visualizzare le tracce associate, se esistono.

1. Nella console Google Cloud, vai alla pagina Esplora log:

   Vai a Esplora log

   Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

2. Individua un log con la descrizione di handle /multi request.

   Per visualizzare i dettagli del log, espandi la voce di log. Nel campo jsonPayload è presente una voce denominata subRequests. Questa voce è stata aggiunta da un'istruzione nella funzione handleMulti.

3. Fai clic su Tracce in una voce di log con il messaggio "handle /multi request", quindi seleziona Visualizza dettagli traccia.

   Si apre un riquadro Dettagli su Trace che mostra la traccia selezionata.

Per ulteriori informazioni sull'uso di Esplora log, consulta Visualizza i log utilizzando Esplora log.

Passaggi successivi

• OpenTelemetry
• Specifiche OTLP
• Logging strutturato
• Risoluzione dei problemi di Managed Service per Prometheus
• Risolvere i problemi di Cloud Trace