Managing DCIs

This guide covers common tasks for creating, configuring, and managing Data Collection Items in NetXMS.

For an overview of data collection concepts, see Data Collection Concepts. For DCI property details and data type reference, see DCI Reference.

Creating a DCI

DCIs can be created in several ways:

  • Manually on a specific node through the management client

  • On a template for automatic deployment to bound nodes (see DCI Templates)

  • Via the DCI import/export mechanism

  • Through the NetXMS API

To create a DCI manually:

  1. Open the node in the management client

  2. Navigate to the Data Collection view — it opens showing last collected values

  3. Toggle Edit mode (Ctrl+M) to see and edit the DCI configuration

  4. Right-click and select New parameter…​ (or New table…​ for a table DCI)

  5. Configure the DCI properties (origin, metric, data type, polling interval)

  6. Click OK to save

Configuring Transformation Scripts

DCI values can be transformed before storage using NXSL scripts. This is configured on the Transformation page of the DCI properties.

The transformation is a two-step process:

  1. Delta calculation is applied first (if configured) — see Delta Calculation Methods

  2. Custom transformation script runs on the result

The transformation script has access to:

  • $1 — the value after delta calculation (or raw value if delta is set to None)

  • $dci — reference to the current DCI object

  • $isCluster — true if the DCI is collected on a cluster object

  • $node — reference to the current node object (null if the owner is not a node)

  • $object — reference to the object owning the DCI

For table DCIs, $1 is an object of type Table.

Common use cases:

  • Convert units (bytes to megabytes, Celsius to Fahrenheit)

  • Extract a value from a complex string

  • Compute a derived metric

  • Normalize vendor-specific values

  • Filter out invalid readings

Example transformation (convert bytes to megabytes):

return $1 / 1048576;

Returning null keeps the original value — it is stored unchanged. To abort collection without storing a value, return one of the error indicators: DataCollection::ERROR, DataCollection::NOT_SUPPORTED, or DataCollection::NO_SUCH_INSTANCE.

For single-value DCIs, you can test transformation scripts directly in the DCI properties dialog using the Test…​ button.

Configuring Instance Discovery

Some metrics exist in multiple instances on a single node — for example, disk volumes, network interfaces, or database tablespaces. Instance discovery automates the creation of per-instance DCIs.

To configure instance discovery:

  1. Create a DCI with {instance} in the metric name (e.g., FileSystem.FreePerc({instance}))

  2. Open DCI properties and go to the Instance Discovery tab

  3. Select the discovery method and configure its parameter (see Instance Discovery Methods)

  4. Optionally set an instance filter (NXSL script returning true for instances to monitor)

  5. Optionally configure an instance name format (used by the OTLP discovery method only)

When applied, NetXMS discovers available instances and creates a separate DCI for each one. The {instance} and {instance-value} placeholders are replaced with the instance value, and {instance-name} with the instance display name.

Controlling Instance Retention

When an instance disappears (e.g., a disk is removed), the corresponding DCI is disabled and a grace period starts. After the retention time expires, the DCI is deleted along with its collected data.

Retention is configured on the Instance Discovery page of the DCI properties:

  • Instance retention mode — Server default or Custom

  • Instance retention time (days) — 0 to 100 days (used in Custom mode); 0 deletes the DCI immediately when the instance disappears

The server default is the DataCollection.InstanceRetentionTime configuration variable (7 days).

Configuring Agent Caching

Agent caching allows the NetXMS agent to store collected metric data locally when the connection to the server is lost. Once the connection is restored, the agent transmits all buffered data to the server.

This feature is available for the following data origins:

  • Agent (single-value and table metrics)

  • SNMP — only when collected through an SNMP proxy agent

  • Modbus — only when collected through a Modbus proxy

Agent caching is configured at three levels, with each level inheriting from the one above:

  1. Global: Set Agent.DefaultCacheMode in Configuration  Server Configuration (choice variable: 1 = On, 2 = Off; default: 2)

  2. Node: Set the agent cache mode in node properties on the Polling page (values: On, Off, or Default to use global setting)

  3. DCI: Set agent cache mode on the DCI’s Other Options page (values: On, Off, or Default to use node setting)

When cached data reaches the server, all transformation scripts and threshold evaluations are applied just as if the data had been collected in real time.

The DataCollection.OfflineDataRelevanceTime server configuration variable (default: 86400 seconds / 1 day) controls the maximum age of offline data that will trigger event generation. Cached data older than this threshold is still stored but does not generate threshold events, preventing a flood of outdated alerts when a long-disconnected agent reconnects.

Using Template Macros

When DCIs are defined on templates, the following macros can be used in the metric name, description, instance name, instance discovery data, system tag, and user tag fields. They are expanded when the template is applied to a node:

Macro Description

%{node_id}

Object ID of the node the template is applied to

%{node_name}

Name of the node the template is applied to

%{node_primary_ip}

Primary IP address of the node (only for Node objects)

%\{script:ScriptName}

Result of executing the specified NXSL library script when the template is applied

%\{expand:…​}

Expands the enclosed text using standard %-macro substitution (e.g., %n, %a)

Example: a template DCI with metric name MyApp.Status(%{node_name}) applied to node "web01" produces MyApp.Status(web01).

Next Steps