Mengaktifkan sinyal telemetri di library klien Go

Google Cloud menyediakan pemantauan, logging, dan diagnostik yang andal untuk aplikasi Go.

Library klien Go dilengkapi dengan instrumentasi untuk memancarkan data tracing, metrik, dan logging. Instrumentasi bersifat opsional; Anda harus mengaktifkannya secara eksplisit. Dokumen ini menjelaskan sinyal yang tersedia dan cara mengaktifkannya.

Sinyal yang tersedia

Sinyal mencakup data telemetri berikut, yang mematuhi OpenTelemetry Konvensi Semantik:

  • Trace: Trace HTTP/gRPC tingkat rendah yang mewakili permintaan jaringan yang dibuat oleh library klien.
  • Metrik: Metrik permintaan klien, yang melacak latensi dan kecepatan permintaan. Metrik utamanya adalah gcp.client.request.duration.
  • Log: Log error yang dapat ditindaklanjuti di tingkat DEBUG (dan yang lebih tinggi), yang memberikan detail untuk permintaan yang gagal di lapisan transportasi, meskipun akhirnya dicoba lagi dengan berhasil.

Sinyal mencakup atribut OpenTelemetry standar (misalnya, http.response.status_code dan rpc.system.name) dan Google Cloud-khusus atribut kustom, yang mungkin mencakup atribut ini dan atribut serupa:

  • gcp.client.service: Nama layanan (misalnya, pubsub atau storage).
  • gcp.client.repo: Repositori library klien (misalnya, googleapis/google-cloud-go).
  • gcp.client.version: Versi library klien.
  • gcp.client.artifact: Jalur modul tertentu (misalnya, cloud.google.com/go/secretmanager).
  • gcp.resource.destination.id: ID resource yang sedang ditindaklanjuti.
  • gcp.errors.domain: Domain error untuk log error yang dapat ditindaklanjuti.
  • gcp.errors.metadata.<key>: Kunci metadata error tambahan untuk permintaan yang gagal (diratakan).

Untuk daftar lengkap atribut standar, lihat OpenTelemetry HTTP dan gRPC konvensi semantik.

Mengaktifkan telemetri

Untuk melindungi data sensitif, Sinyal Emas dinonaktifkan secara default. Anda harus mengaktifkannya secara eksplisit.

Di Go, gunakan variabel lingkungan berikut untuk mengaktifkan trace, metrik, dan log secara global di seluruh Google Cloud library klien Anda:

# 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

Penerapan konteks trace

Library klien Go otomatis menerapkan konteks trace aktif ke Google Cloud layanan, meskipun pembuatan trace (GOOGLE_SDK_GO_TRACING) dinonaktifkan.

Jika aplikasi Anda memiliki rentang OpenTelemetry aktif di context.Context yang diteruskan ke metode library klien, library akan menggunakannya untuk menyediakan konteks tracing untuk permintaan keluar. Hal ini memastikan bahwa trace tingkat aplikasi Anda dapat dikorelasikan dengan log dan perilaku layanan backend tanpa mengharuskan Anda memancarkan rentang sisi klien.

Siapkan propagator peta teks OpenTelemetry global di aplikasi Anda untuk menyediakan konteks tracing bagi library klien.

Mengekspor telemetri

Setelah telemetri diaktifkan di library klien, aplikasi Anda harus dikonfigurasi untuk mengumpulkan dan mengekspor data ini ke backend observabilitas Anda.

Tracing dan metrik

Untuk mengekspor trace dan metrik yang dihasilkan oleh library klien Go, lakukan inisialisasi OpenTelemetry SDK dengan pengekspor pilihan Anda (misalnya, OTLP) dan siapkan propagator peta teks global di main.go Anda:

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

Untuk mengetahui detail selengkapnya tentang cara menghubungkan OpenTelemetry SDK ke Cloud Monitoring atau Cloud Trace, lihat panduan Google Cloud Observability untuk Go.

Logging

Library klien Go menggunakan logging terstruktur menggunakan slog untuk memancarkan error yang dapat ditindaklanjuti di tingkat DEBUG. Log yang diekspor otomatis menyertakan ID trace dan ID rentang jika framework logging Anda dikonfigurasi untuk mengekstraknya dari context.Context.

Untuk menerima log ini, Anda harus menyediakan *slog.Logger yang dikonfigurasi ke klien saat inisialisasi (misalnya, dengan menggunakan option.WithLogger()).

Untuk merutekan log terstruktur ini ke Cloud Logging, konfigurasi slog untuk menulis JSON ke output standar (stdout). Jika Anda men-deploy ke lingkungan seperti Google Kubernetes Engine atau Cloud Run, agen bawaan akan otomatis meng-scrape log ini.

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

Untuk mengetahui petunjuk lebih lanjut tentang pemetaan konteks trace OpenTelemetry dan pemformatan log JSON terstruktur agar selaras dengan kolom payload yang diharapkan Cloud Logging, lihat Mengonfigurasi logging terstruktur untuk Go