From 0afd4ae1153d07d20dead7448f25c9e0a8b4eb79 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Mon, 4 Aug 2025 18:13:35 +1000 Subject: [PATCH] prometheus metrics docs --- docs/API.md | 102 ++++++++++++++++++++++++++++++++ front/css/app.css | 6 +- front/css/dark-patch.css | 2 +- front/css/system-dark-patch.css | 2 +- front/php/templates/header.php | 4 +- front/systeminfo.php | 3 +- 6 files changed, 110 insertions(+), 9 deletions(-) diff --git a/docs/API.md b/docs/API.md index 46da43ff..986a316d 100755 --- a/docs/API.md +++ b/docs/API.md @@ -221,6 +221,108 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row ``` +## API Endpoint: Prometheus Exporter + +* **Endpoint URL**: `/metrics` +* **Host**: (where NetAlertX exporter is running) +* **Port**: as configured in the `GRAPHQL_PORT` setting (`20212` by default) + +--- + +### Example Output of the `/metrics` Endpoint + +Below is a representative snippet of the metrics you may find when querying the `/metrics` endpoint for `netalertx`. It includes both aggregate counters and `device_status` labels per device. + +``` +netalertx_connected_devices 31 +netalertx_offline_devices 54 +netalertx_down_devices 0 +netalertx_new_devices 0 +netalertx_archived_devices 31 +netalertx_favorite_devices 2 +netalertx_my_devices 54 + +netalertx_device_status{device="Net - Huawei", mac="Internet", ip="1111.111.111.111", vendor="None", first_connection="2021-01-01 00:00:00", last_connection="2025-08-04 17:57:00", dev_type="Router", device_status="Online"} 1 +netalertx_device_status{device="Net - USG", mac="74:ac:74:ac:74:ac", ip="192.168.1.1", vendor="Ubiquiti Networks Inc.", first_connection="2022-02-12 22:05:00", last_connection="2025-06-07 08:16:49", dev_type="Firewall", device_status="Archived"} 1 +netalertx_device_status{device="Raspberry Pi 4 LAN", mac="74:ac:74:ac:74:74", ip="192.168.1.9", vendor="Raspberry Pi Trading Ltd", first_connection="2022-02-12 22:05:00", last_connection="2025-08-04 17:57:00", dev_type="Singleboard Computer (SBC)", device_status="Online"} 1 +... +``` + +--- + +### Metrics Explanation + +#### 1. Aggregate Device Counts + +Metric names prefixed with `netalertx_` provide aggregated counts by device status: + +* `netalertx_connected_devices`: number of devices currently connected +* `netalertx_offline_devices`: devices currently offline +* `netalertx_down_devices`: down/unreachable devices +* `netalertx_new_devices`: devices recently detected +* `netalertx_archived_devices`: archived devices +* `netalertx_favorite_devices`: user-marked favorite devices +* `netalertx_my_devices`: devices associated with the current user context + +These numeric values give a high-level overview of device distribution. + +#### 2. Per‑Device Status with Labels + +Each individual device is represented by a `netalertx_device_status` metric, with descriptive labels: + +* `device`: friendly name of the device +* `mac`: MAC address (or placeholder) +* `ip`: last recorded IP address +* `vendor`: manufacturer or "None" if unknown +* `first_connection`: timestamp when the device was first observed +* `last_connection`: most recent contact timestamp +* `dev_type`: device category or type +* `device_status`: current status (Online / Offline / Archived / Down / ...) + +The metric value is always `1` (indicating presence or active state) and the combination of labels identifies the device. + +--- + +### How to Query with `curl` + +To fetch the metrics from the NetAlertX exporter: + +```sh +curl 'http://:/metrics' \ + -H 'Authorization: Bearer ' \ + -H 'Accept: text/plain' +``` + +Replace: + +* ``: IP or hostname of the NetAlertX server +* ``: port specified in your `GRAPHQL_PORT` setting (default: `20212`) +* `` your Bearer token from the `API_TOKEN` setting + +--- + +### Summary + +* **Endpoint**: `/metrics` provides both summary counters and per-device status entries. +* **Aggregate metrics** help monitor overall device states. +* **Detailed metrics** expose each device’s metadata via labels. +* **Use case**: feed into Prometheus for scraping, monitoring, alerting, or charting dashboard views. + +### Prometheus Scraping Configuration + +```yaml +scrape_configs: + - job_name: 'netalertx' + metrics_path: /metrics + scheme: http + scrape_interval: 60s + static_configs: + - targets: [':'] + authorization: + type: Bearer + credentials: +``` + ## API Endpoint: /log files This API endpoint retrieves files from the `/app/log` folder. diff --git a/front/css/app.css b/front/css/app.css index 926f5d93..e5bb5dd4 100755 --- a/front/css/app.css +++ b/front/css/app.css @@ -2114,16 +2114,16 @@ input[readonly] { pointer-events: auto; } -.pa_semitransparent-panel { +.nax_semitransparent-panel { position: absolute; width: 100%; height: 100%; background-color: #fff; - opacity: 0.8; + opacity: 0.5; z-index: 99; } -.pa_spinner { +.nax_spinner { position: absolute; top: 100px; left: 50%; diff --git a/front/css/dark-patch.css b/front/css/dark-patch.css index 5a1016e3..4b83be74 100755 --- a/front/css/dark-patch.css +++ b/front/css/dark-patch.css @@ -744,7 +744,7 @@ table.dataTable tbody tr.selected, table.dataTable tbody tr .selected top: 0.01em; font-size: 3.25em; } -.pa_semitransparent-panel{ +.nax_semitransparent-panel{ background-color: #000 !important; } diff --git a/front/css/system-dark-patch.css b/front/css/system-dark-patch.css index ac5bb25f..75672907 100755 --- a/front/css/system-dark-patch.css +++ b/front/css/system-dark-patch.css @@ -746,7 +746,7 @@ top: 0.01em; font-size: 3.25em; } - .pa_semitransparent-panel{ + .nax_semitransparent-panel{ background-color: #000 !important; } diff --git a/front/php/templates/header.php b/front/php/templates/header.php index 138e82ce..7ae6b294 100755 --- a/front/php/templates/header.php +++ b/front/php/templates/header.php @@ -139,8 +139,8 @@
-
-