Belajar ChromaDB - Observability & Operations

#Pendahuluan

Semua kehebatan ChromaDB tidak berarti jika kalian buta terhadap apa yang terjadi. Episode 20 membahas observability dan operations — mata dan tangan dari sistem produksi: health check, metrics, logging, instrumentasi OpenTelemetry, backup rutin, capacity planning, dan incident response.

Kombinasi observability dan operations adalah yang membedakan "aplikasi yang jalan" dari "sistem yang dikelola". Kalian akan melihat bagaimana memantau server, mengukur performa, dan bersiap menghadapi kegagalan.

#Health Check dan Verifikasi Server

#Heartbeat sebagai Detak Jantung

ChromaDB menyediakan endpoint health yang simpel. Verifikasi berkala adalah gerbang observability paling dasar:

curl http://localhost:8000/api/v2/heartbeat

curl http://localhost:8000/api/v2/heartbeat mengembalikan timestamp — tanda server hidup. Untuk monitoring otomatis, jadwalkan health check ini setiap beberapa detik:

while true; do
  curl -fsS http://localhost:8000/api/v2/heartbeat && echo " OK $(date)"
  sleep 10
done

Loop di atas mencetak status tiap 10 detik. Di produksi, ganti dengan probe dari orchestrator — Kubernetes livenessProbe dan readinessProbe meniru persis pola ini.

#Metrics: Latensi dan Throughput

#Menemukan Angka Kunci

Metrics yang wajib dipantau untuk ChromaDB:

• Latensi query: berapa lama satu query selesai.
• Throughput: berapa banyak query per detik yang dilayani.
• Error rate: persentase permintaan gagal.
• Utilisasi memori: karena index HNSW hidup di RAM (episode 17).

Ukur latensi dari sisi aplikasi:

Mengukur latensi query

import time
 
start = time.perf_counter()
hasil = collection.query(query_texts=["deploy"], n_results=5)
latensi_ms = (time.perf_counter() - start) * 1000
print(f"latensi query: {latensi_ms:.1f} ms")

latensi_ms = (time.perf_counter() - start) * 1000 menghitung durasi satu query. Catat nilai p50 dan p99 dalam jangka panjang — pergeseran p99 menandakan degradasi index atau RAM yang menipis.

#Ekspor Metrics ke Backend

Di produksi, metrics harus mengalir ke backend seperti Prometheus. Instrumentasi dilakukan di lapisan aplikasi: ukur tiap query, ekspor sebagai histogram, dan biarkan Prometheus menariknya. Detail implementasi bergantung stack — yang penting konsisten antara cara mengukur dan cara menyimpan.

#Logging dan OpenTelemetry

#Logging Terstruktur di Aplikasi

Log yang baik punya konteks: collection, query, dan hasil. Contoh logging terstruktur dari aplikasi klien:

Logging query terstruktur

import logging
 
logging.basicConfig(level=logging.INFO)
log = logging.getLogger("chroma-app")
 
log.info(
    "query collection=%s n=%s latensi_ms=%.1f",
    "dokumen", 5, latensi_ms,
)

log.info("query collection=%s n=%s latensi_ms=%.1f", ...) menulis log dengan field terstruktur. Log yang konsisten memudahkan pencarian saat troubleshooting — misalnya "semua query dengan latensi di atas 1 detik".

#OpenTelemetry dan traceAI-chromadb

Untuk tracing end-to-end pipeline RAG, gunakan OpenTelemetry. Ekosistem Chroma menyediakan traceAI-chromadb, adapter yang menghubungkan instrumentasi ChromaDB ke backend OpenTelemetry:

Setup OpenTelemetry untuk ChromaDB

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint="http://collector:4318")))

provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint="http://collector:4318"))) mengirim trace ke collector OpenTelemetry. Dengan instrumentasi yang tepat, setiap permintaan RAG bisa ditelusuri: embed, query, filter, hingga jawaban LLM — melihat di mana waktu paling banyak hilang.

#Backup dan Restore Rutin

#Menjadwalkan Backup

Data di episode 11 sudah diajarkan caranya di-backup; episode 20 mengatur agar backup menjadi rutin. Jadwalkan dengan cron:

0 2 * * * rsync -a --delete /data/chroma/ /backup/chroma-daily/

Baris cron di atas menjalankan rsync -a --delete /data/chroma/ /backup/chroma-daily/ setiap pukul 02.00. Simpan juga snapshot di luar mesin — backup yang tinggal di server yang sama tidak menyelamatkan dari kerusakan disk.

#Menguji Restore Secara Berkala

Backup yang tidak pernah diuji bukanlah backup. Jadwalkan uji restore ke environment terpisah minimal sebulan sekali: copy backup, jalankan server dari situ, lalu verifikasi jumlah collection dan query dasar. Proses ini menemukan backup yang rusak sebelum darurat datang.

#Capacity Planning dan Incident Response

#Capacity Planning

Capacity planning menjawab "kapan perlu nambah resource?". Pantau tiga sinyal:

• Pertumbuhan vektor: seberapa cepat collection bertambah (episode 17).
• RAM terpakai: pendekatan batas index in-memory.
• Latensi p99: mulai naik saat resource mendekati penuh.

Aturan sederhana: saat RAM terpakai 70 persen dari alokasi, mulai rencanakan upgrade. Jangan menunggu p99 meroket.

#Incident Response untuk ChromaDB

Siapkan runbook minimal sebelum insiden:

1. Deteksi: alert heartbeat mati atau latensi p99 naik.
2. Triage: cek log dan metrics — crash, kehabisan RAM, atau koneksi?
3. Respon: restart server, naikkan resource, atau rollback versi.
4. Pemulihan: restore dari backup jika data rusak.
5. Review: catat penyebab dan perbaiki monitoring.

Runbook dalam bentuk kode

def cek_server(client):
    try:
        client.heartbeat()
        print("server: sehat")
        return True
    except Exception as e:
        print("server: bermasalah ->", e)
        return False
 
if not cek_server(client):
    print("jalankan: systemctl restart chroma")

Fungsi cek_server(client) mengotomatiskan deteksi awal. Runbook yang terdokumentasi membuat insiden pertama terasa seperti drill, bukan bencana.

#Penutup

Episode 20 memberi ChromaDB mata dan tangan: health check heartbeat, metrics latensi dan throughput, logging terstruktur, tracing OpenTelemetry dengan traceAI-chromadb, backup dan restore rutin yang teruji, capacity planning dari sinyal RAM dan pertumbuhan, serta runbook incident response yang jelas.

Inti yang harus dibawa pulang:

• Heartbeat adalah gerbang observability paling dasar.
• Pantau latensi p99, throughput, error rate, dan utilisasi RAM.
• OpenTelemetry menghubungkan trace ChromaDB ke backend terpusat.
• Backup harus terjadwal, tersimpan di luar mesin, dan diuji berkala.
• Capacity planning mulai saat RAM terpakai 70 persen.
• Runbook incident yang terdokumentasi mengubah panik menjadi prosedur.

Di episode 21 selanjutnya kita akan membahas fitur modern dan roadmap — kemampuan ChromaDB 2026: vector, full-text, regex, dan metadata dalam satu engine, rilis mingguan, server Rust untuk produksi, Chroma Cloud, serta arah pengembangan serverless dan multi-node. Kalian akan tahu ke mana teknologi ini bergerak.