Belajar Observability dengan LGTM Stack - OpenTelemetry Instrumentation for Traces

#Pendahuluan

Tempo menyediakan penyimpanan, namun trace tidak muncul tanpa instrumentasi. Di episode ini kalian belajar menghasilkan trace berkualitas dengan OpenTelemetry: mulai dari auto-instrumentation yang praktis, pembuatan span manual untuk logika khusus, sampai context propagation yang menyatukan trace lintas service.

Di akhir episode kalian akan tahu cara membuat aplikasi yang menghasilkan trace lengkap dengan nama dan atribut konsisten — bahan baku untuk query TraceQL di episode 15.

#Auto-Instrumentation

#Per Bahasa Pemrograman

Auto-instrumentation otomatis menangani framework populer tanpa mengubah kode bisnis:

• Java: opentelemetry-javaagent.jar dijalankan dengan flag -javaagent.
• Python: paket opentelemetry-instrumentation-* dan command opentelemetry-instrument.
• Node.js: @opentelemetry/instrumentation bersama auto-loader.
• .NET: package OpenTelemetry.AutoInstrumentation.
• Go: tidak ada auto-instrumentation — semuanya dilakukan manual.

pip install opentelemetry-distro opentelemetry-instrumentation-flask
opentelemetry-instrument python3 app.py

Perintah opentelemetry-instrument python3 app.py menjalankan aplikasi dengan tracing HTTP aktif tanpa menyentuh kode aplikasi.

#Manual Instrumentation

#Membuat Span

Untuk logika yang tidak tercakup auto-instrumentation, buat span secara manual:

app.py - span manual

from opentelemetry import trace
 
tracer = trace.get_tracer("orders")
 
def process(order_id):
    with tracer.start_as_current_span("orders.process") as span:
        span.set_attribute("order.id", order_id)
        result = charge(order_id)
        span.set_status(trace.Status(trace.StatusCode.OK))
        return result

Konstruksi with tracer.start_as_current_span("orders.process") memastikan span ditutup otomatis dan menjadi child dari span aktif.

#Atribut, Event, dan Exception

• Atribut: pasangan key-value yang bisa diquery, misalnya order.id.
• Event: titik waktu dalam span, cocok untuk menandai checkpoint.
• Exception: rekam error lengkap dengan stack trace.
• Span status: tandai span OK atau ERROR sesuai hasil operasi.

Merekam event dan exception

span.add_event("charge.attempt", {"attempt": 1})
try:
    charge(order_id)
except Exception as exc:
    span.record_exception(exc)
    span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc)))

Pola span.record_exception(exc) menyimpan error di dalam trace sehingga debugging di episode 21 jadi jauh lebih cepat.

#Context Propagation

#W3C Trace Context

Agar satu trace menyambung antar service, context harus diteruskan lewat header HTTP:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Header traceparent membawa versi, TraceID, SpanID, dan sampling flags. Auto-instrumentation biasanya sudah menangani injeksi dan ekstraksi context secara otomatis.

#Propagator dan Baggage

• Propagators: menentukan cara context dikirim — HTTP headers untuk web, gRPC metadata untuk RPC.
• Baggage: membawa data lintas service tanpa membuat span, misalnya user ID untuk konteks bisnis.

python3 -c "from opentelemetry import propagate; print(propagate.get_global_text_map_propagator())"

Perintah python3 -c ... menampilkan propagator global yang sedang aktif di proses Python.

#Best Practices Instrumentasi

#Penamaan dan Konvensi

• Nama span: gunakan format verb.noun seperti orders.process dan checkout.pay — bukan nama function bebas.
• Atribut: ikuti semantic conventions OTel, misalnya http.method, http.route, db.system.
• Konsistensi: nama dan atribut yang konsisten membuat query TraceQL di episode 15 tetap masuk akal.

#Error Handling dan Performa

• Tandai status span ERROR saat operasi gagal, jangan biarkan sukses.
• Batasi jumlah dan ukuran atribut untuk menekan overhead.
• Pakai sampling di trafik tinggi agar biaya tetap terkendali.

#Penutup

Di episode 14 ini kalian memahami auto-instrumentation untuk Java, Python, Node.js, dan .NET, cara membuat span manual dengan atribut, event, exception, dan status, context propagation W3C dengan propagator dan baggage, serta best practices penamaan span dan atribut.

Inti yang harus dibawa pulang:

• Go tidak punya auto-instrumentation, semua manual.
• Span dibuat dengan konteks with agar selalu tertutup.
• TraceID diteruskan lewat header traceparent W3C.
• Nama span mengikuti format verb.noun yang konsisten.
• Rekam exception dan status ERROR di dalam span.

Di episode 15 selanjutnya kita akan membahas TraceQL — bahasa query Tempo untuk mencari trace berdasarkan atribut span, hubungan antar span, operator pembanding dan logika, hingga query lanjutan dan metrik dari trace. Trace yang kalian hasilkan akan bisa dijelajahi dengan presisi.