Telemetry

Instance Usage Telemetry adalah data pemakaian harian yang dikirim satu arah dari tiap instance On Premise ke License Admin — bukan konfigurasi lisensi, murni angka agregat: fitur apa yang paling sering dipakai, aksi mana yang lambat, dan seberapa besar data yang tersimpan di instance itu.

Mengaktifkan di instance klien

Telemetry dikendalikan oleh env var TELEMETRY_ENABLED di tenant-management-service milik instance klien, independen dari lisensi — sebuah instance bisa mengirim telemetry walau LICENSE_ENABLED=false, dan sebaliknya.

Selama sebuah instance memang tidak mengirim apa pun (env var eksplisit di-set false, atau instance itu berjalan di versi rilis sebelum commit di atas dan tidak pernah diaktifkan manual), instance itu tidak akan muncul di menu Telemetry dan widget Dashboard-nya kosong — itu kondisi normal, bukan tanda kerusakan.

Menu Telemetry

Buka Telemetry di sidebar (route /telemetry). Halaman ini mendaftar setiap instance yang pernah berhasil mengirim telemetry, beserta tanggal kiriman terakhirnya.

Instance ID pada tangkapan layar di atas disensor — kolomnya tetap tampil apa adanya di aplikasi.

Tidak ada baris di sini bukan berarti telemetry-nya bermasalah — instance itu belum pernah berhasil mengirim satu snapshot pun (opt-out, atau belum naik ke versi rilis yang mendukungnya). Instance hanya muncul setelah baris pertamanya berhasil ditulis ke tabel snapshot.

Detail instance per tanggal

Klik ikon mata pada sebuah baris (route /telemetry/$instanceId) untuk melihat payload lengkap yang diterima pada satu snapshot_date — apa adanya dari tabel snapshot, bukan hasil olahan ulang di FE. Pemilih tanggal di bagian atas beralih di antara snapshot yang tersedia untuk instance itu.

Di sebelah tanggal snapshot ada penanda Access log mode. Ini bukan hasil pengukuran — nilainya OPS-DECLARED lewat env var TELEMETRY_ACCESS_LOG_MODE di sisi pengirim (mengikuti GATEWAY_ACCESS_LOG_MODE proxy-service instance itu), dikirim apa adanya di tiap payload. Kegunaannya dijelaskan di Membaca angka nol di bawah.

15 metrik dalam 3 kategori

Payload berisi tepat 15 metrik (kunci top-level ini adalah allow-list — payload dengan field di luar daftar ini ditolak server), dikelompokkan jadi 3 kategori untuk tampilan. Nama kategori dan kunci berikut diambil langsung dari kode, bukan dari ingatan:

Kategori 1 dan 2 sama-sama bersumber dari gateway_access_logs (proxy-service) — itu sebabnya keduanya, bukan Kategori 3, yang terpengaruh saat access_log_mode mati (lihat bagian berikutnya).

p95_duration_by_event_tag ditampilkan terpisah dari 3 kartu kategori, sebagai tabel tersendiri "API dengan Waktu Proses Terlama" dibatasi 20 baris (top 20 by P95 duration), karena bisa berisi puluhan/ratusan event tag pada instance yang ramai:

Referensi kode: allow-list dan pengelompokan kategori — license-admin-go internal/modules/instances/telemetry.go (telemetryAllowedMetricKeys) dan internal/modules/dashboard/telemetry.go (telemetryCategoryKeys), origin/master@8eb20d6. Sumber tiap metrik di sisi pengirim — tenant-management-service internal/telemetry/aggregate.go, origin/master@4e23765.

Widget di Dashboard

Tab Onprem pada Dashboard punya kartu Telemetri Pemakaian — ringkasan snapshot terbaru per kategori untuk satu instance pilihan, dengan pemilih instance dan rentang tanggal sendiri.

Widget ini untuk pemantauan cepat sekilas; untuk melihat payload lengkap satu snapshot apa adanya, buka detail instance di menu Telemetry.

Privasi: nol PII, nol baris mentah

Setiap field dalam payload adalah angka agregat, daftar pendek angka agregat, atau penanda cakupan — tidak ada satu pun baris gateway_access_logs mentah, dan tidak ada user_id, username, atau email yang ikut terkirim. Ini bukan konvensi longgar: sisi pengirim memvalidasi struct payload terhadap sebuah allow-list skema sendiri (ValidatePayloadAllowList) yang gagal (dan gagal di test) kalau ada field baru ditambahkan ke struct pengiriman tanpa didaftarkan eksplisit — supaya sebuah field yang lupa di-agregasi tidak bisa lolos terkirim mentah begitu saja.

Batas backfill: 30 hari

Kalau koneksi ke License Admin sempat putus (atau telemetry sempat dimatikan), pengirim akan mencoba mengirim ulang tanggal-tanggal yang terlewat begitu koneksi pulih — tapi dibatasi jendela retensi gateway_access_logs di proxy-service, 30 hari, karena baris sumber datanya sendiri sudah dibuang lewat retensi itu.

Gap yang lebih lebar dari 30 hari, atau gap yang terjadi selagi TELEMETRY_ENABLED=false, tidak bisa dipulihkan — tanggal-tanggal itu dilewati secara eksplisit (dicatat di log pengirim), bukan diam-diam diisi dengan angka nol yang terlihat seperti data asli.

Referensi kode: tenant-management-service internal/telemetry/guard.go (TelemetryRetentionDays = 30), origin/master@4e23765.

Membaca angka nol di Kategori 1 dan 2

Karena Kategori 1 (Fitur yang Sering Dipakai) dan Kategori 2 (Aksi Lambat) sama-sama bersumber dari gateway_access_logs, keduanya bisa tampil nol untuk dua alasan yang berbeda artinya:

• access_log_mode: "off" — proxy-service instance itu memang tidak mencatat access log sama sekali. Metrik-metrik di dua kategori ini nol karena sumber datanya mati, bukan karena instance itu sepi pemakaian. Kategori 3 (Volume Data) tidak terpengaruh — sumbernya bukan gateway_access_logs.
• access_log_mode: "api" atau "all" dengan metrik tetap nol — access log-nya aktif, jadi nol di sini berarti memang tidak ada traffic pada tanggal itu.

Selalu periksa access_log_mode di header halaman detail sebelum menyimpulkan sebuah instance "sepi" dari Kategori 1/2 saja.

Referensi kode: tenant-management-service internal/telemetry/payload.go (field AccessLogMode, dikirim OPS-DECLARED lewat TELEMETRY_ACCESS_LOG_MODE), origin/master@4e23765.