External Metrics, Actions, and Data Providers

External commands (ExternalMetric, ExternalList, ExternalTable, and Action) support two execution forms:

Shell form passes the command through the system shell (/bin/sh -c on UNIX, cmd.exe /C on Windows):

Shell form supports pipes, redirections, variable expansion, and command substitution.

Exec form launches the executable directly without a shell:

Exec form requires the full path to the executable: it is resolved without a PATH search on any platform, and on Windows the file extension (e.g., .exe) must be included. On Windows, the elements are joined with spaces and re-split by the started program, so an element containing spaces reaches it as several arguments unless the value is wrapped in extra quotes (for example '"some text"').

The parameter name follows the standard NetXMS naming convention. Arguments passed from the DCI are substituted as $1 to $9; a number with no matching argument becomes an empty string. Any other $ is dropped, so write $$ for a literal $, for example $$HOME or awk '{print $$3}'.

Each ExternalMetric automatically provides a companion metric with the .ExitCode suffix that returns the exit code of the executed command:

For parameterized metrics, the .ExitCode suffix works the same way:

The .ExitCode metric is not available for ExternalList, BackgroundExternalMetric, ExternalMetricProvider, or ExternalDataProvider.

For metrics where you want to avoid blocking the data collection thread, use BackgroundExternalMetric. The command runs asynchronously at the given interval and the cached result is returned immediately:

The format is name:interval:command, with the execution interval in seconds. All three parts are required — an entry without an interval is not registered.

For metrics that are expensive to compute, use an external metric provider. The provider script runs periodically in the background and caches results for multiple metrics:

The format is command:interval[,timeout]. The interval is in seconds and defaults to 60 when omitted; the optional timeout is in milliseconds. The script must output key-value pairs, one per line:

Metrics from the provider are accessed by their names as printed by the script. Parameterized metrics are also supported (as shown with Disk.Health(sda) above).

When no per-provider timeout is given, ExternalMetricProviderTimeout applies (30000 ms by default). Setting it to 0 selects DefaultExecutionTimeout (5000 ms by default).

Define each check with ExternalCheck = name: command. The part before the first : is the check name, the rest is the command, in shell form or exec form (see Shell Form vs Exec Form). The directive can be repeated; NagiosPlugin is an alias with the same syntax.

Check names are not case-sensitive. Arguments cannot be passed from the DCI: put all plugin options in the command line and define a separate check for each set of options.

The plugin runs when one of its metrics is requested, not in the background. One run serves all metrics of the check: the result, including a failed run, is reused for ExternalCheckCacheTimeout seconds (default 5), so several DCIs on the same check collected in the same polling cycle start the plugin once. ExternalCheckTimeout limits the run time in milliseconds; when it is 0 or not set, ExternalMetricTimeout applies.

The cache lifetime counts from the moment the plugin starts, not from when it finishes. A plugin that runs for ExternalCheckCacheTimeout seconds or longer stores a result that has already expired, and each DCI on the check starts it again, one after another. Set ExternalCheckCacheTimeout above the plugin’s run time and above ExternalCheckTimeout; with the defaults (5 s cache, 5 s timeout) a timed-out run is not reused.

If the plugin cannot be started or does not finish in time, all metrics of the check return an error until the cached result expires. In shell form the shell itself always starts, so a missing or non-executable plugin is not an error: it shows up as the shell’s exit code (127 or 126 from /bin/sh, 9009 from CMD.EXE) in ExternalCheck.Status, with the shell’s error message as the status text. In exec form the agent returns an error on Linux and Windows; on other UNIX systems the status is 127.

An unknown check name, or a label that is not in the plugin’s performance data, returns "no such instance". Performance data entries without a numeric value, such as U (unknown), are skipped. Full entries are in Agent Internal Metrics and List and Table Metrics.

With the disk check above, check_disk prints a line like:

Useful DCIs on the node:

External data providers use INI-style section syntax:

The agent auto-detects the output format:

Set ForcePlainTextParser = true to override auto-detection.

Without any additional configuration, the provider name itself becomes a parameterized metric. Pass the extraction query as the parameter:

Suppose the command outputs:

You can query values directly:

Any valid jq expression can be used as the parameter (for JSON output), or XPath query (for XML), or regex (for text).

Define named metrics to create fixed metric names with predefined extraction queries:

Each metric entry maps a metric name to an extraction query. Optional .description and .dataType suffixes set the metric description and data type respectively.

Parameterized named metrics are supported (v6.1+):

Define list metrics to extract arrays from the cached output:

Each entry maps a list name to an extraction query that returns multiple values.

The following data types can be used in .dataType and ColumnType settings:

The type name null (no data type) is also accepted, as are the legacy aliases int and uint for int32 and uint32.

A script /opt/scripts/app_metrics.sh outputs JSON:

Agent configuration:

This creates metrics like App.Version, App.Uptime, App.Connections.Active, App.Connections(idle), App.Queue(inbound), and lists like App.QueueNames.

The EnvironmentFile directive loads environment variables for the agent process from a separate file. Since 6.2.1

Use one KEY=VALUE per line in the environment file. Leading and trailing whitespace is trimmed; blank lines and lines starting with # are ignored. Values are read literally, without quoting or expansion. Repeat EnvironmentFile to load multiple files. Configuration dumps show only the file paths. Protect files containing secrets with filesystem permissions.

The server can push environment variables to the agent for use by externally executed commands. The AcceptedEnvironmentVariables parameter defines which server-provided variables the agent accepts, as a repeatable name pattern:

When no patterns are configured, the defaults are NX_* and NETXMS_*. The literal value none clears the list, so no server-provided variables are accepted.

This parameter only filters variables pushed by the server — it does not sanitize the environment that child processes inherit from the agent process.

The preferred configuration format uses INI-style sections:

Parameterized tables use (*) in the section name:

The Separator parameter supports escape sequences:

The older single-line format is still supported:

The format is Name:options:command where options is a semicolon-separated list of key=value pairs. Supported option keys: instanceColumns, separator, description, mergeSeparators, backgroundPolling, pollingInterval, timeout, defaultColumnDataType.

A script outputs comma-separated data with a header row:

Configuration:

The following actions are available when EnableActions = yes (the default):

Platform subagents also register the following actions:

Use nxagentd with control options for runtime management:

From the server, use nxget to query any agent metric:

Use nxaction to execute an action remotely: