Web Service Data Collection

NetXMS can collect data from HTTP/HTTPS endpoints, enabling monitoring of REST APIs, JSON services, XML feeds, and web application health endpoints.

Web service requests are not executed by the server itself — they are executed by a NetXMS agent acting as web service proxy. By default, the agent on the management server node is used; a different proxy can be selected per node on the Web Services property page of the node. The proxy agent must have EnableWebServiceProxy = yes in its configuration.

For DCI configuration concepts and properties, see DCI Reference.

Web Service Definitions

Web service definitions specify how to connect to an HTTP endpoint. They are configured globally and can be referenced by DCIs on any node.

Creating a Web Service Definition

  1. In the management client, go to Configuration > Web Service Definitions

  2. Create a new definition and configure its properties:

Property Description

Name

Descriptive name for the web service (used in DCI metric names). Should not contain /, ,, :, ', ", (, ), {, or } characters, as they conflict with the service:path metric syntax

Description

Optional free-form description of the definition

URL

Full URL of the endpoint; supports macro substitution (see below)

HTTP request method

GET, POST, PUT, PATCH, DELETE

Request data

Request body for POST/PUT/PATCH requests (sent as-is, without macro expansion)

Authentication

Type (NONE, BASIC, DIGEST, NTLM, BEARER, ANY, ANYSAFE) plus login and password. For BEARER, enter the token in the Password field.

Cache retention time

How long the proxy agent caches the response (seconds)

Request timeout

Maximum time to wait for a response (seconds; 0 = default of 10 seconds)

Verify peer’s certificate

Validate the TLS certificate (default: on)

Verify host name in certificate

Verify the hostname matches the certificate (default: on)

Follow location header in a 3xx response

Follow HTTP redirects

Process response as plain text

Force text parsing even if the response looks like JSON/XML

Custom HTTP headers are configured on the separate Headers property page of the definition as name/value pairs.

Macros in URL and Headers

The URL and header values are expanded using standard object macros in the context of the DCI’s node (the request data is sent as-is, without macro expansion):

  • %n — node name

  • %a — node primary IP address

  • %u — node primary IP address in URL-safe form (IPv6 addresses wrapped in […​])

  • %{attribute} — node custom attribute value

  • %[script] — value returned by a script from the script library

  • %1 …​ %99 — arguments from the DCI metric name (see below)

Example URL: https://%u:8080/api/health

Web Service DCIs

Creating a Web Service DCI

  1. Open the node’s Data Collection view and create a new DCI

  2. Set Origin to Web Service

  3. In the Metric field, enter the web service definition name, a colon, and the document path:

    service:path
service(argument1,argument2):path

    Arguments in parentheses are optional; they are substituted into the definition’s URL and headers as %1 …​ %99.

  4. Set the data type and polling interval

The interpretation of path depends on the response document type: a jq expression for JSON, an XPath expression for XML, or a regular expression for plain text.

JSON Extraction

JSON values are extracted with jq expressions:

my_service:.status
my_service:.metrics.cpu
my_service:.servers[0].name

Example: if the API returns:

{
  "status": "healthy",
  "metrics": {
    "cpu": 45.2,
    "requests_per_second": 1250
  }
}

DCIs to extract these values:

  • my_service:.status → healthy (String DCI)

  • my_service:.metrics.cpu → 45.2 (Float DCI)

  • my_service:.metrics.requests_per_second → 1250 (Integer DCI)

A legacy slash-separated form (my_service:/metrics/cpu) is also accepted and converted to a jq expression automatically.

XML Extraction

Use XPath expressions for XML responses:

my_service:/root/status
my_service://server[@name='web1']/load

Regular Expression Extraction

For plain text responses, the path is a regular expression with a capture group; the first capture group is used as the DCI value:

my_service:Status: (\w+)
my_service:CPU Usage: ([0-9.]+)%

The document type is detected from the first non-space character of the response body: < selects XML, { or [ selects JSON, anything else is treated as plain text. Plain text parsing can also be forced with the Process response as plain text option in the definition.

Response Caching

When multiple DCIs reference the same web service definition, the proxy agent caches the HTTP response to avoid redundant requests. The cache retention time is set in the web service definition; responses are cached per effective URL. Only GET requests are cached — requests with other methods are never cached and invalidate an existing cache entry.

For example, if 10 DCIs extract different fields from the same endpoint with a 60-second cache retention, one HTTP request is made per 60 seconds and all 10 values are extracted from the cached response.

TLS Certificate Verification

By default, the proxy agent verifies the endpoint’s TLS certificate and host name. For self-signed certificates in test environments, verification can be disabled in the web service definition.

Disabling certificate verification in production environments is not recommended.

Error Handling

  • Transport-level failures (DNS resolution, connection, TLS, timeout) result in a data collection error for the DCI (visible in Last Values); the DCI value is not updated

  • HTTP error responses (non-2xx status codes) do not produce a communication error — the agent returns an empty document, so the DCI receives a "no such instance" collection error

  • A successful response that does not contain the requested path also results in a "no such instance" collection error

  • A malformed metric name or unknown definition name makes the DCI Not supported

Troubleshooting

DCI Returns Empty or Incorrect Value

  • Verify the web service URL is correct and accessible from the proxy agent (by default, the agent on the management server)

  • Test the jq/XPath expression against the actual response

  • Check if the response format has changed (API version update)

  • Raise the websvc debug tag on the proxy agent to see request execution details

Authentication Failures

  • Verify credentials in the web service definition

  • Check if tokens have expired

  • Ensure the correct authentication method is selected

Timeout Errors

  • Increase the request timeout in the web service definition

  • Check network connectivity between the proxy agent and the endpoint

  • Verify the endpoint is not rate-limiting requests