File Operations (xm_fileop)
This module provides functions and procedures to manipulate files. Coupled with a Schedule block, this module allows various log rotation and retention policies to be implemented, including:
-
log file retention based on file size,
-
log file retention based on file age, and
-
cyclic log file rotation and retention.
Configuration
The xm_fileop module accepts only the common module directives.
Functions
The following functions are exported by xm_fileop.
- string
dir_temp_get()
-
Return the name of a directory suitable as a temporary storage location.
- binary
file_hash(string file, string digest)
-
Return the calculated hash of file using digest algorithm. Available digest values are
blake2b512, blake2s256, gost, md4, md5, rmd160, sha1, sha224, sha256, sha384, sha512
(seeopenssl dgst
command in openssl’s manual). On error undef is returned and an error is logged.
Procedures
The following procedures are exported by xm_fileop.
dir_make(string path);
-
Create a directory recursively (like
mkdir -p
). It succeeds if the directory already exists. An error is logged if the operation fails.
dir_remove(string file);
-
Remove the directory from the filesystem.
file_cycle(string file);
-
Do a cyclic rotation on file. The file will be moved to "file.1". If "file.1" already exists it will be moved to "file.2", and so on. Wildcards are supported in the file path and filename. The backslash (
\
) must be escaped if used as the directory separator with wildcards (for example,C:\\test\\*.log
). This procedure will reopen the LogFile if it is cycled. An error is logged if the operation fails.
file_cycle(string file, boolean copy_truncate);
-
Perform a cyclic rotation on file. If
copy_truncate
is set toFALSE
or not specified, the file will be moved to "file.1". Ifcopy_truncate
is set toTRUE
, the original file will be copied to "file.1", and then truncated to zero. If "file.1" already exists it will be moved to "file.2", and so on. Wildcards are supported in the file path and filename. The backslash (\
) must be escaped if used as the directory separator with wildcards (for example,C:\\test\\*.log
). Ifcopy_truncate
isFALSE
, this procedure will reopen the LogFile if it is cycled. An error is logged if the operation fails.Be aware, that if copy_truncate
isTRUE
, there is a small time delay between copying the file and truncating it, so some logging data may be lost.
file_remove(string file);
-
Remove file. It is possible to specify a wildcard in the filename (but not in the path). The backslash (
\
) must be escaped if used as the directory separator with wildcards (for example,C:\\test\\*.log
). This procedure will reopen the LogFile if it is removed. An error is logged if the operation fails. Calling this procedure while the file is still open by nxlog or other processes, may produce undefined behavior, including silently failing to remove the file (known issue on Windows Server).
file_remove(string file, datetime older);
-
Remove file if its creation time is older than the value specified in older. It is possible to specify a wildcard in the filename (but not in the path). The backslash (
\
) must be escaped if used as the directory separator with wildcards (for example,C:\\test\\*.log
). This procedure will reopen the LogFile if it is removed. An error is logged if the operation fails. Calling this procedure while the file is still open by nxlog or other processes, may produce undefined behavior, including silently failing to remove the file (known issue on Windows Server).
file_touch(string file);
-
Update the last modification time of file or create the file if it does not exist. An error is logged if the operation fails.
file_truncate(string file);
-
Truncate file to zero length. If the file does not exist, it will be created. An error is logged if the operation fails.
Examples
In this example, the internal log file is rotated based on time and size.
#define LOGFILE C:\Program Files\nxlog\data\nxlog.log
define LOGFILE /var/log/nxlog/nxlog.log
<Extension fileop>
Module xm_fileop
# Check the log file size every hour and rotate if larger than 1 MB
<Schedule>
Every 1 hour
Exec if (file_size('%LOGFILE%') >= 1M) \
file_cycle('%LOGFILE%', 2);
</Schedule>
# Rotate log file every week on Sunday at midnight
<Schedule>
When @weekly
Exec file_cycle('%LOGFILE%', 2);
</Schedule>
</Extension>