Exposing Metrics to Prometheus

Goal: Let a Prometheus server scrape NSClient++'s built-in metrics (CPU, memory, uptime, network, temperature, predefined performance counters, …) so they appear alongside everything else in Grafana / Alertmanager.

This works the same on Windows and Linux — the same modules, endpoint, user/role setup and scrape configuration apply on both. The platforms differ only in which metric families they emit (see Available Metrics below).

This scenario is the inverse of the rest of the integration scenarios: NRPE/NSCA/NRDP/Icinga 2 send check results to a monitoring server, but Prometheus scrapes raw metrics on its own schedule. The two patterns are complementary — you can run both on the same agent.

---

How It Works

NSClient++'s WEBServer module exposes an OpenMetrics endpoint at:

GET https://<agent>:8443/api/v2/openmetrics

Authenticated requests return the current metrics one-per-line in OpenMetrics text format. Prometheus is configured to scrape that URL on its usual interval (15s, 30s, 1m, …).

flowchart LR
    P[Prometheus] -->|HTTP scrape| W[NSClient++<br/>WEBServer<br/>/api/v2/openmetrics]
    W --- CS[CheckSystem]
    W --- CD[CheckDisk]
    W --- PC[Predefined counters]

Metrics are aggregated by WEBServer from whichever modules happen to be loaded — load CheckSystem to get CPU/memory/uptime/network, load CheckDisk to add drive metrics, and so on.

---

Prerequisites

[/modules]
WEBServer   = enabled    ; serves the /api/v2/openmetrics endpoint
CheckSystem = enabled    ; provides CPU / memory / uptime / network metrics
CheckDisk   = enabled    ; (optional) drive metrics

You also need:

• A reachable IP/hostname and TCP 8443 open from the Prometheus server.
• Credentials for the scrape (see Step 2 below).

---

Step 1 — Enable the Web Server

If you haven't already, run the helper:

nscp web install

This sets a password, opens 8443 from 127.0.0.1, and writes the role configuration. Restart the service:

nsclient service --restart

For the full setup (TLS certificate, custom port, allowed hosts), see Web Interface — the Prometheus endpoint shares the same web server, so anything that page covers applies here too.

---

Step 2 — Create a Scrape User

Reading the OpenMetrics endpoint requires the openmetrics.list grant. The built-in full role has * (everything), so the admin user can scrape without further configuration — but a dedicated user with only the metrics grant is better practice.

[/settings/WEB/server/roles]
prometheus = openmetrics.list,login.get

[/settings/WEB/server/users/prometheus]
role     = prometheus
password = <strong-random-password>

Restart NSClient++ for the new role/user to take effect.

---

Step 3 — Verify the Endpoint

From the agent (or anywhere allowed to reach it):

curl -k -u prometheus:<password> https://<agent>:8443/api/v2/openmetrics

Expected output is one metric per line, <name> <value>. On a Windows host:

system_mem_commited.avail 12592123904
system_mem_commited.total 17175158784
system_mem_commited.% 73
system_cpu_total.idle 95
system_cpu_total.total 5
system_uptime_ticks.raw 84135

On a Linux host:

system_cpu_total.idle 97.8293
system_cpu_total.user 1.19519
system_cpu_total.kernel 0.975472
system_mem_physical.total 1.6554e+10
system_mem_physical.used 2.78311e+09
system_mem_swap.% 26
system_uptime_ticks.raw 434344
system_network_eth0.received 343
system_network_eth0.sent 131

If you get HTTP 401, the credentials or role grant are wrong; if you get a TLS error, see "TLS / self-signed certificate" below.

---

Step 4 — Configure Prometheus

Add a scrape job to prometheus.yml:

scrape_configs:
  - job_name: nsclient
    scrape_interval: 30s
    metrics_path: /api/v2/openmetrics
    scheme: https
    tls_config:
      # NSClient++ generates a self-signed cert by default. Either point
      # `ca_file` at the CA you used for `nscp web install --certificate`,
      # or set `insecure_skip_verify: true` for a quick start (not for
      # production).
      insecure_skip_verify: true
    basic_auth:
      username: prometheus
      password: <strong-random-password>
    static_configs:
      - targets:
          - win-server-01.example.com:8443
          - linux-server-01.example.com:8443

Windows and Linux agents can share the same scrape job — the endpoint, port and authentication are identical.

Reload Prometheus and check Status → Targets — the job should go green within one scrape interval.

---

Available Metrics

The exact set depends on which modules are loaded and on the platform. Available on both platforms from CheckSystem:

Bundle	Examples
system_cpu_*	total.idle, total.user, total.kernel, plus per-core variants
system_mem_*	families differ per platform — see below
system_uptime_*	ticks.raw, boot.raw
system_network_<nic>.*	received, sent, total (bytes/s per interface)
system_temperature_*	thermal sensors (WMI/ACPI on Windows, sysfs thermal/hwmon on Linux)
system_battery_*	charge/health, on machines that have a battery
system_cpu_frequency_*	current/max clock per core, where exposed
system_process_history_*	per-executable times_seen / currently_running (opt-in, below)

Add CheckDisk (either platform) and you also get disk_io_<device>.* (throughput, IOPS, queue length, busy time) and disk_free_<drive>.* (total/free/used and percentages).

Platform differences to be aware of:

• Memory families follow what the OS exposes: Windows publishes commited / physical / page / virtual, Linux publishes physical / cached / swap.
• Per-core CPU naming: Linux normalises core names to core_0, core_1, …; Windows names them core 0 (with a space), which is not a valid OpenMetrics identifier — strict parsers may drop the per-core lines there (the total aggregate is always parseable on both).
• PDH counters (system_metrics_*) are Windows-only: predefine them in [/settings/system/windows/counters/<name>] (see Performance Counter (PDH) Monitoring) and they appear on the endpoint automatically. There is no Linux equivalent.
• Process history is opt-in on both platforms — set process history = true under [/settings/system/windows] or [/settings/system/unix] respectively.
• Hardware metrics (temperature, battery, CPU frequency) depend on what the host exposes: virtual machines and WSL typically publish none, which is normal.

---

Common Gotchas

Metric names contain dots

NSClient++ emits names like system_mem_commited.avail. Strict OpenMetrics / Prometheus identifiers should match [a-zA-Z_:][a-zA-Z0-9_:]*, which doesn't include .. Recent Prometheus versions tolerate it; older ones may reject the line. If your scrape drops metrics with dots, rewrite them with metric_relabel_configs:

    metric_relabel_configs:
      - source_labels: [__name__]
        regex: '(.*)\.(.*)'
        target_label: __name__
        replacement: '${1}_${2}'

TLS / self-signed certificate

Out of the box nscp web install generates a self-signed certificate. Production options:

• Point Prometheus' ca_file at your internal CA and replace the cert with one signed by it (the nscp web install --certificate ... flag, or the cert-management UI in the web interface).
• Or use insecure_skip_verify: true in tls_config — fast to set up but doesn't authenticate the agent. Acceptable on a private network you trust; not on the open internet.

allowed hosts blocks the scrape

Without an explicit allow list, the WEBServer accepts only 127.0.0.1. If Prometheus runs on a different host, add it:

[/settings/default]
allowed hosts = 127.0.0.1, 10.0.0.0/24

Or per-module under [/settings/WEB/server].

No # HELP / # TYPE lines

The endpoint emits only <name> <value> pairs — no metadata. Most metrics are gauges; tag them as such on the Prometheus side if you need explicit type metadata, or use metric_relabel_configs to project them into separate series.

Strings are skipped

Some bundles include string-typed entries (e.g. system_uptime_uptime is the human-readable "1d 12:30"). These don't appear on the OpenMetrics endpoint — only numeric gauges do. Use the JSON /api/v2/metrics endpoint if you need the strings.

---

Next Steps

• Web Interface — full WEBServer setup including TLS, port, and user/role management.
• Performance Counter (PDH) Monitoring — predefine custom PDH counters; they appear on the OpenMetrics endpoint automatically.
• REST API — the same web server also exposes /api/v2/queries, /api/v2/metrics (JSON), logs, and module management.
• Reference: WEBServer — every web server setting in detail.