Belajar OpenTelemetry - Instrumentasi: API, SDK & Auto-Instrumentation

#Pendahuluan

Setelah di episode 2 kita memahami arsitektur — API → SDK → Exporter → OTLP → Collector — episode ini masuk ke bagian yang paling sering dihadapi developer: menginstrumentasi aplikasi. Kalian akan belajar dua jalur yang berbeda filosofinya: auto-instrumentation (tanpa mengubah kode) dan manual instrumentation (mengubah kode secara eksplisit).

Mengapa harus menguasai keduanya? Auto-instrumentation memberi cakupan cepat untuk framework HTTP/database populer, sedangkan manual instrumentation memberi kontrol untuk logika bisnis yang tidak dikenali framework. Tim yang hanya memakai satu jalur hampir selalu kehilangan sebagian konteks — kombinasi keduanya adalah praktik produksi yang sehat.

#API vs SDK: Siapa Melakukan Apa

#API: Kontrak Tanpa Perilaku

API OTel adalah interface yang kalian panggil di kode: tracer.start_span(), meter.create_counter(), logger.emit(). Aturan kuncinya: API dirancang untuk bekerja meskipun SDK belum dikonfigurasi — ia menjadi no-op. Aplikasi kalian tetap berjalan normal, hanya tanpa menghasilkan telemetry.

from opentelemetry import trace
 
tracer = trace.get_tracer("payment.service")
span = tracer.start_span("charge")
span.end()

Kode di atas aman dieksekusi tanpa SDK apa pun — tidak ada crash, tidak ada overhead berarti. Inilah yang membuat API bisa "ditanam" sejak awal pengembangan.

#SDK: Implementasi yang Dapat Dikonfigurasi

SDK mewujudkan perilaku nyata: membuat TracerProvider, menempelkan Resource, membangun spans, melakukan sampling, batching, dan meneruskan ke exporter. Konfigurasi SDK dikendalikan lewat environment variable atau kode setup:

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
 
provider = TracerProvider(resource=Resource.create({SERVICE_NAME: "payment-service"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="localhost:4317")))
trace.set_tracer_provider(provider)

Membandingkan keduanya:

#Auto-Instrumentation: Telemetry Tanpa Mengubah Kode

Auto-instrumentation memanfaatkan teknik pemrograman yang bergantung bahasa untuk menyisipkan telemetry ke library framework populer:

• Python: command opentelemetry-instrument yang memakai module wrapping.
• Java: -javaagent JVM agent yang memakai bytecode instrumentation.
• Node.js: module patching untuk framework seperti Express/Fastify.
• Go: go.opentelemetry.io/contrib menawarkan middleware manual per framework (Go tanpa runtime agent, jadi berupa helper per framework).

Contoh paling cepat adalah Python. Instrumentasi framework HTTP dan klien database cukup dengan satu perintah:

opentelemetry-instrument \
  --service_name payment-service \
  --exporter_otlp_endpoint http://localhost:4317 \
  python app.py

Yang terjadi di balik layar: opentelemetry-instrument memuat semua paket opentelemetry-instrumentation-* yang terinstall — Flask, requests, psycopg, dan lain-lain — dan membungkus fungsi entry-point-nya. Setiap request HTTP otomatis menjadi root span, setiap panggilan keluar menjadi child span, dan traceparent di-inject/extract secara otomatis.

pip install opentelemetry-instrumentation-flask \
            opentelemetry-instrumentation-requests \
            opentelemetry-instrumentation-psycopg2

#Batasan Auto-Instrumentation

Auto-instrumentation brilian untuk hal yang diketahui framework — namun buta untuk logika bisnis. Ia tidak tahu maksud sebuah fungsi, tidak bisa memberi nama span yang bermakna, dan tidak menambahkan konteks bisnis seperti order.id atau customer.tier. Untuk itu kalian butuh instrumentasi manual.

#Manual Instrumentation: Kendali Penuh

Instrumentasi manual memakai API secara eksplisit untuk membungkus unit kerja dengan span:

from opentelemetry import trace
 
tracer = trace.get_tracer("payment.service")
 
def charge(order_id: str):
    with tracer.start_as_current_span("payment.charge") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("payment.method", "card")
        result = gateway.call(order_id)
        span.set_attribute("payment.amount", result.amount)
        return result

Kelebihan vs auto-instrumentation:

• Nama span bermakna — payment.charge jauh lebih informatif daripada POST /charge.
• Attributes bisnis — order.id, payment.amount langsung melekat.
• Status & error semantik — kalian bisa menandai span gagal dan merekam exception.
• Nested spans terkontrol — menentukan hierarki span sesuai logika, bukan hanya alur framework.

#Mencampur Keduanya: Pola Produksi

Praktik terbaik adalah auto untuk lapisan transport, manual untuk lapisan bisnis:

Hasilnya: trace yang otomatis lengkap secara struktural (framework), tapi kaya konteks secara semantik (bisnis). Inilah bentuk trace yang benar-benar bisa menjawab pertanyaan incident response.

#Verifikasi dengan Jaeger

Cek telemetry benar-benar mengalir ke Jaeger di http://localhost:16686 (stack episode 0). Pilih service payment-service, cari trace, dan amati hierarki span: auto-instrumentation menghasilkan span HTTP + DB, manual instrumentation menambahkan span bisnis di antaranya. Kalian akan melihat langsung bagaimana dua jalur ini saling melengkapi.

#Penutup

Pada episode 3 ini, kalian telah memahami dua jalur instrumentasi dan perbedaan API vs SDK.

Inti yang harus dibawa pulang:

• API adalah kontrak tanpa perilaku (no-op tanpa SDK); SDK adalah implementasi nyata dengan provider, resource, exporter, batching.
• Auto-instrumentation memberi cakupan cepat untuk framework HTTP/database; opentelemetry-instrument untuk Python, -javaagent untuk Java, module patching untuk Node.js.
• Manual instrumentation memberi kendali: nama span bermakna, attributes bisnis, dan status error.
• Produksi ideal: auto untuk transport, manual untuk logika bisnis.

Di episode 4 selanjutnya, kita akan membedah traces: span, context & propagation — struktur span (nama, attributes, events, status, kind), span processor, serta W3C Trace Context (traceparent/tracestate) dan baggage untuk korelasi lintas layanan. Sampai jumpa di episode 4!