Contoh instrumentasi Go

Anda dapat melengkapi aplikasi Go untuk mengumpulkan data trace dan metrik dengan SDK OpenTelemetry dan kolektor OpenTelemetry, serta untuk menulis log JSON terstruktur yang berkorelasi ke output standar menggunakan paket slog Go. Untuk bereksperimen dengan instrumentasi ini, Anda dapat mendownload dan menjalankan aplikasi Go contoh, yang menghasilkan data log, metrik, dan trace, serta mengekspornya ke projectGoogle Cloud Anda.

Tentang pendekatan instrumentasi

Saat menggunakan kolektor OpenTelemetry, Anda menginstrumentasi aplikasi dengan SDK dan pengekspor dalam proses OTLP SDK. Instrumentasi ini bersifat netral terhadap vendor. Anda juga men-deploy kolektor OpenTelemetry yang menerima telemetri dari pengekspor dalam proses, lalu mengekspor telemetri tersebut ke project Google Cloud Anda. Untuk mempelajari lebih lanjut kolektor, lihat Kolektor OpenTelemetry Buatan Google.

Sebaiknya gunakan kolektor OpenTelemetry untuk mengekspor data telemetri Anda jika lingkungan Anda mendukung penggunaan kolektor. Untuk beberapa lingkungan, Anda harus menggunakan pengekspor dalam proses yang langsung mengirim data ke projectGoogle Cloud Anda. Untuk mempelajari instrumentasi dalam proses, lihat Bermigrasi dari pengekspor Trace ke endpoint OTLP.

Untuk mempelajari instrumentasi lebih lanjut, lihat dokumen berikut:

Tentang konteks

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

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

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

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

context.Context library standar Go juga membawa nilai tercakup 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

  1. Instal Google Cloud CLI.

  2. Konfigurasi gcloud CLI agar menggunakan identitas gabungan Anda.

    Untuk mengetahui informasi selengkapnya, lihat Login ke gcloud CLI dengan identitas gabungan Anda.

  3. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

    gcloud init
  4. Buat atau pilih project Google Cloud .

    Peran yang diperlukan untuk memilih atau membuat project

    • Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.
    • Buat project Google Cloud :

      gcloud projects create PROJECT_ID

      Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

    • Pilih project Google Cloud yang Anda buat:

      gcloud config set project PROJECT_ID

      Ganti PROJECT_ID dengan nama project Google Cloud Anda.

  5. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  6. Aktifkan Cloud Logging, Cloud Monitoring, Cloud Trace, dan Telemetry API, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com
  7. Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan trace, minta administrator untuk memberi Anda peran IAM berikut:

    Izin ini sudah cukup jika Anda menjalankan contoh di Cloud Shell, di resource Google Cloud , atau di lingkungan pengembangan lokal. Untuk mempelajari cara mengonfigurasi project kuota, lihat Menetapkan project kuota.

    Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan trace, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

    Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

    Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Melengkapi aplikasi Anda untuk mengumpulkan trace, metrik, dan log

Untuk melengkapi aplikasi Anda agar dapat mengumpulkan data trace dan metrik serta menulis log JSON terstruktur ke output standar, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian berikutnya dalam 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 dan mengumpulkan metrik serta data trace 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 bantuan, setupLogging() dan setupOpenTelemetry(). Fungsi bantuan ini mengonfigurasi paket logging dan OpenTelemetry.

Untuk melihat contoh lengkap, di toolbar contoh, pilih logo GitHub.

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 trace, Anda harus meneruskan Context Go ke logger. Untuk mengetahui informasi selengkapnya, lihat bagian Menulis log terstruktur dalam dokumen ini.

Mengonfigurasi 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 W3C Trace Context untuk menyebarkan konteks trace. Konfigurasi ini memastikan bahwa span memiliki hubungan induk-turunan yang benar dalam trace.

Untuk memastikan bahwa 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 trace 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 menghubungkan log dengan trace:

  • logging.googleapis.com/trace: Nama resource trace yang terkait dengan entri log.
  • logging.googleapis.com/spanId: ID span dalam trace yang terkait dengan entri log.
  • logging.googleapis.com/trace_sampled: Nilai kolom ini harus berupa 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 a 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 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 mengumpulkan data trace 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 trace dengan log dan metrik

Untuk menautkan span server dan klien serta mengaitkan metrik dan log, teruskan instance Context Go ke permintaan HTTP dan ke logger. Contoh berikut mengilustrasikan pengendali rute yang mengekstrak instance Context Go, lalu 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))

	err := computeSubrequests(r, subRequests)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadGateway)
		return
	}

	fmt.Fprintln(w, "ok")
}

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

Menambahkan instrumentasi ke klien HTTP

Untuk memasukkan konteks trace ke dalam permintaan HTTP keluar dan menambahkan instrumentasi trace dan metrik, konfigurasikan http.Client dengan otelhttp.NewTransport dan teruskan konteks permintaan dengan memanggil http.NewRequestWithContext. 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, transportasi otelhttp menggunakan instance TracerProvider, MeterProvider, dan TextMapPropagator global. Fungsi setupOpenTelemetry mengonfigurasi instance ini.

Menulis log terstruktur

Untuk menulis log terstruktur yang ditautkan ke trace, gunakan paket logging terstruktur Go, slog, dan 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 mengilustrasikan 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

Instrumentasi dalam aplikasi contoh menggunakan format yang tidak bergantung pada vendor, seperti JSON untuk data log dan OTLP untuk data metrik dan trace. Collector OpenTelemetry mengirimkan data log, metrik, dan trace ke project Anda menggunakan Telemetry API, yang menggunakan OTLP. Generator beban di aplikasi mengeluarkan permintaan ke rute aplikasi.

Mendownload dan men-deploy aplikasi

Untuk menjalankan contoh, lakukan hal berikut:

  1. Di konsol Google Cloud , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

    Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt 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 pada sesi.

  2. Buat clone repositori:

    git clone https://github.com/GoogleCloudPlatform/golang-samples
    
  3. Buka direktori OpenTelemetry:

    cd golang-samples/opentelemetry/instrumentation
    
  4. Bangun dan jalankan contoh:

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

    Jika Anda tidak menjalankannya di 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 lihat menggunakan Metrics Explorer:

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

  • Prometheus/http_client_duration_milliseconds/histogram mencatat durasi permintaan klien dan menyimpan hasilnya dalam histogram.

  • Prometheus/http_server_response_size_bytes_total/counter mencatat panjang ukuran respons untuk rute HTTP /multi dan /single. Pengukuran untuk metrik ini bersifat kumulatif, yang berarti setiap nilai mewakili total sejak pengumpulan nilai dimulai.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal berikut:
  1. Di konsol Google Cloud , buka halaman  Metrics explorer:

    Buka Metrics explorer

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host App Hub atau project pengelolaan folder khusus aplikasi.
  3. 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 categories, pilih Http.
    3. Di menu Active metrics, pilih metrik.
    4. Klik Terapkan.
  4. Untuk menambahkan filter, yang menghapus deret waktu dari hasil kueri, gunakan elemen Filter.

  5. Konfigurasi cara data dilihat.

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

    Saat nilai bilangan bulat atau ganda diukur, seperti dengan dua metrik counter, Metrics Explorer akan 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

Mungkin perlu waktu beberapa menit sebelum data trace Anda tersedia. Misalnya, saat data trace diterima oleh project Anda, Google Cloud Observability mungkin perlu membuat database untuk menyimpan data tersebut. Pembuatan database dapat memerlukan waktu beberapa menit dan selama periode tersebut, tidak ada data trace yang tersedia untuk dilihat.

Untuk melihat data trace, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Trace explorer:

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

  2. Di bagian tabel halaman, pilih baris dengan nama span /multi.
  3. Di diagram Gantt pada panel Trace details, pilih span berlabel /multi.

    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 trace ini, pilih tab Logs & Events.

    Tab ini menampilkan setiap log. 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 halaman Trace Explorer, lihat Menemukan dan menjelajahi trace.

Melihat log

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

  1. Di konsol Google Cloud , buka halaman Logs Explorer:

    Buka Logs Explorer

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  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.

    Data log Anda mungkin tersedia beberapa menit sebelum data trace Anda tersedia. Jika Anda mengalami error saat melihat data trace, baik dengan menelusuri trace berdasarkan ID atau dengan mengikuti langkah-langkah dalam tugas ini, tunggu satu atau dua menit, lalu coba lagi tindakan tersebut.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Logs Explorer, lihat Melihat log menggunakan Logs Explorer.

Langkah berikutnya