Menambahkan rekaman aktivitas dan metrik kustom ke aplikasi Anda dengan OpenTelemetry

Dengan menambahkan instrumentasi OpenTelemetry kustom ke kode aplikasi, Anda dapat mencatat span trace kustom dan metrik yang mengukur perilaku khusus aplikasi di luar yang dikumpulkan oleh library framework standar. Anda dapat menerapkan konsep dalam dokumen ini ke aplikasi yang ditulis dalam bahasa apa pun yang didukung oleh OpenTelemetry; untuk informasi latar belakang, lihat Kemampuan observasi untuk developer aplikasi dan Memilih pendekatan instrumentasi.

Contoh dalam dokumen ini menggunakan aplikasi contoh Go yang dijelaskan dalam Contoh instrumentasi Go, yang tersedia di GitHub.

Sebelum memulai

Aktifkan Cloud Logging, Cloud Monitoring, dan Cloud Trace API, jika ada yang 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.

Aktifkan API

Membuat trace kustom

Untuk membuat trace kustom dari aplikasi, tambahkan kode instrumentasi yang membuat span OpenTelemetry. Di OpenTelemetry, span adalah elemen penyusun untuk trace.

Untuk membuat span, lakukan hal berikut:

  1. Ubah aplikasi Anda untuk mendapatkan Tracer OpenTelemetry. Di OpenTelemetry, tracer adalah pembuat span. Anda dapat memperoleh tracer seperti yang ditunjukkan dalam kode berikut. Untuk melihat contoh lengkap, di toolbar contoh, pilih logo GitHub.

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    Nama tracer, yang diwakili oleh scopeName, mengidentifikasi cakupan instrumentasi trace yang dihasilkan.

  2. Gunakan instance tracer untuk membuat span. Dalam contoh kode berikut, fungsi computeSubrequests menghasilkan span setiap kali dipanggil:

    func computeSubrequests(r *http.Request, subRequests int) error {
	// Add custom span representing the work done for the subrequests
	ctx, span := tracer.Start(r.Context(), "subrequests")
	defer span.End()

	// Make specified number of http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(ctx); err != nil {
			return err
		}
	}
	// record number of sub-requests made
	subRequestsHistogram.Record(ctx, int64(subRequests))
	return nil
}

    Dalam contoh kode sebelumnya, span yang dihasilkan dari fungsi computeSubrequests mewakili pekerjaan yang dilakukan oleh seluruh fungsi. Hal ini karena langkah pertama fungsi adalah memulai span baru menggunakan tracer.Start dan kata kunci defer sebelum span.End() memastikan bahwa span diakhiri tepat sebelum fungsi keluar.

Membuat metrik kustom

Untuk membuat metrik dari aplikasi, Anda menambahkan kode instrumentasi yang mencatat pengukuran yang dilakukan selama eksekusi aplikasi.

Untuk membuat metrik, lakukan tindakan berikut:

  1. Ubah aplikasi Anda untuk mendapatkan Meter OpenTelemetry. Di OpenTelemetry, meter menyediakan akses ke instrumen metrik untuk mencatat metrik. Anda dapat memperoleh meteran seperti yang ditunjukkan dalam kode berikut:

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    Nama meter, yang diwakili oleh scopeName, mengidentifikasi cakupan instrumentasi dari metrik yang dihasilkan.

  2. Gunakan instance meter untuk membuat instrumen yang dapat mencatat metrik. Misalnya, kode berikut menggunakan meter untuk membuat Histogram OpenTelemetry:

    sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
	metric.WithUnit("s"))
if err != nil {
	panic(err)
}

    Kode sebelumnya menghasilkan histogram bernama sleepHistogram.

  3. Gunakan instance sleepHistogram untuk mencatat waktu tidur, yang ditentukan saat fungsi randomSleep dipanggil:

    func randomSleep(r *http.Request) time.Duration {
	// simulate the work by sleeping 100 to 200 ms
	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
	time.Sleep(sleepTime)

	hostValue := attribute.String("host.value", r.Host)
	// custom histogram metric to record time slept in seconds
	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
	return sleepTime
}

    Metrik yang dicatat dari instrumen ini diekspor dari aplikasi Anda berdasarkan konfigurasi pengekspor OpenTelemetry.

Langkah berikutnya