Telemetriesignale in Go-Clientbibliotheken aktivieren

Google Cloud bietet leistungsstarke Monitoring-, Logging- und Diagnosefunktionen für Go-Anwendungen.

Die Go-Clientbibliotheken sind so instrumentiert, dass sie Tracing-, Messwert- und Logging-Daten ausgeben. Die Instrumentierung ist optional. Sie müssen sie explizit aktivieren. In diesem Dokument werden die verfügbaren Signale und ihre Aktivierung beschrieben.

Verfügbare Signale

Die Signale umfassen die folgenden Telemetriedaten, die den semantischen OpenTelemetry-Konventionen entsprechen:

• Traces:HTTP-/gRPC-Traces auf niedriger Ebene, die die von den Clientbibliotheken ausgeführten Netzwerkanfragen darstellen.
• Messwerte:Messwerte für Clientanfragen, mit denen Latenz und Anfrageraten erfasst werden. Der primäre Messwert ist gcp.client.request.duration.
• Logs:Fehlerlogs auf der Ebene DEBUG und höher, die Details zu fehlgeschlagenen Anfragen auf der Transportschicht enthalten, auch wenn sie schließlich erfolgreich wiederholt werden.

Die Signale umfassen standardmäßige OpenTelemetry-Attribute (z. B. http.response.status_code und rpc.system.name) sowie Google Cloud-spezifische benutzerdefinierte Attribute, die diese und ähnliche Attribute enthalten können:

• gcp.client.service: Der Dienstname, z. B. pubsub oder storage.
• gcp.client.repo: Das Clientbibliotheks-Repository (z. B. googleapis/google-cloud-go).
• gcp.client.version: Die Version der Clientbibliothek.
• gcp.client.artifact: Der spezifische Modulpfad (z. B. cloud.google.com/go/secretmanager).
• gcp.resource.destination.id: Die ID der Ressource, auf die sich die Aktion bezieht.
• gcp.errors.domain: Die Fehlerdomain für umsetzbare Fehlerlogs.
• gcp.errors.metadata.<key>: Zusätzliche Metadatenschlüssel für Fehler für fehlgeschlagene Anfragen (reduziert).

Eine vollständige Liste der Standardattribute finden Sie in den semantischen OpenTelemetry-Konventionen für HTTP und gRPC.

Telemetrie aktivieren

Zum Schutz sensibler Daten sind Golden Signals standardmäßig deaktiviert. Sie müssen sie explizit aktivieren.

Traces, Logs oder Messwerte können sensible Daten wie Ressourcennamen, vollständige URLs und Fehlermeldungen enthalten.

Bevor Sie Abonnenten oder Exporter für Traces, Logs oder Messwerte konfigurieren, sollten Sie die Inhalte der Spans und Logs prüfen und die OpenTelemetry- und slog-Dokumentation lesen, um Filter und Formatierer einzurichten, damit je nach Anwendungsfall keine vertraulichen Informationen weitergegeben werden.

In Go können Sie die folgenden Umgebungsvariablen verwenden, um Traces, Messwerte und Logs global für alle Google Cloud Clientbibliotheken zu aktivieren:

# 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

Weitergabe von Trace-Kontext

Die Go-Clientbibliotheken übertragen aktive Trace-Kontexte automatisch anGoogle Cloud -Dienste, auch wenn die Trace-Generierung (GOOGLE_SDK_GO_TRACING) deaktiviert ist.

Wenn Ihre Anwendung einen aktiven OpenTelemetry-Span im context.Context hat, der an eine Clientbibliotheksmethode übergeben wird, verwendet die Bibliothek ihn, um einen Tracing-Kontext für die ausgehenden Anfragen bereitzustellen. So können Ihre Traces auf Anwendungsebene mit Backend-Dienstprotokollen und ‑verhalten korreliert werden, ohne dass Sie clientseitige Spans ausgeben müssen.

Richten Sie in Ihrer Anwendung einen globalen OpenTelemetry-Textmap-Propagator ein, um einen Trace-Kontext für die Clientbibliotheken bereitzustellen.

Telemetrie exportieren

Nachdem die Telemetrie in den Clientbibliotheken aktiviert wurde, muss Ihre Anwendung so konfiguriert werden, dass diese Daten erhoben und in Ihr Observability-Backend exportiert werden.

Tracing und Messwerte

Wenn Sie die von den Go-Clientbibliotheken generierten Traces und Messwerte exportieren möchten, initialisieren Sie das OpenTelemetry SDK mit dem gewünschten Exporter (z. B. OTLP) und richten Sie den globalen Text Map Propagator in Ihrem main.go ein:

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 ...
}

Weitere Informationen zum Verbinden des OpenTelemetry SDK mit Cloud Monitoring oder Cloud Trace finden Sie in den Google Cloud Observability-Leitfäden für Go.

Logging

Die Go-Clientbibliotheken verwenden strukturiertes Logging mit slog, um umsetzbare Fehler auf der Ebene DEBUG auszugeben. Die exportierten Logs enthalten automatisch Trace-IDs und Span-IDs, wenn Ihr Logging-Framework so konfiguriert ist, dass sie aus dem context.Context extrahiert werden.

Damit Sie diese Logs erhalten, müssen Sie dem Client bei der Initialisierung eine konfigurierte *slog.Logger bereitstellen, z. B. mit option.WithLogger().

Wenn Sie diese strukturierten Logs an Cloud Logging weiterleiten möchten, konfigurieren Sie slog so, dass JSON in die Standardausgabe (stdout) geschrieben wird. Wenn Sie in einer Umgebung wie Google Kubernetes Engine oder Cloud Run bereitstellen, werden diese Logs automatisch von den integrierten Agents erfasst.

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()
}

Weitere Informationen zum Zuordnen von OpenTelemetry-Trace-Kontexten und zum Formatieren strukturierter JSON-Logs, damit sie den erwarteten Nutzlastfeldern von Cloud Logging entsprechen, finden Sie unter Strukturiertes Logging für Go konfigurieren.