Ativar indicadores de telemetria nas bibliotecas de cliente Go

Google Cloud oferece funcionalidades avançadas de monitoramento, geração de registros e diagnóstico para aplicativos Go.

As bibliotecas de cliente do Go são instrumentadas para emitir dados de rastreamento, métricas e geração de registros. A instrumentação é opcional. É necessário ativá-la explicitamente. Este documento descreve os indicadores disponíveis e como ativá-los.

Indicadores disponíveis

Os indicadores incluem os seguintes dados de telemetria, aderindo às convenções semânticas do OpenTelemetry:

• Traces:traces HTTP/gRPC de baixo nível que representam as solicitações de rede feitas pelas bibliotecas de cliente.
• Métricas:métricas de solicitação do cliente, que rastreiam a latência e as taxas de solicitação. A métrica principal é gcp.client.request.duration.
• Registros:registros de erros acionáveis no nível DEBUG (e acima), que fornecem detalhes para solicitações com falha na camada de transporte, mesmo que elas sejam repetidas com sucesso.

Os indicadores incluem atributos padrão do OpenTelemetry (por exemplo, http.response.status_code e rpc.system.name) e Google Cloud-específicos atributos personalizados, que podem incluir estes e atributos semelhantes:

• gcp.client.service: o nome do serviço (por exemplo, pubsub ou storage).
• gcp.client.repo: o repositório da biblioteca de cliente (por exemplo, googleapis/google-cloud-go).
• gcp.client.version: a versão da biblioteca de cliente.
• gcp.client.artifact: o caminho do módulo específico (por exemplo, cloud.google.com/go/secretmanager).
• gcp.resource.destination.id: o ID do recurso em que a ação está sendo realizada.
• gcp.errors.domain: o domínio de erro para registros de erros acionáveis.
• gcp.errors.metadata.<key>: chaves de metadados de erro adicionais para solicitações com falha (aplanadas).

Para uma lista completa de atributos padrão, consulte as convenções semânticas HTTP e gRPC do OpenTelemetry.

Como ativar a telemetria

Para proteger dados sensíveis, os indicadores dourados ficam desativados por padrão. É necessário ativar explicitamente essa opção.

Traces, registros ou métricas podem conter dados sensíveis, como nomes de recursos, URLs completos e mensagens de erro.

Antes de configurar assinantes ou exportadores para traces, registros ou métricas, revise o conteúdo dos intervalos e registros e consulte a documentação do OpenTelemetry e do slog para configurar filtros e formatadores para evitar o vazamento de informações sensíveis, dependendo do caso de uso pretendido.

No Go, use as seguintes variáveis de ambiente para ativar traces, métricas e registros globalmente nas bibliotecas de cliente: Google Cloud

# 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

Propagação do contexto de trace

As bibliotecas de cliente do Go propagam automaticamente contextos de trace ativos para Google Cloud serviços, mesmo que a geração de traces (GOOGLE_SDK_GO_TRACING) esteja desativada.

Se o aplicativo tiver um intervalo do OpenTelemetry ativo no context.Context transmitido para um método de biblioteca de cliente, a biblioteca o usará para fornecer um contexto de rastreamento para as solicitações de saída. Isso garante que os traces no nível do aplicativo possam ser correlacionados com registros e comportamentos de serviço de back-end sem exigir que você emita intervalos do lado do cliente.

Configure um propagador de mapa de texto global do OpenTelemetry no aplicativo para fornecer um contexto de rastreamento para as bibliotecas de cliente.

Como exportar a telemetria

Depois que a telemetria é ativada nas bibliotecas de cliente, o aplicativo precisa ser configurado para coletar e exportar esses dados para o back-end de observabilidade.

Rastreamento e métricas

Para exportar os traces e as métricas gerados pelas bibliotecas de cliente do Go, inicialize o SDK do OpenTelemetry com o exportador preferido (por exemplo, OTLP) e configure o propagador de mapa de texto global no 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 mais detalhes sobre como conectar o SDK do OpenTelemetry ao Cloud Monitoring ou ao Cloud Trace, consulte os guias do Google Cloud Observability para Go.

Logging

As bibliotecas de cliente do Go usam o registro estruturado com slog para emitir erros acionáveis no nível DEBUG. Os registros exportados incluem automaticamente IDs de trace e IDs de intervalo se o framework de geração de registros estiver configurado para extraí-los do context.Context.

Para receber esses registros, é necessário fornecer um *slog.Logger configurado ao cliente na inicialização (por exemplo, usando option.WithLogger()).

Para encaminhar esses registros estruturados para o Cloud Logging, configure slog para gravar JSON na saída padrão (stdout). Se você estiver fazendo a implantação em um ambiente como o Google Kubernetes Engine ou o Cloud Run, os agentes integrados vão extrair esses registros automaticamente.

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 mais instruções sobre como mapear contextos de trace do OpenTelemetry e formatar registros JSON estruturados para se alinhar aos campos de payload esperados do Cloud Logging, consulte Configurar o registro estruturado para Go