Go dan OpenTelemetry

Halaman ini ditujukan bagi developer aplikasi yang ingin mengumpulkan data Cloud Trace untuk aplikasi Go menggunakan OpenTelemetry. OpenTelemetry adalah framework instrumentasi yang tidak bergantung pada vendor yang dapat Anda gunakan untuk mengumpulkan data trace dan metrik. Untuk mengetahui informasi tentang cara menginstrumentasikan kode, lihat Instrumentasi dan kemampuan observasi.

Catatan: Informasi pada halaman ini dibatasi hanya untuk mengumpulkan data trace. Untuk contoh yang lebih lengkap, salah satu yang menggambarkan cara mengumpulkan data trace dan metrik dengan menggunakan OpenTelemetry, serta cara menulis log JSON terstruktur untuk standar, lihat Membuat trace dan metrik dengan Go.

Halaman ini akan memandu Anda melakukan langkah-langkah berikut:

• Instal paket OpenTelemetry.
• Konfigurasi aplikasi Anda untuk mengekspor span ke Cloud Trace.
• Konfigurasi platform Anda.

Untuk informasi rilis, lihat referensi berikut:

• Rilis library terbaru untuk Go

  Catatan: Beberapa library klien Google untuk Go terintegrasi dengan OpenCensus. Jika aplikasi Anda mengandalkan library klien untuk merekam aktivitas, maka jika Anda mengupdate aplikasi untuk menggunakan OpenTelemetry, Anda juga harus menggunakan OpenCensus Bridge. Untuk informasi selengkapnya, lihat Masalah #4237.

• Rilis pengekspor Cloud Trace terbaru untuk Go

Untuk konten referensi OpenTelemetry, lihat hal berikut:

• Tracer
• Span

Untuk detail terbaru tentang OpenTelemetry for Go, beserta dokumentasi dan contoh tambahan, lihat OpenTelemetry.

Sebelum memulai

1. Di panel navigasi Konsol Google Cloud, pilih APIs & Services, klik Enable APIs and Services, lalu aktifkan Cloud Trace API:

   Buka setelan Cloud Trace API

2. Jika API enabled ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

Menginstal, menginisialisasi, dan menggunakan klien

Lihat petunjuk berikut untuk melengkapi aplikasi Go Anda di Compute Engine dan Google Kubernetes Engine. Untuk contoh umum penggunaan OpenTelemetry, lihat repositori GitHub OpenTelemetry untuk Go.

Compute Engine

Instal paket OpenTelemetry:

go get go.opentelemetry.io/otel
go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

Impor paket ekspor OpenTelemetry dan Cloud Trace:

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

Buat pengekspor dan penyedia rekaman aktivitas:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Saat membuat pengekspor, Anda memberikan informasi tentang ID project Google Cloud Anda. Dalam contoh ini, ID disimpan dalam variabel lingkungan GOOGLE_CLOUD_PROJECT.

Aplikasi contoh memanggil fungsi WithBatcher untuk mengonfigurasi penyedia perekaman aktivitas agar mengirim span ke Cloud Monitoring dengan menggunakan proses latar belakang. Contoh ini juga dikonfigurasi untuk memanggil fungsi Shutdown pengekspor saat keluar dari aplikasi. Saat dijalankan, Shutdown akan mengirimkan semua span yang tertunda ke Cloud Monitoring. Konfigurasi yang ditampilkan dalam contoh adalah penerapan yang direkomendasikan untuk semua lingkungan operasi, termasuk untuk Cloud Run tempat container dapat dimatikan kapan saja.

Saat membuat instance Tracer, Anda memberinya nama. Dalam contoh, namanya adalah example.com/trace. Sebaiknya beri nama instance ini setelah komponen dilacak karena strategi ini memungkinkan Anda memiliki beberapa instance.

Saat contoh dijalankan, satu rekaman aktivitas bernama foo akan dibuat.

GKE

Tambahkan kode berikut ke Dockerfile Anda:

RUN go get go.opentelemetry.io/otel
RUN go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

Impor paket ekspor OpenTelemetry dan Cloud Trace:

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

Buat pengekspor dan penyedia rekaman aktivitas:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Saat membuat pengekspor, Anda memberikan informasi tentang ID project Google Cloud Anda. Dalam contoh ini, ID disimpan dalam variabel lingkungan GOOGLE_CLOUD_PROJECT.

Aplikasi contoh memanggil fungsi WithBatcher untuk mengonfigurasi penyedia perekaman aktivitas agar mengirim span ke Cloud Monitoring dengan menggunakan proses latar belakang. Contoh ini juga dikonfigurasi untuk memanggil fungsi Shutdown pengekspor saat keluar dari aplikasi. Saat dijalankan, Shutdown akan mengirimkan semua span yang tertunda ke Cloud Monitoring. Konfigurasi yang ditampilkan dalam contoh adalah penerapan yang direkomendasikan untuk semua lingkungan operasi, termasuk untuk Cloud Run tempat container dapat dimatikan kapan saja.

Saat membuat instance Tracer, Anda memberinya nama. Dalam contoh, namanya adalah example.com/trace. Sebaiknya beri nama instance ini setelah komponen dilacak karena strategi ini memungkinkan Anda memiliki beberapa instance.

Saat contoh dijalankan, satu rekaman aktivitas bernama foo akan dibuat.

Cara membuat span kustom

Anda dapat menambahkan informasi tambahan ke pelacakan yang dibuat sistem dengan membuat span kustom.

Untuk membuat span kustom dengan nama foo, tambahkan kode berikut ke kode sumber:

// Create custom span.
tracer := otel.GetTracerProvider().Tracer("example.com/trace")
err = func(ctx context.Context) error {
	ctx, span := tracer.Start(ctx, "foo")
	defer span.End()

	// Do some work.

	return nil
}(ctx)

Di sini, example.com/trace mengacu pada nama instance tracer.

Konfigurasi platform Anda

Anda dapat menggunakan Cloud Trace di Google Cloud dan platform lainnya.

Berjalan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda tidak perlu memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Namun, Anda harus memastikan bahwa platform Google Cloud Anda telah mengaktifkan cakupan akses Cloud Trace API.

Untuk mengetahui daftar lingkungan Google Cloud yang didukung, lihat Dukungan lingkungan.

Untuk konfigurasi berikut, setelan cakupan akses default akan mengaktifkan Cloud Trace API:

• Lingkungan fleksibel App Engine

• Lingkungan standar App Engine

• Google Kubernetes Engine (GKE)

  Catatan: Jika menggunakan Autopilot atau mengaktifkan Workload Identity untuk cluster GKE, pastikan Anda mengonfigurasi aplikasi untuk menggunakan Workload Identity.

• Compute Engine

• Cloud Run

Jika menggunakan cakupan akses kustom, Anda harus memastikan cakupan akses API Cloud Trace diaktifkan:

• Untuk mengetahui informasi cara mengonfigurasi cakupan akses untuk lingkungan Anda menggunakan Konsol Google Cloud, lihat Mengonfigurasi project Google Cloud.

• Untuk pengguna gcloud, tentukan cakupan akses menggunakan flag --scopes dan sertakan cakupan akses Cloud Trace API trace.append. Misalnya, untuk membuat cluster GKE dengan hanya Cloud Trace API yang diaktifkan, lakukan hal berikut:

  gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Berjalan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Akun layanan harus berisi peran agen Cloud Trace. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Library klien Google Cloud menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda.

Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara:

• Jalankan gcloud auth application-default login

• Tempatkan akun layanan di jalur default untuk sistem operasi Anda. Berikut ini daftar jalur default untuk Windows dan Linux:

  • Windows: %APPDATA%/gcloud/application_default_credentials.json

  • Linux: $HOME/.config/gcloud/application_default_credentials.json

• Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur ke akun layanan Anda:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Lihat pelacakan

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

Buka Trace explorer

Pemecahan masalah

Untuk mengetahui informasi tentang cara memecahkan masalah terkait Cloud Trace, buka halaman Pemecahan masalah.