Habilita los indicadores de telemetría en las bibliotecas cliente de Go

Google Cloud proporciona servicios potentes de supervisión, registro y diagnóstico para las aplicaciones de Go.

Las bibliotecas cliente de Go están instrumentadas para emitir datos de registro, métricas y seguimientos. La instrumentación es opcional, por lo que debes habilitarla de forma explícita. En este documento, se describen los indicadores disponibles y cómo habilitarlos.

Indicadores disponibles

Los indicadores incluyen los siguientes datos de telemetría, que cumplen con las convenciones semánticas de OpenTelemetry:

• Seguimientos: Seguimientos de HTTP/gRPC de bajo nivel que representan las solicitudes de red realizadas por las bibliotecas cliente.
• Métricas: Métricas de solicitudes de cliente, que hacen un seguimiento de la latencia y las tasas de solicitudes. La métrica principal es gcp.client.request.duration.
• Registros: Registros de errores procesables en el nivel DEBUG (y superiores), que proporcionan detalles de las solicitudes fallidas en la capa de transporte, incluso si, finalmente, se reintentan de forma correcta.

Los indicadores incluyen atributos estándares de OpenTelemetry (por ejemplo, http.response.status_code y rpc.system.name) y Google Cloud-específicos atributos personalizados, que pueden incluir estos y atributos similares:

• gcp.client.service: El nombre del servicio (por ejemplo, pubsub o storage).
• gcp.client.repo: El repositorio de la biblioteca cliente (por ejemplo, googleapis/google-cloud-go).
• gcp.client.version: La versión de la biblioteca cliente.
• gcp.client.artifact: La ruta de acceso del módulo específico (por ejemplo, cloud.google.com/go/secretmanager).
• gcp.resource.destination.id: El ID del recurso sobre el que se actúa.
• gcp.errors.domain: El dominio de error para los registros de errores procesables.
• gcp.errors.metadata.<key>: Claves de metadatos de error adicionales para solicitudes fallidas (aplanadas).

Para obtener una lista completa de los atributos estándares, consulta las convenciones semánticas de OpenTelemetry HTTP y gRPC.

Habilita la telemetría

Para proteger los datos sensibles, los indicadores Golden Signals están inhabilitados de forma predeterminada. Debes habilitarlos de forma explícita.

Los seguimientos, los registros o las métricas pueden contener datos sensibles, como nombres de recursos, URLs completas y mensajes de error.

Antes de configurar suscriptores o exportadores para seguimientos, registros o métricas, revisa el contenido de los intervalos y los registros, y consulta la documentación de OpenTelemetry y slog para configurar filtros y formateadores que eviten la filtración de información sensible, según el caso de uso previsto.

En Go, usa las siguientes variables de entorno para activar los seguimientos, las métricas y los registros de forma global en tus Google Cloud bibliotecas cliente:

# 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

Propagación del contexto de seguimiento

Las bibliotecas cliente de Go propagan automáticamente los contextos de seguimiento activos a Google Cloud los servicios, incluso si la generación de seguimientos (GOOGLE_SDK_GO_TRACING) está inhabilitada.

Si tu aplicación tiene un intervalo de OpenTelemetry activo en el context.Context que se pasa a un método de biblioteca cliente, la biblioteca lo usa para proporcionar un contexto de seguimiento para las solicitudes salientes. Esto garantiza que los seguimientos a nivel de la aplicación se puedan correlacionar con los registros y los comportamientos del servicio de backend sin necesidad de que emitas intervalos del cliente.

Configura un propagador de mapa de texto global de OpenTelemetry en tu aplicación para proporcionar un contexto de seguimiento para las bibliotecas cliente.

Exporta la telemetría

Una vez que se habilita la telemetría en las bibliotecas cliente, se debe configurar tu aplicación para recopilar y exportar estos datos a tu backend de observabilidad.

Seguimiento y métricas

Para exportar los seguimientos y las métricas que generan las bibliotecas cliente de Go, inicializa el SDK de OpenTelemetry con el exportador que prefieras (por ejemplo, OTLP) y configura el propagador de mapa de texto global en tu 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 ...
}

Para obtener más detalles sobre cómo conectar el SDK de OpenTelemetry a Cloud Monitoring o Cloud Trace, consulta las guías de Google Cloud Observability para Go.

Logging

Las bibliotecas cliente de Go usan el registro estructurado con slog para emitir errores procesables en el nivel DEBUG. Los registros exportados incluyen automáticamente IDs de seguimiento y de intervalo si tu framework de registro está configurado para extraerlos del context.Context.

Para recibir estos registros, debes proporcionar un *slog.Logger configurado al cliente durante la inicialización (por ejemplo, con option.WithLogger()).

Para enrutar estos registros estructurados a Cloud Logging, configura slog para escribir JSON en la salida estándar (stdout). Si realizas la implementación en un entorno como Google Kubernetes Engine o Cloud Run, los agentes integrados rastrean automáticamente estos registros.

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

Para obtener más instrucciones sobre cómo asignar contextos de seguimiento de OpenTelemetry y dar formato a registros JSON estructurados para que se alineen con los campos de carga útil esperados de Cloud Logging, consulta Configura el registro estructurado para Go