在 Go 客户端库中启用遥测信号

Google Cloud 可为 Go 应用提供强大的监控、日志记录和诊断功能。

Go 客户端库经过插桩，可发出跟踪记录、指标和日志记录数据。插桩是选择性加入的，您需要明确启用它。本文档介绍了可用的信号以及如何启用这些信号。

可用信号

这些信号包括以下遥测数据，这些数据遵循 OpenTelemetry 语义惯例：

跟踪记录：低级别 HTTP/gRPC 跟踪记录，表示客户端库发出的网络请求。
指标：客户端请求指标，用于跟踪延迟时间和请求速率。主要指标是 gcp.client.request.duration。
日志： DEBUG 级别（及更高级别）的可操作错误日志，提供传输层中失败请求的详细信息，即使这些请求最终重试成功也是如此。

这些信号包括标准 OpenTelemetry 属性（例如 http.response.status_code 和 rpc.system.name）和 Google Cloud特定于的自定义属性，这些属性可能包括以下属性和类似属性：

gcp.client.service：服务名称（例如 pubsub 或 storage）。
gcp.client.repo：客户端库代码库（例如 googleapis/google-cloud-go）。
gcp.client.version：客户端库版本。
gcp.client.artifact：特定模块路径（例如 cloud.google.com/go/secretmanager）。
gcp.resource.destination.id：正在执行操作的资源的 ID。
gcp.errors.domain：可操作错误日志的错误网域。
gcp.errors.metadata.<key>：失败请求的其他错误元数据键（扁平化）。

如需查看标准属性的完整列表，请参阅 OpenTelemetry HTTP 和 gRPC 语义惯例。

启用遥测

为保护敏感数据，Golden Signals 默认处于停用状态。您必须明确选择启用它们。

在 Go 中，使用以下环境变量在客户端库中全局启用跟踪记录、指标和日志： 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

跟踪上下文传播

Go 客户端库会自动将活跃跟踪上下文传播到 Google Cloud 服务，即使跟踪记录生成 (GOOGLE_SDK_GO_TRACING) 处于停用状态也是如此。

如果您的应用在传递给客户端库方法的 context.Context 中有活跃的 OpenTelemetry span，该库会使用它为出站请求提供跟踪上下文。这样可确保您的应用级跟踪记录可以与后端服务日志和行为相关联，而无需您发出客户端 span。

在您的应用中设置全局 OpenTelemetry 文本映射传播器，以便为客户端库提供跟踪上下文。

导出遥测数据

在客户端库中启用遥测后，您必须将应用配置为收集此数据并将其导出到可观测性后端。

跟踪记录和指标

如需导出 Go 客户端库生成的跟踪记录和指标，请使用首选导出器（例如 OTLP）初始化 OpenTelemetry SDK，并在 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 ...
}

如需详细了解如何将 OpenTelemetry SDK 连接到 Cloud Monitoring 或 Cloud Trace，请参阅适用于Go的 Google Cloud 可观测性指南。

日志记录

Go 客户端库使用 slog 进行结构化日志记录，以发出 DEBUG 级别的可操作错误。如果您的日志记录框架配置为从 context.Context 中提取跟踪记录 ID 和 span ID，则导出的日志会自动包含这些 ID。

如需接收这些日志，您必须在初始化时向客户端提供已配置的 *slog.Logger（例如，使用 option.WithLogger()）。

如需将这些结构化日志路由到 Cloud Logging，请将 slog 配置为将 JSON 写入标准输出 (stdout)。如果您要部署到 Google Kubernetes Engine 或 Cloud Run 等环境，内置代理会自动抓取这些日志。

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

如需详细了解如何映射 OpenTelemetry 跟踪上下文以及如何格式化结构化 JSON 日志以与 Cloud Logging 的预期载荷字段保持一致，请参阅为 Go 配置结构化日志记录