在 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 語意慣例。

啟用遙測功能

為保護機密資料，系統預設會停用黃金信號。您必須明確選擇啟用這些功能。

在 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

追蹤內容傳播

即使停用追蹤記錄產生功能 (GOOGLE_SDK_GO_TRACING)，Go 用戶端程式庫仍會自動將有效追蹤記錄內容傳播至Google Cloud 服務。

如果應用程式在傳遞至用戶端程式庫方法的 context.Context 中有作用中的 OpenTelemetry 時距，程式庫會使用該時距為外送要求提供追蹤內容。這可確保應用程式層級的追蹤記錄與後端服務記錄和行為相互關聯，而不需發出用戶端範圍。

在應用程式中設定全域 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 Observability 指南。

記錄

Go 用戶端程式庫會使用結構化記錄功能 (透過 slog) 在 DEBUG 層級發出可採取行動的錯誤。如果記錄架構已設為從 context.Context 擷取追蹤 ID 和時距 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 設定結構化記錄」。