Diagnostics

This page describes how to collect diagnostic information, enable debug logging, and trace issues in NetXMS.

Server Log Files

Log File Location

The server log file location is configured by the LogFile parameter in netxmsd.conf:

LogFile = /var/log/netxmsd.log

The default is /var/log/netxmsd.log on UNIX-like systems and C:\netxmsd.log on Windows. Special values are also accepted: {syslog} (system syslog on UNIX, Event Log on Windows), {systemd} (systemd journal), and {stdout} (standard output).

Log Rotation

Log rotation is controlled by these configuration parameters:

Parameter Default Description

LogRotationMode

2

0 = no rotation, 1 = daily rotation, 2 = rotate by size

MaxLogSize

16777216

Maximum log file size in bytes before rotation (when mode = 2)

LogHistorySize

4

Number of rotated log files to keep

Debug Logging

Debug Levels

NetXMS uses debug levels from 0 (no debug output) to 9 (maximum verbosity). Each level includes all output from lower levels. The level is a verbosity threshold — there is no fixed meaning attached to individual levels, and it is independent of message severity (errors and warnings are always logged regardless of debug level).

High debug levels generate very large amounts of log output and can affect server performance. Use them only for targeted troubleshooting and remember to restore level 0 when done.

Enabling Debug Logging

There are three ways to enable debug output. The debug console used below is available locally via nxadm -i or in the management client under Tools > Server debug console (see Debug Console).

Configuration file

Set the global debug level in netxmsd.conf:

DebugLevel = 4

Debug levels for specific tags can be set with the DebugTags parameter, a comma-separated list of tag:level entries:

DebugTags = poll.status:7,db.query:5

These settings require a server restart; DebugLevel affects all subsystems.

Debug console (runtime)

Change the debug level without restarting the server:

debug 4

This takes effect immediately but does not persist across restarts.

Debug tags (targeted diagnostics)

Debug tags allow you to set different debug levels for specific subsystems without flooding the log with unnecessary output:

debug poll.status 7
debug db.query 5
debug snmp.trap 6

This is the recommended approach for production troubleshooting as it limits the log volume to the relevant subsystem.

Common Debug Tags

Tag Description

poll.status

Status polling

poll.conf

Configuration polling

poll.discovery

Network discovery

poll.icmp

ICMP polling

db.query

Database queries (shows executed SQL)

db.writer

Database writer queues

snmp.trap

SNMP trap processing

snmp.discovery

SNMP-based discovery

agent.conn

Agent connections

agent.tunnel

Agent tunnel management

event.proc

Event processing

event.policy

Event processing policy rule matching

event.corr

Event correlation

dc.config

Data collection configuration

dc.scheduler

Data collection scheduling

nxsl

NXSL feature enablement and JSON parsing messages

scripts

NXSL script compilation, execution, and errors

crypto

Encryption and certificate operations

obj.sync

Object synchronization

client.session

Client session communication

Resetting Debug Level

To restore normal logging:

From the debug console:

debug 0

To clear a specific tag (revert it to the default level), use default or -1 as the level:

debug poll.status default

To see current debug settings, run debug without arguments:

debug

Agent Diagnostics

Agent Log Files

Agent log file location is configured in nxagentd.conf:

LogFile = /var/log/nxagentd

The agent supports the same debug levels and rotation settings as the server.

Enabling Agent Debug

Set debug level in nxagentd.conf:

DebugLevel = 4
DebugTags = tunnel.*:6

Restart the agent after changing the configuration for the new debug level to take effect.

For a one-off debug run, start the agent in the foreground with debug options on the command line:

nxagentd -D 6
nxagentd -t tunnel.*:6
Lowercase -d means "run as daemon", not debug.

Testing Agent Connectivity

Use nxget to test communication with an agent:

nxget <host> Agent.Version
nxget <host> System.CPU.Usage
nxget -I <host>

The -I flag lists all supported metrics from the agent.

Collecting Diagnostic Information

When reporting issues, collect the following information:

Server Diagnostics

  1. Server version:

    netxmsd -v

  2. Server log with debug level 4 or above (reproduce the issue with debug enabled)

  3. Server configuration file (netxmsd.conf) — redact passwords

  4. Thread pool statistics from the debug console:

    show threads

  5. Database type and version

  6. Operating system and version

  7. Number of monitored nodes and active DCIs

Agent Diagnostics

  1. Agent version:

    nxagentd -v

  2. Agent log with debug level 4 or above

  3. Agent configuration file (nxagentd.conf) — redact secrets

  4. List of loaded subagents (check the agent log, or query remotely with nxget -l <agent_address> Agent.SubAgentList)

Network Diagnostics

Verifying Port Connectivity

NetXMS uses the following default ports:

Port Protocol Purpose

4701

TCP

Server to client communication

4700

TCP

Server to agent communication

4703

TCP

Agent tunnel connections

162

UDP

SNMP trap receiver

514

UDP

Syslog receiver

Verify connectivity using:

nc -zv <host> <port>

Packet Capture

For deep protocol troubleshooting, capture network traffic between components:

tcpdump -i any -w /tmp/netxms-capture.pcap host <target-ip> and port 4700

Database Diagnostics

Database Consistency Check

Use nxdbmgr to check and repair database consistency (the server must be stopped):

nxdbmgr check

The check is interactive — when problems are found, it explains them and asks before applying repairs.

Always back up the database before applying repairs.

Database Statistics

Monitor database health using the Server.DB.* internal metrics on the management server node, or query the database directly with native tools.

For additional troubleshooting, see Common Issues and Debug Console.