Viewing the NXLog Agent logs

NXLog Agent logs messages about its operation to a file by default. These logs help troubleshoot NXLog Agent when it is not working as expected.

Below, we highlight how to customize logging settings, retrieve NXLog Agent status information, and run NXLog Agent interactively for live debugging.

Changing the log file path

The LogFile global directive specifies the path of the NXLog Agent log file. The path must point to an existing directory. NXLog Agent creates the file if it does not exist.

The default file path is C:\Program Files\nxlog\data\nxlog.log on Windows and /opt/nxlog/var/log/nxlog/nxlog.log on Linux and macOS. You can turn off logging to a file by removing the LogFile directive. You must restart NXLog Agent for new settings to come into effect.

Setting the log level

The LogLevel global directive specifies NXLog Agent’s logging level. The default level is INFO. You can record more detailed information by setting the log level to DEBUG. However, this level produces a lot of logging, so we only recommend it for troubleshooting. You must restart NXLog Agent before the new setting comes into effect.

Alternatively, you can temporarily change the logging level for a running instance as follows:

Windows

Send the service control command 201:

> sc control nxlog 201

Linux and macOS

Send the SIGUSR2 signal:

$ sudo pkill -SIGUSR2 nxlog

Restart the NXLog Agent service to revert to the configuration LogLevel value.

Getting NXLog Agent status information

You can instruct NXLog Agent to dump status information into the log file. This information can help you troubleshoot log processing issues, such as an input instance not forwarding logs to an output instance.

Windows

Send the service control command 200:

> sc control nxlog 200

Linux and macOS

Send the SIGUSR1 signal:

$ sudo pkill -SIGUSR1 nxlog

NXLog Agent writes status information similar to the following in its log file.

2024-06-28 15:25:42 INFO [CORE|main] event queue has 2 events:  TIMEOUT: 1;
CONFIG_CACHE_FLUSH: 1;jobgroup with priority 1;non-module job, events: 0;
jobgroup with priority 10;job of module system_logs/im_file, events: 0;job
of module file/om_file, events: 0;jobgroup with priority 99;non-module job,
events: 0;non-module job, events: 0;non-module job, events: 0;non-module job,
events: 0;[route r1]; - system_logs: type INPUT, status: RUNNING queuesize: 0;
- file: type OUTPUT, status: RUNNING queuesize: 0;

The instance status is the most important field in the debug dump. If the status is PAUSED, the following instance’s queue is full and cannot receive more logs. In this case, the queuesize value of the next instance will be over 99. An instance with a STOPPED status means it has terminated, most likely due to an error.

Using systemd journal on Linux

On Linux-based systems, systemd controls the NXLog Agent service. The systemd journal captures applications' standard output and standard error streams, including NXLog Agent’s logging. Logs are available in the journal database even if logging to a file is not enabled, or the log file is deleted. You can use the journalctl tool to view the logs. The following are some useful journalctl commands for troubleshooting.

A user must be a member of the systemd-journal group to access the systemd journal logs.

Execute the following command to show all NXLog Agent journal entries since it was installed, ordered by oldest first.

$ journalctl --unit nxlog

Use the -b option to show log entries from the current boot.

$ journalctl --unit nxlog -b

Use the --since and --until options to limit the logging to a specific timeframe. Specify the time in local time.

$ journalctl --unit nxlog --since "2024-06-28 15:00:00" --until "2024-06-28 15:30:00"

You can redirect the output to a file as follows.

$ journalctl --unit nxlog --since "2024-06-28 15:00:00" >nxlog.log

By default, journalctl shows logs in syslog-style. However, you can change the output format to JSON using the -o option.

$ journalctl --unit nxlog --since "2024-06-28 15:00:00" -o json

You can also actively follow live logs with the -f option.

$ journalctl --unit nxlog -f

Running NXLog Agent interactively

Running NXLog Agent interactively can be helpful for live debugging. Run NXLog Agent from the command line with the -f option to view its standard output and standard error streams.

Linux

Execute the following command:

$ sudo /opt/nxlog/bin/nxlog -f

Windows

Open the command prompt with administrative rights and execute the following command:

> "C:\Program Files\nxlog\nxlog.exe" -f