Membuat trace dan metrik dengan Go

Dokumen ini menjelaskan cara memodifikasi aplikasi Go untuk mengumpulkan data pelacakan dan metrik menggunakan framework OpenTelemetry open source, dan cara menulis log JSON terstruktur ke standard out. Dokumen ini juga memberikan informasi tentang aplikasi contoh yang dapat Anda instal dan jalankan. Aplikasi dikonfigurasi untuk menghasilkan metrik, trace, dan log.

Tentang konteks

Context OpenTelemetry adalah mekanisme untuk membawa nilai cakupan eksekusi di seluruh API dalam suatu proses. Penggunaan konteks yang penting adalah membawa span aktif saat ini sehingga dapat diubah, atau dirujuk sebagai induk dari span baru saat dibuat. Ringkasnya:

• Context mengacu pada mekanisme untuk menerapkan nilai cakupan eksekusi, termasuk span aktif saat ini, di seluruh API dalam suatu proses.

• Konteks Span adalah objek yang tidak dapat diubah pada setiap span yang mencakup ID rekaman aktivitas, ID span, serta flag dan status untuk rekaman aktivitas.

• Propagasi adalah mekanisme yang memindahkan konteks antara layanan dan proses.

context.Context library standar Go juga membawa nilai yang dicakup di seluruh batas API. Biasanya, fungsi pengendali di server menerima Context yang masuk dan meneruskannya melalui rantai panggilan ke klien mana pun yang membuat permintaan keluar.

Library standar Go context.Context digunakan sebagai implementasi Konteks OpenTelemetry di Go.

Sebelum memulai

Aktifkan API Cloud Logging API, Cloud Monitoring API, and Cloud Trace API.

Mengaktifkan API

Melengkapi aplikasi untuk mengumpulkan trace, metrik, dan log

Untuk melengkapi aplikasi Anda guna mengumpulkan data pelacakan dan metrik, serta untuk menulis JSON terstruktur ke standard out, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dari dokumen ini:

1. Mengonfigurasi fungsi utama
2. Mengonfigurasi OpenTelemetry
3. Mengonfigurasi logging terstruktur
4. Menambahkan instrumentasi ke server HTTP
5. Menautkan span trace dengan log dan metrik
6. Menambahkan instrumentasi ke klien HTTP
7. Menulis log terstruktur

Mengonfigurasi fungsi utama

Untuk mengonfigurasi aplikasi agar menulis log terstruktur serta mengumpulkan metrik dan rekaman aktivitas menggunakan OpenTelemetry, perbarui fungsi main untuk mengonfigurasi paket logging terstruktur Go, slog, dan untuk mengonfigurasi OpenTelemetry.

Contoh kode berikut mengilustrasikan fungsi main yang memanggil dua fungsi helper, setupLogging() dan setupOpenTelemetry(). Fungsi helper ini mengonfigurasi paket logging dan OpenTelemetry:

func main() {
	ctx := context.Background()

	// Setup logging
	setupLogging()

	// Setup metrics, tracing, and context propagation
	shutdown, err := setupOpenTelemetry(ctx)
	if err != nil {
		slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err))
		os.Exit(1)
	}

	// Run the http server, and shutdown and flush telemetry after it exits.
	slog.InfoContext(ctx, "server starting...")
	if err = errors.Join(runServer(), shutdown(ctx)); err != nil {
		slog.ErrorContext(ctx, "server exited with error", slog.Any("error", err))
		os.Exit(1)
	}
}

Setelah mengonfigurasi paket logging, untuk menautkan log ke data rekaman aktivitas, Anda harus meneruskan Context Go ke logger. Untuk mengetahui informasi selengkapnya, lihat bagian Menulis log terstruktur dalam dokumen ini.

Konfigurasi OpenTelemetry

Untuk mengumpulkan dan mengekspor trace dan metrik menggunakan protokol OTLP, konfigurasikan instance TracerProvider dan MeterProvider global. Contoh kode berikut mengilustrasikan fungsi setupOpenTelemetry, yang dipanggil dari fungsi main:

func setupOpenTelemetry(ctx context.Context) (shutdown func(context.Context) error, err error) {
	var shutdownFuncs []func(context.Context) error

	// shutdown combines shutdown functions from multiple OpenTelemetry
	// components into a single function.
	shutdown = func(ctx context.Context) error {
		var err error
		for _, fn := range shutdownFuncs {
			err = errors.Join(err, fn(ctx))
		}
		shutdownFuncs = nil
		return err
	}

	// Configure Context Propagation to use the default W3C traceparent format
	otel.SetTextMapPropagator(autoprop.NewTextMapPropagator())

	// Configure Trace Export to send spans as OTLP
	texporter, err := autoexport.NewSpanExporter(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	tp := trace.NewTracerProvider(trace.WithBatcher(texporter))
	shutdownFuncs = append(shutdownFuncs, tp.Shutdown)
	otel.SetTracerProvider(tp)

	// Configure Metric Export to send metrics as OTLP
	mreader, err := autoexport.NewMetricReader(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	mp := metric.NewMeterProvider(
		metric.WithReader(mreader),
	)
	shutdownFuncs = append(shutdownFuncs, mp.Shutdown)
	otel.SetMeterProvider(mp)

	return shutdown, nil
}

Contoh kode sebelumnya mengonfigurasi TextMapPropagator global untuk menggunakan format Konteks Rekaman Aktivitas W3C untuk menyebarkan konteks rekaman aktivitas. Konfigurasi ini memastikan bahwa span memiliki hubungan induk-turunan yang benar di dalam rekaman aktivitas.

Untuk memastikan semua telemetri yang tertunda dihapus dan koneksi ditutup dengan baik, fungsi setupOpenTelemetry menampilkan fungsi bernama shutdown, yang melakukan tindakan tersebut.

Mengonfigurasi logging terstruktur

Untuk menyertakan informasi rekaman aktivitas sebagai bagian dari log berformat JSON yang ditulis ke output standar, konfigurasikan paket logging terstruktur Go, slog. Contoh kode berikut mengilustrasikan fungsi setupLogging, yang dipanggil dari fungsi main:

func setupLogging() {
	// Use json as our base logging format.
	jsonHandler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: replacer})
	// Add span context attributes when Context is passed to logging calls.
	instrumentedHandler := handlerWithSpanContext(jsonHandler)
	// Set this handler as the global slog handler.
	slog.SetDefault(slog.New(instrumentedHandler))
}

Kode sebelumnya memanggil fungsi handlerWithSpanContext, yang mengekstrak informasi dari instance Context dan menambahkan informasi tersebut sebagai atribut ke log. Atribut ini kemudian dapat digunakan untuk mengkorelasikan log dengan trace:

• logging.googleapis.com/trace: Nama resource trace yang terkait dengan entri log.
• logging.googleapis.com/spanId: ID span dengan pelacakan yang dikaitkan dengan entri log.
• logging.googleapis.com/trace_sampled: Nilai kolom ini harus true atau false.

Untuk mengetahui informasi selengkapnya tentang kolom ini, lihat struktur LogEntry.

func handlerWithSpanContext(handler slog.Handler) *spanContextLogHandler {
	return &spanContextLogHandler{Handler: handler}
}

// spanContextLogHandler is an slog.Handler which adds attributes from the
// span context.
type spanContextLogHandler struct {
	slog.Handler
}

// Handle overrides slog.Handler's Handle method. This adds attributes from the
// span context to the slog.Record.
func (t *spanContextLogHandler) Handle(ctx context.Context, record slog.Record) error {
	// Get the SpanContext from the golang Context.
	if s := trace.SpanContextFromContext(ctx); s.IsValid() {
		// Add trace context attributes following Cloud Logging structured log format described
		// in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
		record.AddAttrs(
			slog.Any("logging.googleapis.com/trace", s.TraceID()),
		)
		record.AddAttrs(
			slog.Any("logging.googleapis.com/spanId", s.SpanID()),
		)
		record.AddAttrs(
			slog.Bool("logging.googleapis.com/trace_sampled", s.TraceFlags().IsSampled()),
		)
	}
	return t.Handler.Handle(ctx, record)
}

func replacer(groups []string, a slog.Attr) slog.Attr {
	// Rename attribute keys to match Cloud Logging structured log format
	switch a.Key {
	case slog.LevelKey:
		a.Key = "severity"
		// Map slog.Level string values to Cloud Logging LogSeverity
		// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
		if level := a.Value.Any().(slog.Level); level == slog.LevelWarn {
			a.Value = slog.StringValue("WARNING")
		}
	case slog.TimeKey:
		a.Key = "timestamp"
	case slog.MessageKey:
		a.Key = "message"
	}
	return a
}

Menambahkan instrumentasi ke server HTTP

Untuk menambahkan instrumentasi trace dan metrik ke permintaan yang ditangani oleh server HTTP, gunakan OpenTelemetry. Contoh berikut menggunakan pengendali otelhttp untuk menyebarkan konteks, dan untuk instrumentasi rekaman aktivitas dan metrik:

func runServer() error {
	handleHTTP("/single", handleSingle)
	handleHTTP("/multi", handleMulti)

	return http.ListenAndServe(":8080", nil)
}

// handleHTTP handles the http HandlerFunc on the specified route, and uses
// otelhttp for context propagation, trace instrumentation, and metric
// instrumentation.
func handleHTTP(route string, handleFn http.HandlerFunc) {
	instrumentedHandler := otelhttp.NewHandler(otelhttp.WithRouteTag(route, handleFn), route)

	http.Handle(route, instrumentedHandler)
}

Dalam kode sebelumnya, pengendali otelhttp menggunakan instance TracerProvider, MeterProvider, dan TextMapPropagator global. Fungsi setupOpenTelemetry mengonfigurasi instance ini.

Menautkan span rekaman aktivitas dengan log dan metrik

Untuk menautkan span server dan klien, serta mengaitkan metrik dan log, teruskan instance Go Context ke permintaan HTTP dan saat Anda menulis log. Contoh berikut mengilustrasikan pengendali rute yang mengekstrak instance Go Context dan meneruskan instance tersebut ke logger dan ke fungsi callSingle, yang membuat permintaan HTTP keluar:

func handleMulti(w http.ResponseWriter, r *http.Request) {
	subRequests := 3 + rand.Intn(4)
	// Write a structured log with the request context, which allows the log to
	// be linked with the trace for this request.
	slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

	// Make 3-7 http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(r.Context()); err != nil {
			http.Error(w, err.Error(), http.StatusBadGateway)
			return
		}
	}

	fmt.Fprintln(w, "ok")
}

Pada kode sebelumnya, panggilan fungsi r.Context() mengambil Context Go dari permintaan HTTP.

Menambahkan instrumentasi ke klien HTTP

Untuk memasukkan konteks rekaman aktivitas ke permintaan HTTP keluar dan menambahkan instrumentasi metrik dan trace, panggil fungsi otelhttp.Get. Dalam contoh berikut, fungsi callSingle melakukan tindakan ini:

func callSingle(ctx context.Context) error {
	// otelhttp.Get makes an http GET request, just like net/http.Get.
	// In addition, it records a span, records metrics, and propagates context.
	res, err := otelhttp.Get(ctx, "http://localhost:8080/single")
	if err != nil {
		return err
	}

	return res.Body.Close()
}

Dalam kode sebelumnya, pengendali otelhttp menggunakan instance TracerProvider, MeterProvider, dan TextMapPropagator global. Fungsi setupOpenTelemetry mengonfigurasi instance ini.

Menulis log terstruktur

Untuk menulis log terstruktur yang tertaut ke rekaman aktivitas, gunakan paket logging terstruktur Go, slog, lalu teruskan instance Context Go ke logger. Instance Context Go diperlukan saat Anda ingin menautkan log ke span. Misalnya, pernyataan berikut menunjukkan cara memanggil metode InfoContext untuk slog, dan menggambarkan cara menambahkan kolom subRequests ke instance JSON:

slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Aplikasi contoh menggunakan format yang tidak bergantung pada vendor, termasuk JSON untuk log dan OTLP untuk metrik dan trace. Untuk merutekan telemetri ke Google Cloud, contoh ini menggunakan Collector OpenTelemetry yang dikonfigurasi dengan pengekspor Google. Generator beban di aplikasi mengeluarkan permintaan ke rute aplikasi.

Mendownload dan men-deploy aplikasi

Catatan: Sebaiknya jalankan aplikasi contoh menggunakan Cloud Shell. Namun, jika Anda ingin menjalankan aplikasi contoh secara lokal di Linux atau Mac, lewati langkah pertama dalam petunjuk berikut.

Untuk menjalankan contoh, lakukan hal berikut:

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Meng-cloning repository

   git clone https://github.com/GoogleCloudPlatform/golang-samples
   

3. Buka direktori OpenTelemetry:

   cd golang-samples/opentelemetry/instrumentation
   

4. Buat dan jalankan contoh:

   docker compose up --abort-on-container-exit
   

   Jika Anda tidak menjalankan Cloud Shell, jalankan aplikasi dengan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke file kredensial. Kredensial Default Aplikasi menyediakan file kredensial di $HOME/.config/gcloud/application_default_credentials.json.

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

Melihat metrik Anda

Instrumentasi OpenTelemetry di aplikasi contoh menghasilkan metrik Prometheus yang dapat Anda tampilkan menggunakan Metrics Explorer:

• Prometheus/http_server_duration/histogram mencatat durasi permintaan server dan menyimpan hasilnya dalam histogram.

• Prometheus/http_server_request_content_length_total/counter mencatat durasi konten permintaan untuk rute HTTP /multi dan /single. Pengukuran untuk metrik ini bersifat kumulatif, yang berarti setiap nilai mewakili total karena pengumpulan nilai dimulai.

• Prometheus/http_server_response_content_length_total/counter mencatat panjang konten respons untuk rute HTTP /multi dan /single. Pengukuran untuk metrik ini bersifat kumulatif.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal berikut:

1. Di panel navigasi Konsol Google Cloud, pilih Monitoring, lalu pilih  Metrics Explorer:

   Buka Metrics Explorer

2. Pada elemen Metrik, luaskan menu Pilih metrik, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih jenis dan metrik resource tertentu:
   1. Di menu Active resources, pilih Prometheus Target.
   2. Di menu Active metric criteria, pilih Http.
   3. Di menu Metrik aktif, pilih metrik.
   4. Klik Terapkan.
3. Konfigurasi cara data ditampilkan.
   

   Jika pengukuran untuk metrik bersifat kumulatif, Metrics Explorer otomatis menormalisasi data yang diukur berdasarkan periode penyelarasan, sehingga diagram akan menampilkan rasio. Untuk mengetahui informasi selengkapnya, lihat Jenis, jenis, dan konversi.

   Saat nilai bilangan bulat atau ganda diukur, seperti dengan dua metrik counter, Metrics Explorer otomatis menjumlahkan semua deret waktu. Untuk melihat data rute HTTP /multi dan /single, tetapkan menu pertama entri Aggregation ke None.

   Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Memilih metrik saat menggunakan Metrics Explorer.

Melihat trace Anda

Untuk melihat data trace, lakukan langkah berikut:

1. Di panel navigasi konsol Google Cloud, pilih Trace, lalu pilih Trace explorer:

   Buka Trace explorer

2. Di diagram sebar, pilih rekaman aktivitas dengan URI /multi.

3. Pada diagram Gantt di panel Trace details, pilih span yang berlabel /multi.

   Sebuah panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Detail ini mencakup metode, kode status, jumlah byte, dan agen pengguna pemanggil.

4. Untuk melihat log yang terkait dengan rekaman aktivitas ini, pilih tab Logs & Events.

   Tab ini menunjukkan log individual. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik View Logs dan melihat log menggunakan Logs Explorer.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan penjelajah Cloud Trace, lihat Menemukan dan menjelajahi trace.

Melihat log

Dari Logs Explorer, Anda dapat memeriksa log, dan Anda juga dapat melihat rekaman aktivitas terkait, jika ada.

1. Di panel navigasi konsol Google Cloud, pilih Logging, lalu pilih Logs Explorer:

   Buka Logs Explorer

2. Temukan log dengan deskripsi handle /multi request.

   Untuk melihat detail log, luaskan entri log. Di kolom jsonPayload, ada entri berlabel subRequests. Entri ini ditambahkan oleh pernyataan dalam fungsi handleMulti.

3. Klik Traces pada entri log dengan pesan "handle /multi request", lalu pilih View trace details.

   Panel Trace details akan terbuka dan menampilkan trace yang dipilih.

Untuk mengetahui informasi selengkapnya tentang penggunaan Logs Explorer, baca Melihat log menggunakan Logs Explorer.

Langkah selanjutnya

• OpenTelemetry
• Ringkasan OTLP
• Logging terstruktur
• Memecahkan Masalah Google Cloud Managed Service for Prometheus
• Memecahkan masalah Cloud Trace