Agent Data Collection

The NetXMS agent (nxagentd) provides the richest set of monitoring metrics. It runs on managed hosts and exposes hundreds of built-in metrics covering system resources, processes, file systems, and more.

For a complete list of built-in agent metrics, see Agent Metrics Reference. For external metrics configuration, see External Metrics, Actions, and Data Providers.

Agent Metrics

Agent metrics are the primary way to collect data from agent-equipped hosts. Each metric is identified by a name and optionally takes arguments.

Metric Naming Convention

Metrics follow a hierarchical naming scheme:

Category.Subcategory.Metric(argument)

Examples:

  • System.CPU.Usage — total CPU usage percentage

  • System.CPU.Usage(3) — CPU usage for core 3

  • FileSystem.FreePerc(/) — free space percentage on /

  • Process.Count(httpd) — number of httpd processes

  • Net.Interface.BytesIn(eth0) — bytes received on eth0

Common Metric Categories

Category Description

System.CPU.*

CPU usage, load average, count, model

System.Memory.*

Physical and virtual memory usage

System.Uptime

System uptime in seconds

FileSystem.*

Disk space, inodes, mount points

Net.Interface.*

Network interface statistics (bytes, packets, errors)

Process.*

Process count, memory usage, CPU time

System.IO.*

Disk I/O statistics

System.Hostname

System hostname

System.PlatformName

OS platform identifier

Discovering Available Metrics

To find metrics supported by an agent, use the Agent Explorer:

  1. Right-click a node and select Agent explorer

  2. Browse or search the available metrics

The metric selection dialog (Select button on the General page of DCI properties) also lists the metrics available on the agent.

You can also use the nxget command-line tool:

nxget -I node_address

This lists all metrics supported by the agent on the target host.

Lists and Tables

In addition to single-value metrics, agents provide lists and tables.

Agent Lists

Agent lists return a collection of values — one per line. They are used for enumeration (e.g., list of all file systems, network interfaces, or running processes).

Example list metric: FileSystem.MountPoints returns all mount points on the system.

Lists are commonly used with instance discovery to automatically create DCIs for each discovered item.

Agent Tables

Agent tables return structured data with named columns and multiple rows. They are used for table DCIs that display detailed information.

Example table metrics:

  • System.Processes — detailed process list with PID, name, CPU, memory

  • FileSystem.Volumes — file system details with size, free space, type

  • Net.Interfaces — network interfaces with IP address, MAC, status

External Metrics

You can extend agent capabilities by configuring external metrics — custom metrics collected by running external scripts or programs.

Configuration

Define external metrics in the agent configuration file (nxagentd.conf):

ExternalMetric = MyApp.Status:python3 /opt/scripts/check_myapp.py
ExternalMetric = MyApp.ResponseTime:curl -s -o /dev/null -w "%\{time_total}" https://localhost:8080/health

The agent runs the command and uses its standard output as the metric value. The old ExternalParameter* spellings (ExternalParameter, ExternalParameterTimeout, ExternalParametersProvider) are deprecated but still accepted.

External Lists

External lists work similarly but expect multiple lines of output:

ExternalList = MyApp.Endpoints:/opt/scripts/list_endpoints.sh

External Tables

External tables return delimited data with a header row. The default column separator is a comma; set separator=\t in the options for tab-separated output.

ExternalTable = MyApp.Sessions:instanceColumns=SESSION_ID:/opt/scripts/sessions.sh

The syntax is name:options:command, where options are semicolon-separated name=value pairs (instanceColumns, description, separator, and others).

Execution Control

Setting Description

ExternalMetricTimeout

Maximum execution time for external metric commands, in milliseconds (default: 5000)

ExternalMetricProvider

Command executed by the agent at a fixed interval; its output is parsed as metric=value lines providing values for multiple metrics. Syntax: command:interval (interval in seconds, default 60; timeout controlled by ExternalMetricProviderTimeout, default 30 seconds)

Background Polling Metrics

For metrics that take a long time to collect, the agent supports background polling. Background metrics are polled independently of DCI requests and their values are cached.

BackgroundExternalMetric = slow.metric:60:/opt/scripts/slow_check.sh

The syntax is metric_name:polling_interval_seconds:command. When the server requests this metric, the agent returns the cached value instead of waiting for the script to complete.

Actions

Agent actions are commands that can be triggered remotely from the server. They are used in event processing rules to execute remediation scripts.

Action = restart.service:systemctl restart $1
Action = clear.cache:rm -rf /tmp/cache/*

Action arguments are referenced as $1 …​ $9 in the command line.

Actions are not used for data collection but are configured alongside metrics in the agent configuration.

Agent Proxying

When a target host cannot be reached directly by the server, another agent can act as a proxy. The proxy agent forwards data collection requests and returns results to the server.

Configure the proxy on the target node’s properties in the management client:

  1. Right-click the node and select Properties

  2. Go to the Polling tab

  3. Set Agent proxy to the proxy node

The proxy agent must have the EnableProxy option set in its configuration.

See Agent Proxies for details.

Performance Considerations

  • Native agent metric collection is lightweight — values are read directly from the operating system

  • External metrics have higher overhead due to process spawning; use background polling for expensive scripts

  • For high-frequency monitoring, consider using the Push origin instead of polling

  • The agent can collect and cache DCI values locally while disconnected from the server — controlled by the Agent cache mode property on the node or DCI (the server-wide default comes from the Agent.DefaultCacheMode server configuration variable, off by default)

  • On reconnection, cached values older than the DataCollection.OfflineDataRelevanceTime server configuration variable (default: 86400 seconds) do not activate thresholds

Troubleshooting

DCI Shows "Not Supported"

The metric is not available on the target agent. Common causes:

  • The metric requires a subagent that is not loaded

  • The metric is platform-specific (e.g., Windows-only metrics on a Linux host)

  • The metric name or arguments are incorrect

Use nxget to test metric availability:

nxget node_address "System.CPU.Usage"

Stale or Missing Values

  • Verify agent connectivity: check Agent Status on the node’s overview

  • Check agent logs for errors: /var/log/nxagentd on UNIX-like systems; on Windows, agents installed with the standard installer log to the Windows Event Log (LogFile = {syslog}), while the compiled-in default is C:\nxagentd.log

  • Verify the metric works by querying the agent from the server using nxget <agent_address> "metric_name"

External Metric Timeout

If an external metric frequently times out:

  • Increase ExternalMetricTimeout in the agent configuration

  • Convert to a background polling metric for expensive scripts

  • Optimize the script itself