Services & Ports

FREMIS-N mengekspos beberapa port untuk keperluan API, metrics, dan monitoring. Berikut ringkasan lengkap port default dan peran masing-masing komponen.

Port Default

Komponen	Port	Fungsi
FREMIS-N HTTP API	`4003`	Endpoint API utama untuk enrollment, search, match, dan manajemen keyspace
Prometheus metrics	`4040/metrics`	Endpoint metrics dalam format Prometheus; di-scrape oleh Prometheus server
Prometheus server	`9090`	Web UI Prometheus untuk query dan eksplorasi metrics
Grafana dashboard	`3000`	Dashboard visualisasi metrics dan alert

Port 4040 adalah endpoint metrics yang diekspos langsung oleh FREMIS-N. Port 9090 dan 3000 adalah komponen monitoring eksternal (Prometheus + Grafana) yang perlu dijalankan secara terpisah. Lihat Configuration Reference — Monitoring & Observability untuk panduan setup-nya.

Deskripsi Komponen

FREMIS-N HTTP API (port 4003)

Ini adalah entry point utama untuk semua interaksi dengan FREMIS-N — baik dari Visionaire, Lenz, maupun integrasi langsung via HTTP. Semua operasi enrollment, recognition, match 1:1, search 1:N, dan manajemen keyspace dilayani melalui port ini.

Untuk deployment cluster, arahkan klien ke coordinator (bukan ke node data), meskipun coordinator juga mengekspos API di port yang sama. Lihat Installation — Setup Cluster untuk detail.

Prometheus Metrics Endpoint (port 4040)

FREMIS-N mengekspos metrics operasional secara native dalam format Prometheus di http://<host>:4040/metrics. Metrics yang tersedia mencakup:

Throughput — queries per second (QPS) per tipe operasi (enrollment, recognition, utility)
Latency — p50, p95, p99 response time untuk setiap endpoint
Error rate — persentase request yang gagal, breakdown per jenis error
License status — quota utilization dan QPS remaining dari paket lisensi
Database health — connection pool status, query latency, transaction success rate
System resources — CPU, memory, disk I/O dari node FREMIS-N

Prometheus Server (port 9090)

Prometheus adalah sistem monitoring open-source yang secara berkala men-scrape endpoint metrics FREMIS-N (4040/metrics) dan menyimpan datanya sebagai time-series. Web UI Prometheus di port 9090 memungkinkan query ad-hoc menggunakan PromQL.

Prometheus perlu dikonfigurasi untuk menargetkan endpoint FREMIS-N. Lihat Configuration Reference — Setup Monitoring dengan Grafana.

Grafana Dashboard (port 3000)

Grafana menyediakan visualisasi dashboard yang lebih kaya dibandingkan UI Prometheus. Dashboard FREMIS-N yang sudah dikonfigurasi dapat diimport dari file fremis-n_dashboard.json yang disediakan di repository FREMIS-N.

Health Check Endpoint

FREMIS-N mengekspos endpoint health yang menunjukkan kesiapan sistem menerima traffic:

curl http://localhost:4003/health

Endpoint ini berguna untuk readiness probe di Kubernetes atau health check di load balancer. Endpoint mengembalikan status unhealthy jika:

Database tidak terjangkau atau terjadi kesalahan koneksi
Lisensi belum tervalidasi atau sudah expired
Node sedang dalam proses startup atau shutdown
Dependensi kritis lainnya tidak tersedia

Lihat API Reference untuk detail path endpoint dan format respons lengkap.

License & Connectivity Issues

Validasi lisensi dilakukan saat startup dan secara berkala selama service berjalan. Dua skenario kegagalan paling sering muncul.

Service Refuses to Start — License Check-in Failure

FREMIS-N gagal start dengan error terkait lisensi atau tidak dapat connect ke layanan verifikasi lisensi.

Verifikasi credentials. Cek --access-key dan --secret-key yang digunakan saat start service — keys bersifat case-sensitive. Jika ragu, minta credentials baru dari tim Nodeflux.
Test network connectivity. Dari node FREMIS-N, coba curl ke endpoint license service yang dikonfigurasi. Jika gagal, periksa firewall yang memblokir outbound traffic dan pastikan DNS resolution bekerja.
Review logs startup. Cari error message spesifik di stderr/stdout untuk tahu tahap mana yang gagal — koneksi, authentication, atau parsing config.

Service Berjalan tetapi Semua Request 401/403

Service start sukses, tetapi setiap recognition/enrollment request mengembalikan 401 atau 403.

Restart service dengan credentials yang benar — token lisensi internal di-refresh saat startup.
Verifikasi lisensi status ke tim Nodeflux: apakah masih aktif dan tanggal expiry-nya. Request renewal jika sudah lewat.
Check /health. Endpoint ini secara eksplisit mengembalikan unhealthy ketika lisensi belum tervalidasi atau sudah expired — gunakan sebagai sinyal cepat sebelum melihat logs lebih detail.

Selanjutnya

Configuration Reference — setup monitoring Prometheus + Grafana, konfigurasi alert, dan referensi parameter lengkap
Installation — perintah Docker untuk standalone dan cluster, termasuk panduan database initialization

Services & Ports

On this page