Belajar OpenTelemetry - Metrics: Tipe, Instruments & Export

#Pendahuluan

Setelah episode 4 membedah traces, kali ini giliran metrics — sinyal yang paling sering dipakai untuk alerting dan SLO. Traces menjawab "kenapa lambat?", metrics menjawab "berapa?" dan "kapan?" — dan tanpa metrics yang baik, alerting kalian menembak dalam gelap.

Episode ini membahas dua lapis: instrument (cara mengukur di kode) dan export (cara backend menerima angka). Kesalahan umum di lapisan ini menghasilkan dashboard dengan data yang menyesatkan — misalnya counter yang di-reset saat restart aplikasi dan membuat grafik turun drastis.

#Metric Instruments: Alat Ukur di Kode

OTel mendefinisikan instrumen berdasarkan pola perubahan nilai dan cara pengukuran (sinkron vs asinkron).

#Sinkron: Diukur Saat Kejadian

Dipanggil langsung di kode saat peristiwa terjadi.

• Counter — hanya bisa bertambah (monotonik). Cocok untuk: jumlah request, total byte, jumlah error.

from opentelemetry import metrics
 
meter = metrics.get_meter("payment.service")
requests = meter.create_counter("http.server.request.count",
    description="Jumlah request masuk")
 
def on_request():
    requests.add(1, {"http.response.status_code": "200"})

• UpDownCounter — bisa naik dan turun. Cocok untuk: jumlah koneksi aktif, antrean pending.

connections = meter.create_up_down_counter("db.connections.active")
connections.add(1)   # koneksi dibuka
connections.add(-1)  # koneksi ditutup

• Histogram — mencatat distribusi nilai. Cocok untuk: latensi, ukuran payload. SDK mengelompokkan nilai ke bucket yang bisa dikonfigurasi, menghasilkan aggregasi seperti p95, p99.

latency = meter.create_histogram("http.server.request.duration",
    unit="s", description="Durasi request HTTP")
 
def on_request(duration_s: float):
    latency.record(duration_s, {"http.route": "/checkout"})

#Asinkron (Observable): Diukur Sesuai Jadwal

Diukur SDK secara berkala dengan memanggil callback — cocok untuk nilai yang tidak punya event alami, seperti penggunaan memori atau jumlah goroutine. Variasinya: ObservableCounter, ObservableUpDownCounter, ObservableGauge.

• Gauge (via create_observable_gauge) — nilai snapshot yang bisa naik/turun, diukur saat callback dipanggil.

def read_memory():
    usage = psutil.virtual_memory()
    return metrics.Observation(usage.percent, {"mem.unit": "percent"})
 
meter.create_observable_gauge(
    "process.memory.usage", callbacks=[read_memory]
)

#View: Kustomisasi Tanpa Ubah Kode

View adalah konfigurasi SDK yang mengubah bagaimana instrumen di-agregasi dan diekspor — tanpa menyentuh kode aplikasi. Gunakan View untuk:

• Rename instrumen (misal menambahkan unit ke nama).
• Set aggregation — histogram dengan bucket custom, atau drop instrumen yang tak terpakai.
• Filter attribute untuk mengendalikan cardinality (topik episode 19).

from opentelemetry.sdk.metrics import View
from opentelemetry.sdk.metrics.export import ExplicitBucketHistogramAggregation
 
view = View(
    instrument_name="http.server.request.duration",
    aggregation=ExplicitBucketHistogramAggregation(
        boundaries=[0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1.0]
    ),
)

#Delta vs Cumulative: Bahasa Backend

Ada dua cara backend menerima metrics:

• Delta — kenaikan nilai antar interval ekspor (Prometheus menyebutnya counter "irrelevant"; umum di backend tracing seperti Jaeger/OTLP native).
• Cumulative — akumulasi nilai sejak proses dimulai (default Prometheus).

Pilihannya ditentukan SDK/backend dan di-negotiasi lewat OTLP. Kesalahan umum: mencampur keduanya di dashboard dan melihat counter turun — itu biasanya bukan bug, melainkan reset cumulative saat proses restart, atau pergantian mode delta-cumulative yang tidak disadari.

#Export ke Prometheus (Remote Write)

Backend metrics paling umum adalah Prometheus. Dua jalur yang dipakai OTel:

1. SDK → OTLP → Collector → Prometheus remote write — jalur resmi untuk production.
2. Collector menerima scrape dari Prometheus — collector mengekspos endpoint metrics di port 8888, lalu Prometheus men-scrape-nya seperti target biasa.

Tambahkan jalur ekspor ke pipeline collector episode 0:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
 
processors:
  batch:
 
exporters:
  debug:
    verbosity: basic
  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: otel
 
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, prometheus]

Jalankan ulang collector, kirim metrics dari SDK Python, lalu scrape localhost:8889/metrics — kalian akan melihat metric dengan nama otel_http_server_request_count beserta attribute-nya.

#Common Pitfalls

• Histogram bucket default terlalu lebar untuk latensi microservice (banyak nilai masuk bucket terakhir) — kustomisasi via View.
• Cardinality liar — attribute user_id pada metric akan meledakkan jumlah series; gunakan attribute ber-cardinality rendah.
• Unit salah — durasi harus detik (s) sesuai semantic conventions, bukan milidetik, agar backend konsisten.
• Instrumen asinkron memakai callbacks berat — jangan panggil API jaringan di dalam callback observable.

#Penutup

Pada episode 5 ini, kalian telah menguasai instrumen metrics dan cara ekspornya.

Inti yang harus dibawa pulang:

• Empat instrumen inti: Counter (naik), UpDownCounter (naik-turun), Histogram (distribusi), Gauge/observable (snapshot).
• View mengubah agregasi/renaming tanpa menyentuh kode.
• Delta vs cumulative menentukan cara membaca angka; jangan panik melihat counter turun di restart.
• Alerting metrics sebaiknya berbasis rate, dan ekspor produksi via OTLP → collector → Prometheus remote write.

Di episode 6 selanjutnya, kita akan membahas logs: konsep & korelasi dengan traces — Logs API yang masih bertahap, structured logs standar, dan bagaimana trace_id/span_id otomatis disuntikkan ke log record agar log bisa langsung dikaitkan ke trace. Sampai jumpa di episode 6!