Skip to content

Metrics API Endpoint

The /metrics endpoint exposes Prometheus-compatible metrics for NetAlertX, including aggregate device counts and per-device status.

Endpoint Details

  • GET /metrics → Returns metrics in plain text.
  • Host: NetAlertX server
  • Port: As configured in GRAPHQL_PORT (default: 20212)

Example Output

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 Overview

1. Aggregate Device Counts

Metric Description
netalertx_connected_devices Devices currently connected
netalertx_offline_devices Devices currently offline
netalertx_down_devices Down/unreachable devices
netalertx_new_devices Recently detected devices
netalertx_archived_devices Archived devices
netalertx_favorite_devices User-marked favorites
netalertx_my_devices Devices associated with the current user

2. Per-Device Status

Metric: netalertx_device_status Each device has labels:

  • device: friendly name
  • mac: MAC address (or placeholder)
  • ip: last recorded IP
  • vendor: manufacturer or "None"
  • first_connection: timestamp of first detection
  • last_connection: most recent contact
  • dev_type: device type/category
  • device_status: current status (Online, Offline, Archived, Down, …)

Metric value is always 1 (presence indicator).

Querying with curl

curl 'http://<server_ip>:<GRAPHQL_PORT>/metrics' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Accept: text/plain'

Replace placeholders:

  • <server_ip> – NetAlertX host IP/hostname
  • <GRAPHQL_PORT> – configured port (default 20212)
  • <API_TOKEN> – your API token

Prometheus Scraping Configuration

scrape_configs:
  - job_name: 'netalertx'
    metrics_path: /metrics
    scheme: http
    scrape_interval: 60s
    static_configs:
      - targets: ['<server_ip>:<GRAPHQL_PORT>']
    authorization:
      type: Bearer
      credentials: <API_TOKEN>

Grafana Dashboard Template

Sample template JSON: Download