Abilitare gli indicatori di telemetria nelle librerie client Go

Google Cloud fornisce funzionalità avanzate di monitoraggio, logging e diagnostica per le applicazioni Go.

Le librerie client di Go sono strumentate per emettere dati di tracciamento, metriche e logging. La strumentazione è facoltativa, quindi devi attivarla in modo esplicito. Questo documento descrive gli indicatori disponibili e come attivarli.

Indicatori disponibili

Gli indicatori includono i seguenti dati di telemetria, in conformità con le convenzioni semantiche di OpenTelemetry:

• Tracce: tracce HTTP/gRPC di basso livello che rappresentano le richieste di rete effettuate dalle librerie client.
• Metriche: metriche delle richieste client, che tengono traccia della latenza e delle frequenze delle richieste. La metrica principale è gcp.client.request.duration.
• Log: log di errori utilizzabili a livello DEBUG (e superiori), che forniscono dettagli sulle richieste non riuscite a livello di trasporto, anche se alla fine vengono ritentate correttamente.

Gli indicatori includono attributi OpenTelemetry standard (ad esempio http.response.status_code e rpc.system.name) e Google Cloud-specifici attributi personalizzati, che possono includere questi e attributi simili:

• gcp.client.service: il nome del servizio (ad esempio pubsub o storage).
• gcp.client.repo: il repository della libreria client (ad esempio googleapis/google-cloud-go).
• gcp.client.version: la versione della libreria client.
• gcp.client.artifact: il percorso del modulo specifico (ad esempio cloud.google.com/go/secretmanager).
• gcp.resource.destination.id: l'ID della risorsa su cui viene eseguita l'azione.
• gcp.errors.domain: il dominio di errore per i log di errori utilizzabili.
• gcp.errors.metadata.<key>: chiavi di metadati di errore aggiuntive per le richieste non riuscite (appiattite).

Per un elenco completo degli attributi standard, consulta le convenzioni semantiche HTTP e gRPC di OpenTelemetry.

Abilitazione della telemetria

Per proteggere i dati sensibili, i Golden Signals sono disattivati per impostazione predefinita. Devi attivare esplicitamente l'opzione per abilitarli.

Le tracce, i log o le metriche possono contenere dati sensibili come nomi di risorse, URL completi e messaggi di errore.

Prima di configurare sottoscrittori o esportatori per tracce, log o metriche, esamina i contenuti degli span e dei log e consulta la documentazione di OpenTelemetry e slog per configurare filtri e formattatori per impedire la perdita di informazioni sensibili, a seconda del caso d'uso previsto.

In Go, utilizza le seguenti variabili di ambiente per attivare tracce, metriche e log a livello globale nelle Google Cloud librerie client:

# Enable trace generation (span emission)
export GOOGLE_SDK_GO_TRACING=true

# Enable metrics
export GOOGLE_SDK_GO_METRICS=true

# Enable logging
export GOOGLE_SDK_GO_LOGGING=true

Propagazione del contesto di Trace

Le librerie client di Go propagano automaticamente i contesti di traccia attivi ai Google Cloud servizi, anche se la generazione di tracce (GOOGLE_SDK_GO_TRACING) è disattivata.

Se l'applicazione ha uno span OpenTelemetry attivo nel context.Context passato a un metodo della libreria client, la libreria lo utilizza per fornire un contesto di tracciamento per le richieste in uscita. In questo modo, le tracce a livello di applicazione possono essere correlate ai log e ai comportamenti servizio di backend senza richiedere l'emissione di span lato client.

Configura un propagatore di mappe di testo OpenTelemetry globale nella tua applicazione per fornire un contesto di tracciamento per le librerie client.

Esportazione della telemetria

Una volta abilitata la telemetria nelle librerie client, l'applicazione deve essere configurata per raccogliere ed esportare questi dati nel backend di osservabilità.

Tracciamento e metriche

Per esportare le tracce e le metriche generate dalle librerie client di Go, inizializza l'SDK OpenTelemetry con l'esportatore che preferisci (ad esempio OTLP) e configura il propagatore di mappe di testo globale in main.go:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/trace"
)

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

    // Initialize the exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Set up the tracer provider
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    defer func() {
        // Ensure all spans are flushed before exit
        if err := tp.Shutdown(ctx); err != nil {
            log.Fatalf("failed to shutdown TracerProvider: %v", err)
        }
    }()

    otel.SetTracerProvider(tp)

    // Set up the global propagator
    otel.SetTextMapPropagator(propagation.TraceContext{})

    // ... initialize Google Cloud client libraries ...
}

Per maggiori dettagli sulla connessione dell'SDK OpenTelemetry a Cloud Monitoring o Cloud Trace, consulta le guide di Google Cloud Observability per Go.

Logging

Le librerie client di Go utilizzano il logging strutturato con slog per emettere errori utilizzabili a livello DEBUG. I log esportati includono automaticamente gli ID traccia e gli ID span se il framework di logging è configurato per estrarli da context.Context.

Per ricevere questi log, devi fornire un *slog.Logger configurato al client al momento dell'inizializzazione (ad esempio utilizzando option.WithLogger()).

Per instradare questi log strutturati a Cloud Logging, configura slog in modo che scriva JSON nell'output standard (stdout). Se esegui il deployment in un ambiente come Google Kubernetes Engine o Cloud Run, gli agenti integrati eseguono automaticamente lo scraping di questi log.

package main

import (
    "context"
    "log/slog"
    "os"

    "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
)

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

    // Configure slog to output JSON to stdout at the DEBUG level
    opts := &slog.HandlerOptions{Level: slog.LevelDebug}
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // Provide the logger to the client
    client, err := secretmanager.NewClient(ctx, option.WithLogger(logger))
    if err != nil {
        // handle error
    }
    defer client.Close()
}

Per ulteriori istruzioni sul mapping dei contesti di traccia OpenTelemetry e sulla formattazione dei log JSON strutturati in modo che corrispondano ai campi del payload previsti di Cloud Logging, consulta Configurare il logging strutturato per Go