Genera tracce e metriche con Go

Questo documento descrive come modificare un'app Go per raccogliere dati di tracce e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati nel formato standard. Questo documento fornisce anche informazioni su un'app di esempio che puoi installare ed eseguire. L'app è configurata per generare metriche, tracce e log.

Informazioni sul contesto

Context di OpenTelemetry è un meccanismo per trasferire valori con ambito di esecuzione nelle API all'interno di un processo. Un uso importante del contesto è quello di trasferire l'intervallo attivo corrente in modo che possa essere modificato o indicato come l'elemento padre di qualsiasi nuovo intervallo quando vengono creati. In sintesi:

• Il contesto si riferisce al meccanismo per propagare i valori basati sull'esecuzione, incluso l'intervallo attivo corrente, tra le API all'interno di un processo.

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

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

Anche context.Context della libreria standard di Go supporta valori con ambito che superano i confini delle API. In genere, le funzioni gestore in un server ricevono un Context in entrata e lo trasmettono attraverso la catena di chiamate a tutti i client che effettuano richieste in uscita.

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

Prima di iniziare

Abilita le API Cloud Logging API, Cloud Monitoring API, and Cloud Trace API.

Abilita le API

Instrumenta la tua app per raccogliere tracce, metriche e log

Per consentire alla tua app di raccogliere dati di traccia e metriche e di scrivere JSON strutturato all'out standard, segui i passaggi descritti nelle sezioni successive di questo documento:

1. Configura la funzione principale
2. Configura OpenTelemetry
3. Configurare il logging strutturato
4. Aggiungi la strumentazione al server HTTP
5. Collegare gli intervalli di traccia a log e metriche
6. Aggiungi la strumentazione al client HTTP
7. Scrivere log strutturati

Configura la funzione principale

Per configurare l'app in modo da scrivere log strutturati e raccogliere metriche e tracciare dati utilizzando OpenTelemetry, aggiorna la funzione main per configurare il pacchetto di logging strutturato Go, slog, e per configurare OpenTelemetry.

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

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, per collegare i log ai dati di traccia devi passare Context Vai al logger. Per ulteriori informazioni, consulta la sezione Scrivere log strutturati di questo documento.

Configura OpenTelemetry

Per raccogliere ed esportare tracce e metriche utilizzando il protocollo OTLP, configura le istanze globali TracerProvider e MeterProvider. Il seguente esempio di codice illustra la funzione setupOpenTelemetry, che viene richiamata 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
}

L'esempio di codice precedente configura l'elemento TextMapPropagator globale in modo che utilizzi il formato Contesto traccia W3C per il contesto della traccia di propagazione. 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 attesa vengano cancellati e che le connessioni vengano chiuse correttamente, la funzione setupOpenTelemetry restituisce una funzione denominata shutdown, che esegue queste azioni.

Configura il logging strutturato

Per includere le informazioni di traccia nei log in formato JSON scritti nell'output standard, 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 le 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 risorsa della traccia associata alla voce di log.
• logging.googleapis.com/spanId: l'ID intervallo con la traccia associata alla voce di log.
• logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

Per maggiori informazioni su questi campi, consulta la struttura LogEntry.

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 strumentazione al server HTTP

Per aggiungere strumentazione di tracce e metriche alle richieste gestite dal server HTTP, utilizza OpenTelemetry. L'esempio seguente utilizza 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, il gestore otelhttp utilizza le istanze TracerProvider, MeterProvider e TextMapPropagator globali. La funzione setupOpenTelemetry configura queste istanze.

Collega intervalli di tracce con log e metriche

Per collegare gli intervalli di server e client e associare metriche e log, passa l'istanza Vai Context alla richiesta HTTP e quando scrivi i log. L'esempio seguente illustra un gestore di route che estrae l'istanza Go Context 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))

	// Make 3-7 http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(r.Context()); err != nil {
			http.Error(w, err.Error(), http.StatusBadGateway)
			return
		}
	}

	fmt.Fprintln(w, "ok")
}

Nel codice precedente, la chiamata di funzione r.Context() recupera l'elemento Context Go dalla richiesta HTTP.

Aggiungi la strumentazione al client HTTP

Per inserire il contesto di traccia nelle richieste HTTP in uscita e per aggiungere la strumentazione di traccia e 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 le istanze TracerProvider, MeterProvider e TextMapPropagator globali. La funzione setupOpenTelemetry configura queste istanze.

Scrittura di log strutturati

Per scrivere log strutturati che rimandino a una traccia, utilizza il pacchetto di logging strutturato di Go, slog, e trasmetti l'istanza Go Context al logger. L'istanza Go Context è necessaria quando vuoi collegare un log a un intervallo. Ad esempio, la seguente istruzione mostra come chiamare il metodo InfoContext per slog e illustra 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 metriche e tracce. Per instradare la telemetria a Google Cloud, questo esempio utilizza il valore Collector di OpenTelemetry configurato con gli esportatori Google. Il generatore di carico nell'app invia richieste alle relative route.

Scaricare e implementare l'app

Nota: ti 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 nelle seguenti istruzioni.

Per eseguire l'esempio:

1. Nella console Google Cloud, attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

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 l'esempio:

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

   Se non è in esecuzione su Cloud Shell, esegui l'applicazione con la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS che punta a un file delle credenziali. Application default Credentials (Credenziali predefinite dell'applicazione) fornisce un file delle 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 metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:

• 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 le route HTTP /multi e /single. 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 lunghezza dei contenuti della risposta per le route HTTP /multi e /single. Le misurazioni per questa metrica sono cumulative.

Per visualizzare le metriche generate dall'app di esempio:

1. Nel pannello di navigazione della console Google Cloud, seleziona Monitoring e poi  Metrics Explorer:

   Vai a Metrics Explorer

2. Nell'elemento Metrica, espandi il menu Seleziona una metrica, inserisci http_server nella barra dei filtri, quindi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
   1. Nel menu Risorse attive, seleziona Target 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 il modo in cui vengono visualizzati i dati.
   

   Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, mostrando una frequenza nel grafico. Per ulteriori informazioni, consulta Tipi, tipi e conversioni.

   Quando vengono misurati valori interi o doppi, ad esempio con le due metriche counter, 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 Aggregation su None.

   Per maggiori informazioni sulla configurazione di un grafico, consulta Selezionare le metriche quando si utilizza Metrics Explorer.

Visualizza le tue tracce

Per visualizzare i dati di traccia:

1. Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

   Vai a Trace Explorer

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

3. Nel grafico di Gantt nel riquadro Dettagli traccia, seleziona l'intervallo denominato /multi.

   Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte 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, espandi la voce di log. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per maggiori informazioni sull'utilizzo di Cloud Trace Explorer, consulta Trovare ed esplorare tracce.

visualizza i log

In Esplora log puoi esaminare i log e visualizzare le tracce associate, se presenti.

1. Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:

   Vai a Esplora log

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 su una voce di log con il messaggio "handle /richiesta multipla", quindi seleziona Visualizza dettagli traccia.

   Si apre il riquadro Dettagli traccia che mostra la traccia selezionata.

Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizzare i log con Esplora log.

Passaggi successivi

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