Troubleshoot common issues
This page provides troubleshooting tips and solutions for the most common NXLog Agent issues related to log collection and processing. These issues typically stem from a misconfiguration and are straightforward to resolve.
NXLog Agent not collecting logs
- Symptom
-
NXLog Agent does not collect logs, yet there are no configuration errors or other symptoms.
- Possible reason
-
The most common reason for this issue is that, by default, NXLog Agent input modules only collect logs generated after their first start. They do not automatically read previously existing events. You can control this behavior with the ReadFromLast and SavePos directives.
- Investigation
-
Some input modules save the last log position they read in an in-memory cache and periodically write it to the
configcache.dat
file on disk. On the next start, the module starts reading logs from that position. To verify whether this is the cause of your issue:-
Verify that your input module supports the
ReadFromLast
andSavePos
directives. -
Check the existence and content of the
configcache.dat
file. The default location isC:\Program Files\nxlog\data
on Windows and/opt/nxlog/spool/nxlog/
on Linux and macOS.
-
- Solution
-
-
Stop the NXLog Agent service.
-
Delete the
configcache.dat
file. Note that deleting this file clears the configuration cache of all module instances. If you only want to start fresh for a single instance, give that instance a new name instead. -
Turn off the
ReadFromLast
directives by adding the following to your instance configuration:ReadFromLast FALSE
-
If you don’t want NXLog Agent to save the position of the last log it read, turn off the
SavePos
directive as well.SavePos FALSE
-
Start the NXLog Agent service.
-
See the NoCache, CacheDir, CacheFlushInterval, and CacheSync directives in the NXLog Agent Reference Manual for more options to control caching behavior.
NXLog Agent writing empty lines to an output file
- Symptom
-
NXLog Agent seems to be working fine, but your output file only includes empty lines.
- Possible reason
-
This issue could be caused by log records not containing the
$raw_event
field, which the om_file module writes to the output file. Without this field, the module writes empty lines.A good example of this issue is when you receive logs with im_udp and the
InputType
directive set toGELF_UDP
and write them to a file withom_file
.Example 1. Incorrect UDP to file configurationThis configuration receives
GELF
logs viaUDP
and saves them to a file. In this case, NXLog Agent writes empty lines in the output file.nxlog.conf<Extension gelf> Module xm_gelf </Extension> <Input udp> Module im_udp InputType GELF_UDP ListenAddr 0.0.0.0:12201 </Input> <Output file> Module om_file File 'C:\logs\gelflogs.txt' </Output>
- Investigation
-
Apart from seeing the empty lines in your output, there might be some indicators in your configuration that you can check. Two of the most common ones are:
-
You do not explicitly set the
$raw_event
field in your configuration. -
You are not using a data conversion procedure that automatically sets the
$raw-event
field, such as to_json() or to_syslog_bsd().
-
- Solution
-
Ensure that your configuration sets the
$raw_event
field. There are three ways you can do this:- Option 1
-
Explicitly set the
$raw_event
field by defining$raw_event = $another_field
in an exec block, where$another_field
contains the data you want to write to the output file. The$Message
field usually contains the necessary information, but it depends on the log source and your NXLog Agent configuration. In the case of theGELF_UDP
input example, the field is$FullMessage
.Example 2. Explicitly setting a fieldThis configuration receives GELF logs via UDP, sets the
$raw_event
field, and writes them to a file.nxlog.conf<Extension gelf> Module xm_gelf </Extension> <Input udp> Module im_udp InputType GELF_UDP ListenAddr 0.0.0.0:12201 </Input> <Output file> Module om_file File 'C:\logs\gelflogs.txt' Exec $raw_event = $FullMessage; </Output>
- Option 2
-
Another option is renaming an existing field using the rename_field() core procedure.
Example 3. Renaming a fieldThis configuration receives GELF logs via UDP, renames the
$FullMessage
field to$raw_event
, and writes them to a file.nxlog.conf<Extension gelf> Module xm_gelf </Extension> <Input udp> Module im_udp InputType GELF_UDP ListenAddr 0.0.0.0:12201 </Input> <Output file> Module om_file File 'C:\logs\gelflogs.txt' Exec rename_field($FullMessage, $raw_event); </Output>
- Option 3
-
You can also use a data conversion procedure that sets the
$raw_event
field, such as to_json() or to_syslog_bsd().Example 4. Using a data conversion procedureThis configuration receives GELF logs via UDP and converts log records to JSON using the to_json() procedure. This procedure writes the result to the
$raw_event
field.nxlog.conf<Extension gelf> Module xm_gelf </Extension> <Extension json> Module xm_json </Extension> <Input udp> Module im_udp InputType GELF_UDP ListenAddr 0.0.0.0:12201 </Input> <Output file> Module om_file File 'C:\logs\gelflogs.txt' Exec to_json(); </Output>