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. Saklarnya terpisah dari lisensi, tetapi pengirimannya tidak: telemetry memakai instance token yang didapat saat lisensi mendaftar ke server lisensi. Instance tanpa lisensi aktif dan terdaftar tidak mengirim apa pun, walau TELEMETRY_ENABLED=true.

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.

Tiga tab di menu Telemetry

Halaman Telemetry punya tiga tab dengan route sendiri:

Akses ke menu ini hanya untuk pengguna dengan role license_admin.

Executive Dashboard

Identitas akun pada tangkapan layar disensor. Data pada tangkapan layar berasal dari lingkungan uji dengan klien contoh, jadi angkanya bukan angka pemakaian sebenarnya.

• Periode dan pembanding. Pilih 7 hari, 30 hari (pilihan awal), atau 90 hari. Periode dihitung termasuk hari ini, tetapi hari ini belum lengkap sehingga tidak ikut dihitung: pada 30 hari, kartu menghitung 29 hari lengkap dan membandingkannya dengan 29 hari sebelumnya. Keterangan di kanan atas (Dibanding 29 hari sebelumnya · data sampai 4 Nov 2026) menunjukkan jumlah hari dan tanggal terakhir yang dipakai. Pada grafik, bagian yang belum lengkap digambar dengan garis putus.
• Filter. Environment, klien, dan billing (Berbayar, Trial, Internal). Pilihan awal environment adalah production; dev dan staging tidak ikut kecuali dipilih.
• Angka pembanding. Teks di bawah angka utama, misalnya ▼ 9,8% vs 126 periode sebelumnya, berarti nilai periode sebelumnya yang sama panjang adalah 126, dan nilai sekarang turun 9,8% dari angka itu. Klien yang belum punya data pada periode sebelumnya diberi tanda baru, bukan persentase.

Kartu ringkasan

Ikon i di samping judul kartu membuka penjelasan singkat saat kursor diarahkan ke ikon itu.

• Klien aktif melapor (misalnya 4 / 6). Angka kanan adalah jumlah klien yang pernah melapor, angka kiri adalah klien yang masih melapor. Klien dihitung tidak melapor kalau tidak ada satu pun instance-nya yang melapor selama 3 hari atau lebih (dihitung sampai kemarin). Klien dengan beberapa instance baru dianggap tidak melapor kalau semua instance-nya diam.
• Rata-rata user aktif harian. User aktif dihitung per hari, jadi kartu ini menampilkan rata-rata harian, dibulatkan ke bilangan bulat, bukan penjumlahan antar hari, karena orang yang sama akan terhitung berulang. Puncak harian di bawahnya adalah jumlah user aktif tertinggi dalam satu hari pada periode terpilih.
• Total request dijumlahkan sepanjang periode. Request adalah jumlah panggilan API yang lewat gateway, termasuk panggilan otomatis dari aplikasi, bukan jumlah klik pengguna.
• Process instance (nilai terakhir). Kartu ini mengambil jumlah process instance dari laporan terakhir tiap instance, lalu menjumlahkannya antar klien. Angkanya bukan jumlah per hari dan tidak dijumlahkan antar hari.
• Klien berisiko menghitung klien yang masuk daftar di bawah.

Filter klien

Filter klien punya kolom pencarian (Cari klien…). Klien yang sudah dipilih tetap tampil pada tombol filter walaupun pencarian berikutnya tidak menemukan apa pun (pesan Tidak ada klien dengan telemetry yang cocok), sehingga pembaca tidak kehilangan konteks angka yang sedang ditampilkan. Semua kartu, grafik, dan tabel pada halaman ini ikut berubah mengikuti klien terpilih.

Klien berisiko

Sebuah klien masuk daftar Klien berisiko kalau memenuhi salah satu syarat berikut:

1. rata-rata user aktif harian turun lebih dari 30% dibanding periode sebelumnya;
2. tidak melapor selama 3 hari atau lebih (dihitung sampai kemarin);
3. access log mati selama 3 hari atau lebih.

Hari tanpa access log dikeluarkan dari perhitungan, bukan dianggap nol. Karena itu klien dengan access log mati ditandai tidak dihitung pada kolom Δ user aktif, dan tidak dianggap turun.

Peta adopsi fitur dan fitur paling lambat

• Peta adopsi fitur menunjukkan fitur yang dipakai tiap klien. Persentase pada sel adalah hari fitur itu terlihat dibagi hari klien itu aktif melapor, dan hanya dihitung dari 20 event teratas per instance per hari. Karena itu nilainya bisa lebih rendah dari pemakaian sebenarnya. Sel kosong (—) berarti fitur itu tidak terlihat di 20 teratas, bukan berarti tidak dipakai.
• Peta menampilkan 8 fitur lebih dulu. Kalau lebih banyak fitur yang terlihat, tombol Tampilkan semua muncul untuk menampilkan sisanya.
• Lihat daftar lengkap fitur membuka daftar semua fitur yang dikenal aplikasi, dengan kategori dan jumlah klien yang terlihat memakainya (— kalau belum ada). Satu nama fitur hanya muncul satu kali di daftar ini, walaupun beberapa endpoint memakai nama yang sama.
• Endpoint belum dipetakan (daftar yang bisa dibuka di bawah peta) berisi endpoint yang belum ada di kamus nama fitur. Endpoint ini tidak ikut dihitung dalam peta adopsi.
• Fitur paling lambat menampilkan median p95 waktu proses antar klien, berdasarkan 10 fitur paling lambat per instance per hari. Hari dengan access log mati tidak dihitung.
• Nama fitur yang belum punya terjemahan ditampilkan dengan nama teknisnya dan penanda belum diterjemahkan.

Peringkat klien

Tabel peringkat diurutkan dari total request terbanyak pada periode terpilih. Ini ukuran volume pemakaian, bukan skor kesehatan klien: klien di urutan teratas belum tentu paling sehat, dan klien di bawah belum tentu bermasalah.

Kolomnya: total request, perubahan dibanding periode lalu, rata-rata user aktif harian, jumlah instance, process instance (nilai terakhir), error rate (5xx), jumlah addon, pemakaian AI, dan waktu laporan terakhir. Nilai yang tidak bisa dihitung ditampilkan sebagai —, bukan 0. Instance yang tidak melapor dikumpulkan di bagian Instance yang tidak melapor.

Semua Data

Tabel ini berisi 1 baris untuk setiap kombinasi instance dan hari, diurutkan dari tanggal terbaru. Yang tersedia:

• Filter tanggal, environment, billing, dan status; ada juga pilihan Hanya yang terlambat melapor. Filter yang aktif tampil sebagai chip di atas tabel, termasuk rentang tanggalnya.
• Preset tanggal. Tombol Tanggal membuka daftar preset di sisi kiri kalender (lihat Preset tanggal).
• Kolom: tombol Kolom mengatur kolom yang tampil.
• Urut dan jumlah baris per halaman.
• Export CSV (sesuai filter) mengunduh data sesuai filter yang sedang aktif.

Preset tanggal

Preset dihitung sampai hari ini dan termasuk hari ini, sama seperti pilihan awal halaman (30 hari terakhir):

Rentang yang tampil pada chip di atas tabel sama persis dengan rentang yang dipakai tabel dan Export CSV (sesuai filter): setelah memilih 3 bulan terakhir pada 5 November 2026, chip menunjukkan 8 Agu – 5 Nov dan permintaan ekspor memakai tanggal yang sama (8 Agustus – 5 November).

Status laporan

Kolom Status laporan memakai nilai berikut:

Tanda — berarti metrik tidak bisa dihitung (access log mati atau instance tidak melapor), bukan nol pemakaian. Baris hari ini masih berjalan dan angkanya bertambah sampai tengah malam.

Batasan data

• Riwayat telemetry baru ada sejak pertengahan September 2026.
• Instance lama yang belum mengirim environment tidak ikut bila filter environment dipakai.
• Menu hanya bisa diakses role license_admin.

Menu Telemetry (Per Instance)

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.

Pesan blocking dan troubleshooting

Fitur Telemetry di License Admin tidak punya pesan blocking yang menghentikan pengguna: bagian ini tidak berlaku. Untuk data yang tidak masuk, ikuti Validasi dan Troubleshooting Telemetry.