Web Services Monitoring

NetXMS can monitor web services and REST APIs by sending HTTP requests and extracting data from JSON, XML, or text responses. This enables monitoring of cloud services, microservices, application APIs, and any system exposing an HTTP interface.

Overview

Web service monitoring in NetXMS provides:

  • HTTP/HTTPS request execution with configurable methods, headers, and authentication

  • Response data extraction using jq expressions, XPath, or regular expressions

  • Centralized web service definition with reuse across multiple DCIs

Web Service Definitions

Web service definitions are created in the management client and can be reused across multiple nodes and DCIs.

Creating a Web Service Definition

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

  2. Click Create

  3. Configure the web service properties

Properties

Property Description

Name

Descriptive name for the web service

Description

Optional free-form description

URL

HTTP/HTTPS URL to request (supports macro substitution)

HTTP request method

GET, POST, PUT, DELETE, PATCH

Request data

Request body for POST/PUT methods (sent as-is, without macro substitution)

Authentication

NONE, BASIC, DIGEST, NTLM, BEARER, ANY, or ANYSAFE

Verify peer’s certificate

Whether to validate the server’s SSL certificate

Verify host name in certificate

Whether to verify the hostname in the certificate

Follow location header in a 3xx response

Follow HTTP redirects (3xx responses)

Process response as plain text

Do not parse the response as JSON or XML; values are extracted with regular expressions

Cache retention time

How long to cache responses (seconds). Multiple DCIs querying the same service within this period reuse the cached response.

Request timeout

HTTP request timeout in seconds (0 = default of 10 seconds)

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

URL Macros

The URL and header values support macro substitution (the request body is sent as-is, without macro expansion):

Macro Description

%n

Name of the target object

%a

Primary IP address of the target node

%{attr}

Value of the custom attribute attr of the target node

%1 … %99

Arguments given in the DCI metric (serviceName(arg1,arg2):path)

The same macros are available in header values configured on the Headers property page.

Example URL with macros (deviceId is a custom attribute of the node):

https://api.example.com/v1/status/%{deviceId}

Data Extraction

JSON (jq)

For JSON responses, use jq expressions to extract values:

Given this response:

{
  "status": "healthy",
  "uptime": 86400,
  "metrics": {
    "cpu": 45.2,
    "memory": 72.8,
    "connections": 150
  }
}

jq examples:

jq expression Result

.status

healthy

.uptime

86400

.metrics.cpu

45.2

.metrics.connections

150

Legacy slash-separated paths (e.g. /metrics/cpu) are automatically converted to jq expressions.

XPath

For XML responses, use XPath expressions:

Given this response:

<system>
  <status>healthy</status>
  <metrics>
    <cpu>45.2</cpu>
    <memory>72.8</memory>
  </metrics>
</system>

XPath examples:

XPath Result

/system/status

healthy

/system/metrics/cpu

45.2

Regular Expressions

For text or HTML responses, use regex with capture groups:

uptime:\s+(\d+)\s+seconds

The first capture group becomes the extracted value.

Creating Web Service DCIs

  1. Create a DCI on the target node

  2. Set origin to Web Service

  3. In the Metric field, enter serviceName:path or serviceName(arg1,arg2):path, where serviceName is the name of the web service definition, the optional arguments are available in the URL and request body as %1–%99, and path is the extraction expression (jq, XPath, or regular expression)

  4. Set the data type according to the expected value

Multiple DCIs can use the same web service definition with different extraction paths, and the response caching prevents redundant HTTP requests.

Authentication

Supported authentication types: NONE, BASIC, DIGEST, NTLM, BEARER, ANY (a suitable supported method is selected automatically), and ANYSAFE (a suitable secure method is selected automatically).

Username and password configured in the web service definition are used by all types except BEARER, which instead sends the configured token in the Authorization: Bearer <token> header.

For services that expect an API key in a custom header, add a header on the Headers property page, e.g. name X-API-Key with the key as the value.

Monitoring HTTP Response Properties

HTTP response code, request duration, and certificate expiration are not available through web service DCIs. To monitor them, use the NETSVC subagent metrics with agent origin instead:

  • NetworkService.Status(url) and NetworkService.ResponseTime(url) — response check and timing

  • TLS.Certificate.ExpiresIn(hostname, port) and TLS.Certificate.ExpirationDate(hostname, port) — SSL/TLS certificate expiration

Troubleshooting

Connection Errors

  1. Requests are executed by the agent acting as web service proxy — the web service proxy configured for the node, or the NetXMS server’s own agent when none is configured. Verify the URL is accessible from that agent’s host.

  2. Check firewall and proxy settings

  3. Verify SSL certificate if HTTPS is used

  4. Check authentication credentials

Incorrect Values

  1. Test the URL manually (e.g., with curl) and verify the response format

  2. Verify the jq/XPath/regex expression against the actual response

  3. Check if the API response structure has changed

  4. Verify the data type matches the extracted value

Performance

  • Use response caching (cache timeout) when multiple DCIs query the same service

  • Increase request timeout for slow APIs

  • Assign a different web service proxy on the node if the default proxy cannot reach the API