Belajar Observability dengan LGTM Stack - TraceQL - Tempo Query Language

#Pendahuluan

Mencari trace berdasarkan TraceID memang berguna, tapi bagaimana mencari semua trace yang gagal di payment dalam 1 jam terakhir? Jawabannya adalah TraceQL — bahasa query Tempo yang memungkinkan pencarian trace berdasarkan atribut span dan hubungan antar span.

Episode ini membangun kemampuan TraceQL dari fondasi: seleksi span, perbedaan intrinsic field dan atribut, pola query yang paling sering dipakai, operator yang tersedia, hingga query lanjutan yang memanfaatkan struktur trace.

#TraceQL Fundamentals

#Seleksi Span

TraceQL memilih span menggunakan kurung kurawal dengan kondisi atribut:

{ span.http.status_code >= 500 }
{ resource.service.name = "checkout" }
{ span.http.route = "/api/orders" }

Query { span.http.status_code >= 500 } memilih semua span dengan status HTTP di atas 500 — pola pertama saat menyelidiki error.

#Intrinsic Fields vs Attributes

Tempo membedakan dua jenis field:

• Intrinsic fields: field bawaan span seperti name, duration, status, dan kind.
• Attributes: key-value bebas, dibedakan berdasarkan scope — span. untuk atribut span dan resource. untuk atribut resource.

{ name = "orders.process" }
{ duration > 500ms }
{ status = error }

Contoh { duration > 500ms } menunjukkan bahwa durasi bisa difilter langsung sebagai intrinsic field.

#Query Patterns

#Mencari Trace yang Umum

Beberapa pola yang paling sering dipakai di produksi:

{ resource.service.name = "payment" && status = error }
{ resource.service.name = "orders" && duration > 2s }
{ span.http.route = "/api/checkout" } && { span.http.status_code = "500" }

Query pertama mencari trace dari service payment yang gagal; query kedua mencari request lambat di service orders.

#Filter Durasi dan Error

Untuk investigasi latency dan kegagalan, kombinasikan intrinsic dan atribut:

{ resource.service.name = "checkout" } && { duration > 1s }
{ status = error } | count() > 3

Ekspresi { status = error } | count() > 3 menemukan trace dengan lebih dari tiga span error — indikasi kegagalan beruntun.

#TraceQL Operators

#Operator yang Tersedia

• Comparison operators: =, !=, >, <, >=, <=.
• Logical operators: && (dan), || (atau), ! (negasi).
• Pipeline operators: | untuk memproses hasil antar kondisi.
• Aggregate functions: count(), avg(), max(), min() pada kumpulan span.

{ resource.service.name = "checkout" && span.http.status_code = "500" }
{ resource.service.name = "payment" } && { name = "call.retry" }

Operator && di dalam satu pasang kurung menggabungkan kondisi pada span yang sama; di antara dua pasang kurung menggabungkan kondisi pada span berbeda.

#Advanced Queries

#Multi-Span dan Parent-Child

Kekuatan TraceQL muncul saat kalian menggabungkan kondisi antar span:

{ resource.service.name = "gateway" } >> { resource.service.name = "payment" }
{ resource.service.name = "orders" } > { resource.service.name = "payment" }

Operator >> memilih trace di mana span pertama adalah ancestor dari span kedua, sedangkan > memilih relasi parent-child langsung.

#Metrik dari Trace

Dengan operator {} bersarang, TraceQL bisa menghasilkan metrik deret waktu:

{ resource.service.name = "checkout" } | rate()
{ resource.service.name = "checkout" && status = error } | count()
{ resource.service.name = "payment" } | quantile_over_time(duration, .95)

Query { resource.service.name = "checkout" } | rate() menghitung jumlah trace per detik — persis pola yang dipakai dashboard RED di episode 24.

#Penutup

Di episode 15 ini kalian menguasai TraceQL: seleksi span dengan kondisi atribut, perbedaan intrinsic field dan atribut, pola query untuk mencari error dan request lambat, operator perbandingan, logika, pipeline, dan agregasi, serta query lanjutan multi-span dan metrik dari trace.

Inti yang harus dibawa pulang:

• TraceQL memilih span dengan kondisi di dalam kurung kurawal.
• Intrinsic field seperti name, duration, dan status.
• && menggabungkan kondisi, >> dan > memilih relasi span.
• Pipeline dan agregasi mengubah trace menjadi metrik.
• Mulai query dari service lalu perluas kondisi bertahap.

Di episode 16 selanjutnya kita akan membahas OpenTelemetry Collector deep dive — arsitektur receiver, processor, exporter, dan extension, mode deployment agent dan gateway, receiver populer seperti OTLP dan Prometheus, serta best practices konfigurasi. Collector menjadi titik pusat yang mengatur semua data telemetry.