Esempio di strumentazione Go

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

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

Informazioni sul contesto

Il contesto di OpenTelemetry è un meccanismo per trasferire valori con ambito di esecuzione tra le API all'interno di un processo. Un utilizzo importante del contesto è quello di trasportare l'intervallo attivo corrente in modo che possa essere modificato o a cui si possa fare riferimento come elemento principale di qualsiasi nuovo intervallo quando viene creato. In sintesi:

  • Contesto si riferisce al meccanismo per propagare valori con ambito di esecuzione, inclusa l'attuale estensione attiva, tra le API all'interno di un processo.

  • Span Context è 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.

Anche context.Context della libreria standard di Go trasporta valori con ambito tra i limiti delle API. In genere, le funzioni del 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 OpenTelemetry in Go.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

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

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  8. Install the Google Cloud CLI.

  9. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

  10. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  11. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

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

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  14. Se esegui gli esempi in Cloud Shell, sulle risorse Google Cloud o in un ambiente di sviluppo locale, le autorizzazioni elencate in questa sezione sono sufficienti. Per le applicazioni di produzione, in genere un account di servizio fornisce le credenziali per scrivere dati di log, metriche e traccia.

    Per ottenere le autorizzazioni necessarie per consentire alle applicazioni di esempio di scrivere dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

    Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

    Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

    Instrumenta la tua app per raccogliere tracce, metriche e log

    Per instrumentare l'app in modo da raccogliere dati di traccia e metriche e scrivere JSON strutturato in standard out, segui i passaggi descritti nelle sezioni successive di questo documento:

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

    Configurare la funzione principale

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

    Per visualizzare l'esempio completo, fai clic su Altro e poi 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, per collegare i log ai dati di traccia, devi passare il contesto Go Context al logger. Per maggiori 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 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
}

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

    Per garantire che tutti i dati di telemetria in attesa vengano scaricati e che le connessioni vengano chiuse in modo controllato, la funzione setupOpenTelemetry restituisce una funzione denominata shutdown, che esegue queste azioni.

    Configura il logging strutturato

    Per includere le informazioni di tracciamento 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 chiamata 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 essere utilizzati per correlare un log a una traccia:

    • logging.googleapis.com/trace: il nome della 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 ulteriori informazioni su questi campi, consulta la struttura LogEntry.

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

// spanContextLogHandler is a 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 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 strumentazione al server HTTP

    Per aggiungere la strumentazione di traccia e metrica alle richieste gestite dal server HTTP, utilizza OpenTelemetry. Il seguente esempio utilizza il gestore otelhttp per propagare il contesto e per l'instrumentazione di traccia e metrica:

    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 globali TracerProvider, MeterProvider e TextMapPropagator. La funzione setupOpenTelemetry configura queste istanze.

    Collegare gli intervalli di traccia ai log e alle metriche

    Per collegare gli span del server e del client e per associare metriche e log, passa l'istanza Context di Go 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))

	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 di Go Context dalla richiesta HTTP.

    Aggiungere la strumentazione al client HTTP

    Per inserire il contesto di traccia nelle richieste HTTP in uscita e per aggiungere l'instrumentazione di traccia e metrica, chiama la funzione otelhttp.Get. Nell'esempio riportato di seguito, 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 globali TracerProvider, MeterProvider e TextMapPropagator. 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 uno span. 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 dati di telemetria

    L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per le metriche e le tracce. Per indirizzare la telemetria a Google Cloud, questo esempio utilizza OpenTelemetry Collector configurato con gli esportatori Google. Il generatore di carico nell'app invia richieste alle route dell'app.

    Scaricare ed eseguire il deployment dell'app

    Per eseguire l'esempio:

    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 campione:

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

      Se non esegui l'applicazione su Cloud Shell, esegui l'applicazione con la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS che punta a un file delle credenziali. Credenziali predefinite dell'applicazione fornisce un file di credenziali in $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

      5. Visualizzare le metriche

      L'instrumentazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Esplora metriche:

      • Prometheus/http_server_duration/histogram registra la durata delle richieste del server e memorizza 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 per 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, 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. Nella barra degli strumenti della console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
      3. Nell'elemento Metrica, espandi il menu Seleziona una metrica, digita http_server nella barra dei filtri e 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.

      4. Per aggiungere filtri, che rimuovono le serie temporali dai risultati della query, utilizza l'elemento Filtro.

      5. Configura la modalità di visualizzazione dei dati.

        Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, il che comporta la visualizzazione di 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 Aggregazione su Nessuna.

        Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche durante l'utilizzo di Esplora metriche.

      Visualizzare le tracce

      Potrebbero essere necessari diversi minuti prima che i dati di tracciamento siano disponibili. Ad esempio, quando i dati di traccia vengono ricevuti dal tuo progetto, Google Cloud Observability potrebbe dover creare un database per archiviarli. La creazione del database può richiedere alcuni minuti e durante questo periodo non sono disponibili dati di tracciamento da visualizzare.

      Per visualizzare i dati di traccia:

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

        Vai a Trace Explorer

        Puoi trovare questa pagina anche utilizzando la barra di ricerca.

      2. Nella sezione della tabella della pagina, seleziona una riga con il nome dello span /multi.

      3. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo etichettato /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, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

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

      Visualizza i log

      Da Esplora log puoi esaminare i log e visualizzare le tracce associate, se esistenti.

      1. Nella Google Cloud console, 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.

        I dati di log potrebbero essere disponibili diversi minuti prima dei dati di traccia. Se si verifica un errore durante la visualizzazione dei dati di traccia cercando una traccia per ID o seguendo i passaggi descritti in questa attività, attendi un minuto o due e riprova.

      Per ulteriori informazioni sull'utilizzo di Esplora log, vedi Visualizza i log utilizzando Esplora log.

      Passaggi successivi