Halaman ini diterjemahkan oleh Cloud Translation API.

Contoh instrumentasi Go

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

Untuk mempelajari lebih lanjut instrumentasi, 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 rentang aktif saat ini sehingga dapat diubah, atau dirujuk sebagai induk dari rentang baru saat dibuat. Ringkasnya:

Konteks mengacu pada mekanisme untuk menyebarkan nilai cakupan eksekusi, termasuk rentang aktif saat ini, di seluruh API dalam suatu proses.
Span Context adalah objek yang tidak dapat diubah di setiap rentang yang mencakup ID aktivitas, ID rentang, serta flag dan status untuk aktivitas.
Penerapan adalah mekanisme yang memindahkan konteks antar-layanan dan proses.

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

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

Sebelum memulai

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Jika Anda menjalankan sampel di Cloud Shell, di Google Cloud resource, atau di lingkungan pengembangan lokal, izin yang tercantum di bagian ini sudah cukup. Untuk aplikasi produksi, biasanya akun layanan menyediakan kredensial untuk menulis data log, metrik, dan trace.

Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan rekaman aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Cloud Trace Agent (roles/cloudtrace.agent)
Untuk mendapatkan izin yang Anda perlukan guna melihat data log, metrik, dan rekaman aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:
- Logs Viewer (roles/logging.viewer)
- Monitoring Viewer (roles/monitoring.viewer)
- Cloud Trace User (roles/cloudtrace.user)
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran kustom atau peran yang telah ditentukan lainnya.

Melengkapi aplikasi Anda untuk mengumpulkan rekaman aktivitas, metrik, dan log

Untuk menginstrumentasi aplikasi Anda guna mengumpulkan data rekaman aktivitas dan metrik, serta menulis JSON terstruktur ke output standar, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dalam dokumen ini:
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 menggambarkan fungsi main yang memanggil dua fungsi pembantu, setupLogging() dan setupOpenTelemetry(). Fungsi pembantu ini mengonfigurasi paket logging dan OpenTelemetry.

Untuk melihat contoh lengkapnya, klik Lainnya, lalu pilih Lihat di 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 rekaman aktivitas, 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, konfigurasi 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 Trace W3C untuk mempropagasi konteks trace. Konfigurasi ini memastikan bahwa rentang memiliki hubungan induk-turunan yang benar dalam rekaman aktivitas.

Untuk memastikan semua telemetri yang tertunda dibersihkan 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, konfigurasi 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 mengorelasikan log dengan rekaman aktivitas:
- logging.googleapis.com/trace: Nama resource rekaman aktivitas yang terkait dengan entri log.
- logging.googleapis.com/spanId: ID rentang dengan rekaman aktivitas yang terkait 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 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 handler otelhttp untuk menyebarkan konteks, serta untuk instrumentasi metrik dan rekaman aktivitas:
```
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 rentang rekaman aktivitas dengan log dan metrik

Untuk menautkan rentang server dan klien, serta mengaitkan metrik dan log, teruskan instance Context Go ke permintaan HTTP dan saat Anda menulis log. Contoh berikut menggambarkan pengendali rute yang mengekstrak instance Context Go 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))

	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 menyuntikkan konteks rekaman aktivitas ke permintaan HTTP keluar dan menambahkan instrumentasi rekaman aktivitas dan metrik, panggil fungsi otelhttp.Get. Pada 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 ditautkan ke rekaman aktivitas, gunakan paket logging terstruktur Go, slog, dan teruskan instance Context Go ke logger. Instance Go Context diperlukan saat Anda ingin menautkan log ke rentang. 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

Aplikasi contoh menggunakan format netral vendor, termasuk JSON untuk log dan OTLP untuk metrik dan rekaman aktivitas. Untuk merutekan telemetri ke Google Cloud, contoh ini menggunakan Collector OpenTelemetry yang dikonfigurasi dengan eksportir 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. In the Google Cloud console, activate Cloud Shell.
  
  Activate Cloud Shell
  
  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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 sampel:
```
docker compose up --abort-on-container-exit
```
  Jika Anda tidak menjalankan 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
```

Contoh instrumentasi Go

Tentang konteks

Sebelum memulai

Melengkapi aplikasi Anda untuk mengumpulkan rekaman aktivitas, metrik, dan log

Mengonfigurasi fungsi utama

Mengonfigurasi OpenTelemetry

Mengonfigurasi logging terstruktur

Menambahkan instrumentasi ke server HTTP

Menautkan rentang rekaman aktivitas dengan log dan metrik

Menambahkan instrumentasi ke klien HTTP

Menulis log terstruktur

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Mendownload dan men-deploy aplikasi

Melihat metrik Anda

Melihat trace Anda

Melihat log

Langkah berikutnya

Contoh instrumentasi Go Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Tentang konteks

Sebelum memulai

Melengkapi aplikasi Anda untuk mengumpulkan rekaman aktivitas, metrik, dan log

Mengonfigurasi fungsi utama

Mengonfigurasi OpenTelemetry

Mengonfigurasi logging terstruktur

Menambahkan instrumentasi ke server HTTP

Menautkan rentang rekaman aktivitas dengan log dan metrik

Menambahkan instrumentasi ke klien HTTP

Menulis log terstruktur

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Mendownload dan men-deploy aplikasi

Melihat metrik Anda

Melihat trace Anda

Melihat log

Langkah berikutnya

Contoh instrumentasi Go