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 and SavePos directives.

  • Check the existence and content of the configcache.dat file. The default location is C:\Program Files\nxlog\data on Windows and /opt/nxlog/spool/nxlog/ on Linux and macOS.

Solution
  1. Stop the NXLog Agent service.

  2. 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.

  3. Turn off the ReadFromLast directives by adding the following to your instance configuration:

    ReadFromLast    FALSE
  4. 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
  5. 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 to GELF_UDP and write them to a file with om_file.

Example 1. Incorrect UDP to file configuration

This configuration receives GELF logs via UDP 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 the GELF_UDP input example, the field is $FullMessage.

Example 2. Explicitly setting a field

This 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 field

This 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 procedure

This 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>