Grafana Integration

NetXMS integrates with Grafana through a dedicated data source plugin, allowing you to build Grafana dashboards using NetXMS monitoring data. This integration is useful for teams that standardize on Grafana for visualization across multiple monitoring systems.

Prerequisites

  • NetXMS server with the web API enabled (see below)

  • Grafana 10.4.0 or later

  • Network connectivity between Grafana and the NetXMS web API port

Enabling the Web API

The web API is built into the NetXMS server and is provided by the webapi server module. To enable it, load the module in netxmsd.conf and restart the server:

Module = webapi

The API listener is configured in the [WEBAPI] section of netxmsd.conf. By default it serves plain HTTP on port 8000 and accepts connections on the loopback interface only. When Grafana runs on a different host, set Address to any, *, or an explicit IP address so the listener accepts remote connections:

[WEBAPI]
Address = any
Port = 8000

An optional TLS listener can be enabled (port 8443 by default); it is terminated by an external reproxy process, which is bundled with the server on Windows but must be installed separately on Linux. The recommended setup is to place a TLS-offloading reverse proxy (nginx, Caddy, Traefik, etc.) in front of the HTTP port.

Installing the Data Source Plugin

Plugin releases are published on the GitHub releases page as a zip archive. Unzip the archive into the Grafana plugins directory and restart Grafana:

cd /var/lib/grafana/plugins
unzip radensolutions-netxms-datasource-<version>.zip
systemctl restart grafana-server

If using an unsigned plugin build, add it to the allow_loading_unsigned_plugins setting in grafana.ini:

[plugins]
allow_loading_unsigned_plugins = radensolutions-netxms-datasource

Configuring the Data Source

  1. In NetXMS, issue an authentication token for the account Grafana will use: navigate to Configuration > Users and groups, right-click the user, and select Issue authentication token…​

  2. Open Grafana and navigate to Connections > Data sources

  3. Click Add new data source and select "NetXMS"

  4. Configure the connection:

Setting Description

API address

Base URL of the NetXMS web API (e.g., http://netxms.example.com:8000)

API Key

Authentication token issued in NetXMS

  1. Click Save & Test to verify the connection

This is a backend plugin: all requests to the NetXMS web API are made by the Grafana server process, and the API key is stored encrypted in Grafana.

Create a dedicated NetXMS user account for Grafana with read-only access to the required objects. The token carries the permissions of the user it was issued for.

Building Dashboards

Query Editor

The first field in the query editor is Query Type:

Query type Description

Alarms

Active alarms, optionally limited to a subtree of the object tree

Summary Tables

Data from a DCI summary table configured on the server

Object Queries

Results of an object query configured on the server

DCI value

Historical values of a single DCI

Object Status

Status of objects under the selected root object

Depending on the query type, additional fields appear. All of them are dropdowns populated from the NetXMS server:

Field Description

Root object

Object that scopes the query. Optional for Alarms and Object Queries, required for the other query types

DCI

The DCI to retrieve values from (DCI value only; the list is filtered by the selected root object)

Summary table

The DCI summary table to query (Summary Tables only)

Object query

The object query to execute (Object Queries only)

Query parameters

Optional input fields for the object query, entered in a plain text area as a JSON array of key-value pairs (Object Queries only). The plugin currently sends them in a form the server ignores, so they have no effect (grafana-datasource#4)

Displaying Alarms

To display active alarms, add a panel with the Table visualization, select the NetXMS data source, and set the query type to Alarms. Optionally set a root object to limit the table to alarms from a subtree of the object tree.

Example Dashboard

A typical NetXMS Grafana dashboard might include:

  • CPU and memory graphs for a group of servers

  • Network interface utilization charts

  • Active alarm table

  • Node status overview using stat panels

  • Disk usage bar gauges

Example panel query configuration:

Query Type: DCI value
Root object: server01
DCI: CPU: usage (average last minute)

Permissions and Access Control

The Grafana data source inherits the permissions of the NetXMS user account the API key was issued for. To restrict what data is visible in Grafana:

  • Create a dedicated NetXMS user for Grafana

  • Assign read-only access to specific object containers

  • Use NetXMS access control to limit visibility

Troubleshooting

Connection Failed

  • Verify the web API is enabled: Module = webapi must be present in netxmsd.conf, and the server log should contain a "Web API initialized" message on startup

  • If Grafana runs on a different host, make sure Address is set in the [WEBAPI] section — by default the API listens on the loopback interface only

  • Check firewall rules between Grafana and the NetXMS server API port (default 8000)

  • Verify the API address includes the correct protocol and port

  • Verify the API key is valid and not expired

No Data Shown

  • Verify the NetXMS user has access to the queried objects

  • Check that DCIs are actively collecting data

  • Verify time range in Grafana matches available data

  • Test the same query in the NetXMS management console

Plugin Not Loading

  • Check Grafana logs: journalctl -u grafana-server

  • Verify plugin is in the correct directory

  • Ensure plugin version is compatible with your Grafana version

  • Check unsigned plugin allowlist if applicable

Alternative: Infinity Plugin with REST API

If the dedicated NetXMS data source plugin is not available or does not meet your requirements, you can use the Grafana Infinity plugin with the NetXMS REST API directly.

Prerequisites

  1. Ensure the web API is enabled on the NetXMS server: the webapi module must be loaded (Module = webapi in netxmsd.conf). The API listener is enabled by default on port 8000. To change the port or disable the listener, edit the [WEBAPI] section in netxmsd.conf:

    Module = webapi

[WEBAPI]
Enable = true
Port = 8000

  2. Install the Infinity plugin in Grafana:

    grafana-cli plugins install yesoreyeram-infinity-datasource
systemctl restart grafana-server

Configuring the Infinity Data Source

  1. Create a new data source of type Infinity

  2. Set authentication to Bearer Token

  3. Generate a token in NetXMS: open the management console, navigate to Configuration > Users and groups, right-click your API user, and select Issue authentication token…​

  4. Paste the token into the Infinity data source configuration

  5. Add the NetXMS API address to Allowed Hosts

  6. Set the health check URL to /v1/status

Available API Endpoints

The following REST API endpoints are available for use with the Infinity plugin:

Method Endpoint Description

POST

/v1/grafana/infinity/alarms

Active alarms. A JSON body is required; the rootObjectId field in it is optional: {} or {"rootObjectId": <id>}

POST

/v1/grafana/infinity/object-query

Object query results. Body: {"rootObjectId": <id>, "queryId": <id>}

POST

/v1/grafana/infinity/summary-table

Summary table data. Body: {"rootObjectId": <id>, "tableId": <id>}

GET

/v1/objects/<id>/data-collection/<dciId>/history

DCI history values. Query params: timeFrom, timeTo

GET

/v1/grafana/objects/<id>/dci-list

DCIs configured on an object

POST

/v1/grafana/objects-status

Status of objects under a root object

GET

/v1/grafana/object-list

Objects usable as query roots; filter query parameter: dci, alarm, query, or summary

GET

/v1/grafana/summary-table-list

Configured DCI summary tables

GET

/v1/grafana/query-list

Configured object queries

DCI History Panels

To create time-series panels using DCI history:

  1. Add a new panel in Grafana

  2. Select the Infinity data source

  3. Configure:

    Setting Value

    Type

    JSON

    Parser

    Backend

    Source

    URL

    Format

    Data Frame

    Method

    GET

    URL

    http://<server>:8000/v1/objects/<objectId>/data-collection/<dciId>/history

  4. Add URL query parameters to pass the Grafana time range:

    Parameter Value

    timeFrom

    $__from/1000

    timeTo

    $__to/1000

  5. Set the root selector to values

  6. Configure columns:

    • timestamp — type Time (ISO format)

    • value — type Number

Grafana time range variables ($from, $to) return milliseconds. The NetXMS API expects seconds, so divide by 1000.
The values/timestamp+value column mapping applies to raw-tier responses. With aggregation enabled and long time ranges (or when maxDataPoints is set), the response contains avg, min, max, and sampleCount columns plus aggregated: true and tierServed fields instead of value — map the aggregate columns accordingly.

Alternatively, you can embed the time parameters directly in the URL using the :date:seconds format:

http://<server>:8000/v1/objects/<objectId>/data-collection/<dciId>/history?timeFrom=${__from:date:seconds}&timeTo=${__to:date:seconds}

Example: CPU Usage Graph

Create a time-series panel showing CPU usage from a specific node:

Setting Value

Format

Data Frame

Method

GET

URL

http://netxms.example.com:8000/v1/objects/108/data-collection/183/history

URL Query: timeFrom

$__from/1000

URL Query: timeTo

$__to/1000

Root

values

Configure columns: timestamp as Time (ISO format), value as Number. To show multiple metrics (e.g., user CPU, system CPU, I/O wait), add additional queries in the same panel with different DCI IDs.

Example: Log Monitoring Table

Display log monitoring data (e.g., authentication errors captured by the LogWatch subagent) as a table:

Setting Value

Format

Data Frame

Method

GET

URL

http://netxms.example.com:8000/v1/objects/108/data-collection/32466/history

URL Query: timeFrom

$__from/1000

URL Query: timeTo

$__to/1000

Root

values

This works with any DCI type including push DCIs populated by log monitoring policies.

Object Query Panels

To display object query results as a table:

  1. Add a table panel with the Infinity data source

  2. Set method to POST

  3. Set the URL to http://<server>:8000/v1/grafana/infinity/object-query

  4. Set the body:

    {
  "rootObjectId": 2,
  "queryId": 1,
  "inputFields": {
    "fieldName": "value"
  }
}
Grafana sorts table columns alphabetically by default. Use Grafana’s Organize fields transformation to arrange columns in the desired order.

Example: Agent Information Query

The following NXSL object query script displays agent information for all nodes with an agent. Create this query in NetXMS under Configuration > Object Queries, then reference it by ID in Grafana.

with
  nodeName (name = "Node name", order = "asc") = {
    $node.name
  },
  agentVersion (name = "Agent Version") = {
    $node.agentVersion
  },
  agentUnreachable (name = "Agent unreachable") = {
    $node.state == NodeState::AgentUnreachable
  },
  lastCommTime (name = "Last connection time") = {
    DateTime($node.lastAgentCommTime).format("%Y-%m-%d %H:%M")
  },
  tunnelConnected (name = "Tunnel connection") = {
    $node.tunnel != null
  },
  hasUserAgent (name = "Has user agent") = {
    $node.hasUserAgent
  },
  platformName (name = "Platform name") = {
    $node.platformName
  }
(type == NODE) and $node.isAgent

Configure the Infinity panel as POST to /v1/grafana/infinity/object-query with body {"queryId": 2}.

Summary Table Panels

To display a summary table in Grafana:

  1. Add a table panel with the Infinity data source

  2. Set method to POST

  3. Set the URL to http://<server>:8000/v1/grafana/infinity/summary-table

  4. Set the body with both rootObjectId and tableId (both required):

    {
  "rootObjectId": 2,
  "tableId": 5
}

The API returns the same data as the NetXMS summary table view. Use Grafana’s Organize fields transformation to arrange columns in the desired order.

Next Steps