Analitik dan Metrik

Pendahuluan

Modul analitik menyediakan akses ke data peringatan/peristiwa (alert/event) dari OpenSearch dan telemetri sensor tingkat host dari InfluxDB. OpenSearch tetap dikunci berdasarkan identitas sensor virtual, sementara InfluxDB sekarang menyimpan status online sensor fisik dan metrik host yang dipancarkan oleh agen host tunggal yang diinstal pada setiap sensor.

---

Controller

Controller	Rute	Deskripsi
OpenSearchController	api/opensearch	Titik akhir analitik dan dasbor OpenSearch
VirtualSensorsAnalyticsController	api/analytics/virtual-sensors	Data filter sensor virtual untuk analitik

File:

• API/Controllers/Analytics/OpenSearchController.cs → mendelegasikan ke IOpenSearchAnalyticsService
• API/Controllers/Analytics/VirtualSensorsAnalyticsController.cs → mendelegasikan ke IVirtualSensorsAnalyticsService

Lapisan Layanan

Antarmuka Layanan	Implementasi	Tanggung Jawab
IOpenSearchAnalyticsService	OpenSearchAnalyticsService	Orkestrasi kueri OpenSearch dengan caching, kebijakan timeout, dan fallback yang anggun (graceful fallback)
IVirtualSensorsAnalyticsService	VirtualSensorsAnalyticsService	Analitik sensor virtual

OpenSearchAnalyticsService dan VirtualSensorsAnalyticsService menangani komposisi kueri analitik dan pembentukan respons di atas dependensi OpenSearch dan database yang dikonfigurasi.

---

Integrasi OpenSearch

Layanan

File: Infrastructure/Services/OpenSearchAnalyticsService.cs Masa Pakai (Lifetime): Scoped (didaftarkan sebagai IOpenSearchAnalyticsService) Pustaka (Library): OpenSearch.Client v1.8.0

Konfigurasi

{
  "OpenSearch": {
    "Url": "{{OpenSearch__Url}}",
    "Username": "{{OpenSearch__Username}}",
    "Password": "{{OpenSearch__Password}}",
    "IndexName": "{{OpenSearch__IndexName}}"
  }
}

{
  "OpenSearchAnalytics": {
    "DefaultTimeoutSeconds": 20,
    "DashboardTimeoutSeconds": 30,
    "AggregationTimeoutSeconds": 15,
    "ListQueryTimeoutSeconds": 25
  },
  "AnalyticsCacheWarming": {
    "Enabled": true,
    "IntervalMinutes": 5,
    "InitialDelaySeconds": 20
  }
}

Kunci	Tipe	Default	Deskripsi
Url	string	https://localhost:9200	URL titik akhir OpenSearch
Username	string	admin	Nama pengguna autentikasi
Password	string	(wajib)	Kata sandi autentikasi
IndexName	string	mataelang-sensor-events-stream	Indeks default untuk kueri

Validasi Startup

Ketersediaan OpenSearch diverifikasi selama pemeriksaan kesehatan startup:

• HTTP GET ke URL root dengan Basic Auth
• Validasi sertifikat SSL dilewati (DangerousAcceptAnyServerCertificateValidator)
• Mencoba kembali (retry) hingga 3 kali dengan timeout 10 detik per percobaan

Penggunaan

OpenSearchAnalyticsService menyediakan metode untuk:

• Mengagregasi peringatan untuk kartu dasbor dan bagan
• Memfilter data peringatan berdasarkan organisasi, sensor virtual, rentang waktu, dan metadata IP/protokol
• Mengembalikan daftar peringatan yang dipaginasi dan data aliran IP (IP-flow) untuk UI analitik

Kontrak Identitas Sensor

• Analitik OpenSearch mengharapkan metadata.sensor_id menyimpan UUID sensor virtual
• Filter analitik backend membandingkan metadata.sensor_id.keyword dengan virtual_sensors.id
• Alur kesehatan/metrik InfluxDB dan Heartbeat terus menggunakan UUID sensor fisik
• Perbaikan pemetaan ini hanya berlaku untuk data baru; dokumen OpenSearch historis yang diindeks dengan UUID sensor fisik tetap tidak berubah dan tidak akan muncul di UI analitik sensor virtual

---

Integrasi InfluxDB

Layanan

File: Infrastructure/Services/InfluxDbService.cs Masa Pakai (Lifetime): Singleton Pustaka (Library): InfluxDB.Client v4.18.0

Konfigurasi

{
  "InfluxDb": {
    "Url": "{{InfluxDb__Url}}",
    "Token": "{{InfluxDb__Token}}",
    "Org": "{{InfluxDb__Org}}",
    "Bucket": "{{InfluxDb__Bucket}}",
    "Precision": "ms",
    "TimeoutSeconds": 30
  }
}

Kunci	Tipe	Default	Deskripsi
Url	string	—	URL server InfluxDB
Token	string	—	Token autentikasi
Org	string	—	Organisasi InfluxDB
Bucket	string	—	Bucket default untuk kueri
Precision	string	ms	Presisi penulisan (write)
TimeoutSeconds	int	30	Batas waktu klien

Validasi Startup

Ketersediaan InfluxDB diverifikasi selama pemeriksaan kesehatan startup:

• HTTP GET ke titik akhir {url}/health
• Harus mengembalikan kode status sukses
• Mencoba kembali hingga 3 kali dengan timeout 10 detik per percobaan

Penggunaan

InfluxDbService menyediakan metode untuk:

• Menulis status online ke pengukuran sensor_status
• Menulis CPU host, memori, dan lalu lintas antarmuka yang memenuhi syarat ke pengukuran sensor_metrics
• Mengueri metrik host untuk UI metrik sensor
• Mengambil stempel waktu heartbeat online terbaru untuk pemantauan kesehatan

Metrik DTO

File: Application/DTOs/SensorHeartbeatMetricsDto.cs

Digunakan untuk mentransfer data heartbeat dan metrik:

public class SensorHeartbeatMetricsDto
{
    // Field heartbeat dan metrik untuk pemantauan sensor
}

File: Application/DTOs/SensorMetricsRequest.cs

Digunakan untuk meminta data metrik:

public class SensorMetricsRequest
{
    // Rentang waktu dan parameter filter untuk kueri metrik
}

---

Perilaku Runtime

Persyaratan Startup

Pemeriksaan	Perilaku saat Gagal
Kesehatan OpenSearch	Startup gagal setelah 3 percobaan
Kesehatan InfluxDB	Startup gagal setelah 3 percobaan

Kedua layanan bersifat fail-fast saat startup — aplikasi tidak akan berjalan jika salah satu layanan tidak tersedia. Hal ini memastikan integritas data dan mencegah permintaan gagal secara diam-diam.

Perilaku Waktu Permintaan (Request-Time)

• Titik akhir analitik OpenSearch mengueri OpenSearch secara sinkron melalui OpenSearchAnalyticsService
• Titik akhir analitik dengan frekuensi tinggi menggunakan cache Redis dan pola fallback cache-lama (stale-cache)
• Analitik OpenSearch menggunakan opsi timeout per jenis kueri (OpenSearchAnalyticsOptions)
• Circuit breaker diterapkan dalam eksekusi kueri analitik
• Pemanasan cache latar belakang (background cache warming) berjalan melalui layanan ter-host (AnalyticsCacheWarmingService) untuk jalur dasbor utama
• Metrik yang didukung InfluxDB tetap tersedia melalui lapisan layanan mereka sendiri di luar rute analitik lama yang telah dihapus

Catatan Peluncuran (Rollout)

• Setiap sensor fisik menjalankan tepat satu agen host yang diinstal melalui perintah instalasi yang dihasilkan backend
• Penyebaran sensor virtual tidak lagi menyertakan sidecar heartbeat; hanya Suricata dan sensor-client yang disebarkan per sensor virtual
• MES_CLIENT_SENSOR_ID terus menggunakan UUID sensor virtual untuk identitas analitik OpenSearch

---

Registrasi Layanan

Layanan analitik yang relevan didaftarkan di ServiceCollectionExtensions:

services.AddSingleton<InfluxDbService>();
services.AddScoped<IOpenSearchAnalyticsService, OpenSearchAnalyticsService>();
services.AddScoped<IVirtualSensorsAnalyticsService, VirtualSensorsAnalyticsService>();
services.AddSingleton<CircuitBreakerService>();
services.AddHostedService<AnalyticsCacheWarmingService>();

Layanan tersebut menerima konfigurasi melalui opsi ber-tipe IOptions<T>:

• InfluxDbService ← IOptions<InfluxDbOptions>
• OpenSearchAnalyticsService ← IOptions<OpenSearchOptions> dan IOptions<OpenSearchAnalyticsOptions>

---

Perbaikan di Masa Depan

Selesai

• Caching respons untuk titik akhir analitik utama.
• Konfigurasi timeout per jenis kueri.
• Jalur eksekusi circuit breaker di layanan analitik.
• Dukungan paginasi untuk daftar peringatan (page, pageSize).

Terbuka

• Cakupan agregasi hasil kueri (pemanasan cache mencakup jalur utama, bukan semua bentuk kueri).
• Standarisasi kontrak metadata degradasi anggun (graceful degradation) di semua bentuk respons titik akhir.