Konteks rekaman aktivitas

Konteks trace dan propagasi konteks adalah mekanisme yang digunakan untuk meneruskan metadata antara operasi dan layanan sehingga Cloud Trace dapat menautkan setiap span menjadi trace terdistribusi end-to-end yang lengkap.

Saat aplikasi Anda menangani permintaan dan memanggil layanan hilir, aplikasi tersebut akan meneruskan ID, seperti ID trace, ID span induk, dan status pengambilan sampel, menggunakan header permintaan atau metadata. Operasi turunan menggunakan konteks ini untuk mengisi kolom berikut pada rentang baru:

  • ID Rentang: ID unik untuk operasi turunan. Jika operasi dieksekusi beberapa kali, setiap pemanggilan akan menghasilkan rentang dengan ID rentang yang berbeda.
  • ID Trace: ID unik dari keseluruhan permintaan end-to-end, yang disediakan oleh induk.
  • ID rentang induk: ID unik rentang induk yang memanggil. Kolom ini adalah null untuk rentang root.

Dengan menggunakan ID bersama ini, Cloud Trace merekonstruksi hierarki eksekusi dan mengukur latensi di semua layanan yang berpartisipasi. Konteks juga dapat mencakup informasi status tambahan, seperti apakah permintaan diambil sampelnya.

Protokol untuk penerapan konteks

Bagian berikut menjelaskan cara protokol permintaan tertentu menyebarkan konteks.

Permintaan HTTP

Untuk permintaan HTTP, propagasi konteks biasanya dilakukan melalui header HTTP seperti header traceparent dan tracestate, yang distandardisasi oleh W3C. Header traceparent berisi ID untuk mengidentifikasi permintaan secara unik. Sebaliknya, header tracestate bersifat opsional dan berisi metadata khusus vendor.

Header traceparent memiliki format berikut:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

Kolom header traceparent ditentukan sebagai berikut:

  • VERSION adalah versi header. Harus berupa 00.
  • TRACE_ID adalah nilai heksadesimal 32 karakter yang mewakili angka 128-bit.
  • PARENT_SPAN_ID adalah nilai heksadesimal 16 karakter yang mengidentifikasi rentang induk.
  • TRACE_FLAGS adalah nilai heksadesimal 2 karakter yang mengidentifikasi keputusan pengambilan sampel induk. Jika induk mengambil sampel rentang, nilainya adalah 01.

LayananGoogle Cloud yang mendukung propagasi konteks rekaman aktivitas biasanya mendukung header traceparent dan header X-Cloud-Trace-Context lama.

Jika memungkinkan, gunakan header traceparent di aplikasi Anda. Jika aplikasi hanya mendukung header X-Cloud-Trace-Context, sebaiknya Anda mengupdate aplikasi untuk mendukung dan memprioritaskan header traceparent. Aplikasi Anda dapat terus menggunakan header X-Cloud-Trace-Context sebagai solusi penggantian.

Tabel berikut merangkum beberapa perbedaan signifikan antara kedua header tersebut:

Atribut Header traceparent
 Header X-Cloud-Trace-Context
Pemisah tanda hubung (-) garis miring (/) dan titik koma (;)
Representasi
ID rentang		 Heksadesimal Desimal

Header X-Cloud-Trace-Context lama

Header X-Cloud-Trace-Context yang digunakan oleh Google Cloud mendahului spesifikasi W3C. Untuk kompatibilitas mundur, beberapa layanan Google Cloud terus menerima, membuat, dan menyebarkan header X-Cloud-Trace-Context. Namun, kemungkinan besar sistem ini juga mendukung header traceparent.

Header X-Cloud-Trace-Context memiliki format berikut:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

Kolom header ditentukan sebagai berikut:

  • TRACE_ID adalah nilai heksadesimal 32 karakter yang mewakili angka 128-bit.
  • SPAN_ID adalah representasi desimal 64-bit dari ID rentang yang tidak bertanda.
  • OPTIONS mendukung 0 (induk tidak diambil sampelnya) dan 1 (induk diambil sampelnya).

Permintaan gRPC

Untuk permintaan gRPC, propagasi konteks dilakukan menggunakan metadata gRPC, yang diimplementasikan di atas header HTTP. Aplikasi gRPC dapat menggunakan header traceparent atau kunci konteks metadata yang disebut grpc-trace-bin.

Untuk komponen yang Anda miliki, sebaiknya gunakan header traceparent.

Penerapan konteks untuk layanan Google Cloud

LayananGoogle Cloud dapat bertindak sebagai inisiator atau perantara dalam pemrosesan permintaan. Misalnya, layanan berikut diketahui berpartisipasi dalam memproses permintaan:

Dukungan untuk inisiasi dan propagasi konteks rekaman aktivitas bergantung pada Google Cloud layanan. Untuk meminta Google Cloud layanan menambahkan dukungan untuk propagasi konteks, gunakan Google Issue Tracker.

Propagasi konteks di aplikasi Anda

Beberapa library instrumentasi, seperti OpenTelemetry, dapat menyebarkan objek context yang berisi data yang diperlukan untuk pelacakan. Untuk mengetahui daftar library OpenTelemetry yang mendukung pelacakan, lihat Language APIs & SDKs.

Jika Anda mengandalkan library open source, tentukan apakah propagasi konteks tersedia dan apakah konfigurasi diperlukan. Misalnya, jika Anda menggunakan OpenTelemetry untuk menginstrumentasi aplikasi Go, aplikasi Anda harus memanggil SetTextMapPropagator, yang mengonfigurasi konteks untuk menggunakan format traceparent W3C. Untuk contoh, lihat Contoh instrumentasi Go.

Jika tidak ada library instrumentasi yang sesuai, Anda harus memastikan bahwa aplikasi Anda menyebarkan konteks rekaman aktivitas ke operasi turunan.

Langkah berikutnya