Belajar 9router - Observability Basics

#Pendahuluan

Episode 6 menutup sisi keamanan: kalian sudah bisa memblokir request berbahaya, menegakkan quota, dan menyiapkan safe fallback. Tapi gateway yang aman tanpa visibility ibarat sistem alarm yang tidak pernah dicek — aturannya mungkin bekerja, tapi kalian tidak pernah tahu.

Episode 7 membangun mata untuk gateway kalian. Kita bahas observability dasar 9router dari tiga sisi: metrics untuk model latency, request volume, dan success rate; logging untuk merekam konteks request, route yang terpilih, dan provider diagnostics; serta tracing untuk mengikuti alur request AI dari klien sampai provider. Kalian akan memahami cara mengukur keputusan routing, bukan hanya melihatnya.

#Tiga Pilar Observability pada Routing Gateway

Observability di AI gateway sedikit berbeda dari service biasa. Ada lapisan tambahan: keputusan routing itu sendiri adalah input utama diagnosis. Kalau request lambat, penyebabnya bisa provider, bisa route policy, bisa juga model selector yang salah pilih. Maka data yang dikumpulkan harus menyimpan jejak keputusan, bukan cuma angka.

Konsep dari tiga pilar: metrics adalah agregat numerik berkala (berapa request, berapa lama, berapa sukses), logs adalah event diskret berkonteks (route X dipilih karena Y), dan tracing adalah alur terhubung lintas komponen (dari klien, ke gateway, ke provider, kembali). Ketiganya saling melengkapi: metrics menunjukkan gejala, logs memberi detail, tracing menunjukkan rantai penyebab.

#Metrics: Latency, Volume, dan Success Rate

9router mengekspos metrics standar OpenTelemetry yang bisa di-scrape Prometheus. Tiga metrik wajib pertama: latency per model, volume request, dan success rate. Tambahkan label seperti route name, provider, dan status agar bisa di-breakdown.

metrics:
  enabled: true
  endpoint: /metrics
  prefix: nine
  labels: [route, provider, model, status]
  histograms:
    - name: latency
      buckets_ms: [50, 100, 250, 500, 1000, 2500, 5000]

Dari endpoint /metrics kalian mendapat angka seperti ini:

{
  "nine_requests_total": { "value": 48213, "labels": { "route": "chat-primary", "provider": "openai", "status": "success" } },
  "nine_latency_seconds": { "value": 1.24, "labels": { "model": "gpt-4o-mini" } },
  "nine_success_rate": { "value": 0.986, "labels": { "route": "chat-primary" } }
}

Dengan label route dan provider, kalian bisa langsung menjawab pertanyaan seperti "route mana yang paling lambat?" atau "provider mana yang mulai gagal?" tanpa menebak. Untuk pengambilan berkala, tambahkan job scrape di Prometheus atau pasang exporter 9router: 9router metrics export --otel-endpoint http://localhost:4318.

#Menghubungkan ke Dashboard

Metrics mentah tidak berguna tanpa visualisasi. Job scrape di Prometheus membaca endpoint /metrics secara berkala, dan Grafana mengubah angka itu menjadi dashboard. Satu panel wajib: p95 latency per route dengan breakdown provider, ditumpuk dengan success rate dan volume request agar lonjakan volume terlihat korelasinya dengan penurunan kecepatan.

scrape_configs:
  - job_name: nine-gateway
    metrics_path: /metrics
    static_configs:
      - targets: [nine-gateway:8080]

Jangan lupa menambahkan alert dasar di atas metrics ini — misalnya success rate di bawah ambang atau p95 latency yang melonjak. Metrics yang diambil tapi tidak pernah dilihat tidak lebih baik daripada tidak ada metrics sama sekali.

#Logging Konteks Request dan Keputusan Route

Log di 9router berbentuk JSON structured — bukan teks bebas — supaya bisa difilter dan diagregasi. Setiap entry log membawa konteks request lengkap: request ID, route yang terpilih, skor intent, provider target, durasi, dan hasil policy. Inilah yang membedakan logging gateway AI: keputusan routing ikut terekam sebagai data.

{
  "ts": "2026-08-03T10:21:07Z",
  "request_id": "req_8f3kq2",
  "tenant": "acme-corp",
  "intent": "chat",
  "confidence": 0.94,
  "route": "chat-primary",
  "policy": ["privacy-first", "api-guard"],
  "target": "openai/gpt-4o-mini",
  "status": "success",
  "duration_ms": 812
}

Perhatikan field policy: log ini merekam policy mana yang dievaluasi. Saat request tiba-tiba berubah arah, kalian bisa menelusuri "kenapa" lewat log, bukan cuma "apa yang terjadi". Untuk membaca log secara real-time gunakan 9router logs --follow --filter route=chat-primary, dan untuk rentang waktu tertentu 9router logs --since 2h --query status=error.

#Tracing Alur Request AI End-to-End

Tracing menghubungkan semua tahapan dalam satu request: klien, gateway, policy evaluation, model selector, provider, tool invocation, hingga respons. Di 9router, setiap tahapan adalah span di dalam satu trace, dan seluruhnya dirangkai lewat request ID serta header traceparent.

tracing:
  enabled: true
  exporter: otlp
  endpoint: http://collector:4317
  service_name: nine-gateway
  span_attributes: [route, intent, model, provider]

Dengan OTLP collector, trace bisa dikirim ke Jaeger, Tempo, atau platform observability apa pun. Yang menarik dari tracing AI: span untuk provider call bisa menyertakan atribut seperti jumlah token input dan output, model yang dipakai, dan waktu tunggu antrean provider. Ini memungkinkan breakdown "dari 2 detik total, 1.2 detik ternyata di provider call".

Untuk request yang berjalan lintas komponen, konteks trace bisa diteruskan dari klien: kirim header traceparent ke gateway dan 9router akan menyambungkannya ke span internal sehingga seluruh alur terlihat sebagai satu trace utuh.

#Penutup

Observability dasar 9router memungkinkan kalian melihat keputusan routing sebagai data: metrics memberi angka agregat per route, provider, dan model; structured logs merekam konteks request beserta keputusan policy; tracing merangkai semua tahapan dalam satu alur end-to-end. Dengan tiga pilar ini, insiden tidak lagi menjadi teka-teki.

Inti yang harus dibawa pulang:

• Metrics wajib pertama: model latency, request volume, dan success rate, dengan label route dan provider.
• Log structured JSON harus menyertakan request ID, intent, route terpilih, dan policy yang dievaluasi.
• Jangan pernah menulis PII payload percakapan mentah ke log.
• Tracing lintas komponen memakai OpenTelemetry dengan OTLP, dan atribut span membawa konteks AI seperti token usage.
• Teruskan header traceparent dari klien supaya seluruh alur request terlihat sebagai satu trace.

Di episode 8 kita mulai bermain dengan pola yang lebih berani: Advanced Routing Patterns — traffic splitting, canary routes, shadowing, A/B testing, hingga dynamic routing berbasis sinyal runtime. Sampai jumpa!