Mekanisme Heartbeat

Pendahuluan

Setelah pendaftaran, agen sensor masuk ke dalam loop heartbeat yang berkelanjutan, secara berkala mengumpulkan metrik sistem dan mengirimkannya ke backend. Ini adalah tanggung jawab utama agen yang berkelanjutan — memberikan visibilitas waktu nyata (real-time) kepada pusat pertahanan mengenai kesehatan host sensor dan aktivitas antarmuka jaringan.

---

Loop Heartbeat

Loop heartbeat tidak pernah berhenti. Heartbeat yang gagal dicatat, tetapi agen tetap beroperasi.

---

Permintaan Heartbeat

Titik Akhir (Endpoint):

POST /api/sensors/:sensorId/agent/heartbeat

Header:

Header	Nilai
Content-Type	application/json
X-Sensor-Token	Token sensor yang tahan lama dari pendaftaran

Payload:

{
  "sensorToken": "durable-token",
  "timestamp": "2025-12-19T12:00:00Z",
  "cpuUsage": 25.5,
  "memoryUsed": 4294967296,
  "memoryTotal": 17179869184,
  "memoryPercent": 25.0,
  "interfaces": [
    {
      "name": "enp130s0f0",
      "isManagement": true,
      "isLoopback": false,
      "isVirtual": false,
      "isWireless": false,
      "isUp": true,
      "bytesSent": 1073741824,
      "bytesRecv": 2147483648
    }
  ]
}

---

Metrik yang Dikumpulkan

Penggunaan CPU

• Sumber: gopsutil/cpu.Percent(time.Second, false)
• Mengembalikan agregat penggunaan CPU di semua core sebagai persentase tunggal.
• Jendela sampel 1 detik berarti setiap siklus heartbeat membutuhkan setidaknya 1 detik untuk pengukuran CPU.

Memori

• Sumber: gopsutil/mem.VirtualMemory()
• Field yang dikumpulkan:

Field	Tipe	Deskripsi
memoryUsed	uint64	Memori yang digunakan (byte)
memoryTotal	uint64	Total memori (byte)
memoryPercent	float64	Persentase memori digunakan

Antarmuka Jaringan

• Sumber: net.Interfaces() + gopsutil/net.IOCounters(true)
• Setiap antarmuka pada host dilaporkan dengan:

Field	Tipe	Deskripsi
name	string	Nama antarmuka (misalnya, enp130s0f0)
isManagement	bool	True jika ini adalah antarmuka rute default
isLoopback	bool	True untuk antarmuka loopback (lo)
isVirtual	bool	True untuk bridge Docker, veth, tun, tap, dll.
isWireless	bool	True untuk antarmuka nirkabel (wl*, wlan*)
isUp	bool	True jika antarmuka memiliki bendera UP
bytesSent	uint64	Kumulatif byte terkirim (sejak boot)
bytesRecv	uint64	Kumulatif byte diterima (sejak boot)

---

Aturan Klasifikasi Antarmuka

Agen mengklasifikasikan setiap antarmuka jaringan menggunakan aturan berikut:

Klasifikasi	Metode Deteksi
Management	Nama antarmuka cocok dengan perangkat rute default dari ip route show default
Loopback	Bendera net.FlagLoopback diatur, atau namanya adalah lo
Virtual	Nama dimulai dengan: veth, docker, br-, virbr, vnet, tun, tap
Wireless	Nama dimulai dengan: wl, wlan

Klasifikasi ini membantu backend menentukan antarmuka mana yang layak untuk penyebaran sensor virtual. Antarmuka management, loopback, virtual, dan wireless biasanya tidak layak untuk pengambilan paket (packet capture).

---

Interval Heartbeat

Interval antar heartbeat ditentukan oleh dua sumber:

1. Dari respons pendaftaran — Backend mengirimkan heartbeatIntervalSeconds selama pendaftaran, dan agen mengadopsi nilai ini.
2. Dari variabel lingkungan — HEARTBEAT_INTERVAL mengatur interval awal (default: 30 detik). Ini digunakan untuk periode pra-pendaftaran; setelah terdaftar, nilai yang diberikan backend akan didahulukan.

---

Pemrosesan Backend

Saat backend menerima heartbeat:

1. Memvalidasi header X-Sensor-Token.
2. Menyimpan metrik CPU dan memori di InfluxDB (pengukuran sensor_metrics).
3. Memperbarui stempel waktu lastHeartbeatAt milik sensor.
4. Menyimpan status antarmuka untuk inventaris antarmuka backend (SensorNetworkInterface).
5. Memperbarui status online/offline berdasarkan kebaruan heartbeat.

Frontend kemudian menanyakan metrik ini untuk:

• Lencana kesehatan sensor (Sehat / Peringatan / Kritis berdasarkan ambang batas CPU/memori).
• Status online/offline (heartbeat lebih baru dari 5 menit = online).
• Daftar antarmuka pada halaman detail sensor.

---

Mode Kegagalan

Skenario	Perilaku
Pengumpulan metrik CPU gagal	Heartbeat mengembalikan error, dicatat, loop berlanjut
Pengumpulan metrik memori gagal	Heartbeat mengembalikan error, dicatat, loop berlanjut
Pengumpulan antarmuka gagal	Heartbeat mengembalikan error, dicatat, loop berlanjut
Backend tidak terjangkau	Error HTTP dicatat, loop berlanjut
Backend mengembalikan non-200	Error dicatat dengan kode status, loop berlanjut
Kegagalan JSON marshaling	Error dicatat, loop berlanjut

Loop heartbeat dirancang agar resilien — tidak ada kegagalan tunggal yang menyebabkan agen berhenti. Hal ini memastikan pemantauan terus-menerus bahkan selama masalah jaringan sementara.