File (im_file)

This module can be used to read log messages from files. The file position can be persistently saved across restarts to avoid reading from the beginning again when NXLog Agent is restarted. External rotation tools are also supported. When the module is not able to read any more data from the file, it checks whether the opened file descriptor belongs to the same filename it opened originally. If the inodes differ, the module assumes the file was moved and reopens its input.

im_file uses a one-second interval to monitor files for new messages. This method was implemented because polling a regular file is not supported on all platforms. If there is no more data to read, the module will sleep for 1 second.

By using wildcards, the module can read multiple files simultaneously and will open new files as they appear. It will also enter newly created directories if recursion is enabled.

The module needs to scan the directory content for wildcarded file monitoring. This can present a significant load if there are many files (hundreds or thousands) in the monitored directory. For this reason, it is highly recommended to rotate files out of the monitored directory either using the built-in log rotation capabilities of NXLog Agent or with external tools.

Configuration

The im_file module accepts the following directives in addition to the common module directives. The File directive is required.

Required directives

The following directives are required for the module to start.

File

This mandatory directive specifies the name of the input file to open. It may be used more than once in a single im_file module instance. The value must be a string type expression. If the expression in the File directive is not a constant string (it contains functions, field names, or operators), it will be evaluated before each event is written to the file (and after the Exec is evaluated). For relative filenames, you should be aware that NXLog Agent changes its working directory to "/" unless the global SpoolDir is set to something else. On Windows systems, the directory separator is the backslash (\). For compatibility reasons the forward slash (/) character can be also used as the directory separator, but this only works for filenames not containing wildcards. If the filename is specified using wildcards, the backslash (\) should be used for the directory separator. Filenames on Windows systems are treated case-insensitively, but case-sensitively on Unix/Linux.

Wildcards are supported in filenames and directories. Wildcards are not regular expressions but are patterns commonly used by Unix shells to expand filenames (also known as "globbing").

?: Matches a single character only.
*: Matches zero or more characters.
\*: Matches the asterisk (*) character.
\?: Matches the question mark (?) character.
[…]: Used to specify a single character. The class description is a list containing single characters and ranges of characters separated by the hyphen (-). If the first character of the class description is ^ or !, the sense of the description is reversed (any character not in the list is accepted). Any character can have a backslash (\) preceding it, which is ignored, allowing the characters ] and - to be used in the character class, as well as ^ and ! at the beginning.

By default, the backslash character (\) is used as an escape sequence. This character is also the directory separator on Windows. Because of this, escaping wildcard characters is not supported on Windows, see the EscapeGlobPatterns directive. However, string literals are evaluated differently depending on the quotation type. Single quoted strings are interpreted as-is without escaping, e.g. 'C:\t???*.log' stays C:\t???\*.log. Escape sequences in double-quoted strings are processed, for example "C:\\t???\*.log" becomes C:\t???\*.log after evaluation. In both cases, the evaluated string is the same and gets separated into parts with different glob patterns at different levels. In the previous example, the parts are c:, t???, and *.log. NXLog Agent matches these at the proper directory levels to find all matching files.

Optional directives

ActiveFiles

This directive specifies the maximum number of files NXLog Agent will actively monitor. If there are modifications to more files in parallel than the value of this directive, then modifications to files above this limit will only get noticed after the DirCheckInterval (all data should be collected eventually). Typically there are only a few log sources actively appending data to log files, and the rest of the files are dormant after being rotated, so the default value of 10 files should be sufficient in most cases. This directive is also only relevant in the case of a wildcarded File path.

CloseWhenIdle

If set to TRUE, this boolean directive specifies that open input files should be closed as soon as possible after there is no more data to read. Some applications request an exclusive lock on the log file when written or rotated, and this directive can help if the application tries again to acquire the lock. The default is FALSE.

DirCheckInterval

This directive specifies how frequently, in seconds, the module will check the monitored directory for modifications to files and new files in case of a wildcarded File path. The default is twice the value of the PollInterval directive (if PollInterval is not set, the default is 2 seconds). Fractional seconds may be specified. We recommend increasing the default if many files cannot be rotated out and the NXLog Agent process is causing a high CPU load.

EscapeGlobPatterns

This boolean directive specifies whether the backslash (\) character in glob patterns or wildcarded entries should be enabled as an escape sequence. If set to TRUE, this directive implies that the backslash character (\) needs to be escaped by another backslash character (\\). File and directory patterns on Windows do not require escaping and are processed as non-escaped even if this directive is set to TRUE. The default is FALSE.

Exclude

This directive can specify a file or a set of files (using wildcards) to be excluded. More than one occurrence of the Exclude directive can be specified.

InputType

See the InputType directive in the list of common module directives. If this directive is not specified the default is LineBased (the module will use CRLF as the record terminator on Windows, or LF on Unix).

This directive also supports data converters, see the description in the InputType section.

NoEscape

This boolean directive specifies whether the backslash (\) in file paths should be disabled as an escape sequence. This is especially useful for file paths on Windows. By default, NoEscape is FALSE (backslash escaping is enabled and the path separator on Windows must be escaped).

Use the EscapeGlobPatterns global directive instead.

OnEOF

This optional block directive can be used to specify a group of statements to execute when a file has been fully read (on end-of-file). Only one OnEOF block can be specified per im_file module instance. The following directives are used inside this block.

Exec: This mandatory directive specifies the actions to execute after EOF has been detected and the grace period has passed. Like the normal Exec directive, the OnEOF Exec can be specified as a normal directive or a block directive.

GraceTimeout: This optional directive specifies the time in seconds to wait before executing the actions configured in the Exec block or directive. The default is 1 second.

PollInterval

This directive specifies how frequently the module will check for new files and new log entries, in seconds. If this directive is not specified, it defaults to 1 second. Fractional seconds may be specified (PollInterval 0.5 will check twice every second).

ReadFromLast

This optional boolean directive instructs the module to only read logs that arrive after NXLog Agent is started. This directive comes into effect if a saved position is not found, for example on the first start, or when the SavePos directive is FALSE. When the SavePos directive is TRUE and a previously saved position is found, the module will always resume reading from the saved position. If ReadFromLast is FALSE, the module will read all logs from the beginning of the file. This can result in a lot of messages and is usually not the expected behavior. If this directive is not specified, it defaults to TRUE.

The following matrix shows the outcome of this directive in conjunction with the SavePos directive:

ReadFromLast SavePos SavedPosition Outcome

TRUE

Reads events that are logged after NXLog Agent is started.

TRUE

Yes

Reads events from the saved position.

TRUE

FALSE

Reads events that are logged after NXLog Agent is started.

TRUE

FALSE

Yes

Reads events that are logged after NXLog Agent is started.

FALSE

TRUE

Reads all events.

FALSE

TRUE

Yes

Reads events from the saved position.

FALSE

Reads all events.

FALSE

Yes

Reads all events.

ReadOrder

This optional directive specifies the reading order of the elements in a directory. The accepted values are none, CtimeOldestFirst, CtimeNewestFirst (Ctime is file creating time), MtimeOldestFirst, MtimeNewestFirst (Mtime is file modification time), NameAsc and NameDesc (sort is done according to ASCII codes of name characters). If this directive is not specified then none is used as a default which means that the order of entries read from the directory is not specified.

Recursive

If set to TRUE, this boolean directive instructs the module to search for the filename within the specified directory and any sub-directories. You can use wildcards in combination with Recursive. However, it will only apply the recursive action on the stem of the path. See the examples in the table below. The default is FALSE.

File Directive Matches Directory Matches Filename Examples

/var/log/error.log

/var/log/*

error.log

/var/log/error.log
/var/log/apt/error.log

/var/log/*.log

/var/log/*

*.log

/var/log/error.log
/var/log/apt/history.log

/var/log/*/error.log

/var/log/*/*

error.log

/var/log/apt/error.log
/var/log/journal/error.log
/var/log/journal/tmp/error.log

/var/*/apt/error.log

/var/*/apt/*

error.log

/var/log/apt/error.log
/var/log/apt/tmp/error.log
/var/lib/apt/error.log
/var/lib/apt/log/error.log

FollowSymlinks

This directive specifies whether the module should treat symlinked directories and files as regular directories and files. If the directive is TRUE, the module treats symlinked directories and symlinked files as normal directories and files. If the Recursive directive is also TRUE, it will have the same effect as it has for a regular directory. The Exclude directive with the symlinks and target files works as usual except when the symlink’s name is defined in the File directive and the symlink’s target is specified in the Exclude directive. The default value of the FollowSymlinks directive is FALSE – the module does not follow the symlinked directories.

The directive works with symlinks created with the mklink command on Windows and the ln command on Unix-like operating systems. The directive supports symlinks made to directories and files.

RenameCheck

If set to TRUE, this boolean directive specifies that input files should be monitored for file rotation to avoid re-reading the same content. The module considers a file rotated when it detects a new file with the same inode and size as another deleted input file. Note that the file system can reuse the inode number of a deleted file. Therefore, if a new log file has the same inode and size as a deleted file, it will yield a false positive, and the module will falsely detect it as a rotated/renamed file. The default value of RenameCheck is FALSE – the module considers renamed files to be new and will re-read the file content.

When using file rotation, it is better to use a naming scheme that does not match the wildcard specified in the File directive so rotated files are no longer monitored than relying on the RenameCheck directive.

SavePos

If this boolean directive is set to TRUE, the file position will be saved when NXLog Agent exits. The file position will be read from the cache file upon startup. The default is TRUE, the file position will be saved if this directive is not specified. This directive affects the outcome of the ReadFromLast directive. The SavePos directive can be overridden by the global NoCache directive.

Functions

The following functions are exported by im_file.

string file_name(): Return the name of the currently open file, including the path which the log was read from.

integer record_number(): Returns the number of processed records (including the current record) of the currently open file since it was opened or truncated.

Creating and populating fields

im_file populates the $raw_event core field with the log message read from file. Further processing of this field can be done to parse the message into structured data or convert it to a different output format, such as JSON or XML. See Parsing and converting log records below and Parsing standard log formats in the NXLog Platform User Guide for examples

Examples

Example 1. Forwarding logs from files to a remote host

This configuration reads logs from a directory, symlinked directories, and files in the directory. The configuration then forwards the logs via TCP to a remote host.

nxlog.conf

<Input messages>
    Module            im_file
    File              "/var/log/messages/*"
    FollowSymlinks    TRUE
</Input>

<Output tcp>
    Module            om_tcp
    Host              192.168.1.1:514
</Output>

Example 2. Parsing and converting log records

This configuration reads logs from a file and parses the $raw_event field with a regular expression. If the regular expression matches, fields are created according to the captured groups, otherwise the log record is dropped. Finally, the record is converted to JSON format using the to_json() procedure of the xm_json module.

nxlog.conf

<Extension json>
    Module    xm_json
</Extension>

<Input messages>
    Module    im_file
    File      '/path/to/log/file'
    <Exec>
        if $raw_event =~ /(?x)^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\+\d\d:\d\d),
                          (.+),(.+)$/
        {
            $EventTime = parsedate($1);
            $Severity = $2;
            $Message = $3;
        }
        else
        {
            drop();
        }

        to_json();
    </Exec>
</Input>

Input sample

2021-11-05T14:03:40+01:00,INFO,The service started successfully

Output sample in JSON format

{
  "EventReceivedTime": "2021-11-05T14:04:24.244343+01:00",
  "SourceModuleName": "messages",
  "SourceModuleType": "im_file",
  "EventTime": "2021-11-05T14:03:40.000000+01:00",
  "Severity": "INFO",
  "Message": "The service started successfully"
}