NAME

tinylog - log stdin to a directory of rotated log files

SYNOPSIS

tinylog [-hV] [-k numkeep ] [-r] [-s logsize ] [-t] [-z] dir

DESCRIPTION

tinylog reads lines from standard input and writes them to a set of rotated log files maintained in dir.

While active, tinylog switches into dir and writes into a log file named current. When current reaches the size specified with the -s option (default 100000 bytes), it rotates the file: current is renamed with a filename in the form _yyyymmddThhmmss.uuuuuu.s, and a new current is opened.

tinylog maintains a set of older rotated log files in dir, upto the number specified with the -k option (default 5). After this number is reached, tinylog deletes the rotated log file with the oldest timestamp before continuing with a new current.

If the -z option is specified, tinylog will compress log files during rotation with the utility specified in the environmental variable TINYLOG_ZIP (default /usr/bin/gzip). If the compression is successful, the rotated log file is renamed with a .Z extension.

The name of a rotated log file may be described further: beginning with an underscore, followed by a current gmtime(3) timestamp in RFC8601 format (to the nearest microsecond), followed by a status suffix, and optionally followed by a .Z zip extension. Normally the status suffix is .s, indicating the file was safely written to disk. Otherwise a status suffix of .u indicates that the file was not safely written to disk, and may possibly be incomplete and/or corrupted by an unexpected failure.

tinylog sets the file mode of current to 0644 while active. When tinylog sees eof on stdin, it writes any pending line to current, fsyncs and closes the file, and changes its mode to 0744 before exiting. Whenever tinylog restarts, it looks for an existing current and, if one is found with a file mode 0744, reopens it and changes its mode back to 0644 for continued logging. Otherwise, if an existing current is found set with a mode of 0644, it is immediately rotated with a .u suffix, and a new current is opened.

tinylog ignores empty lines, truncates lines longer than 1000 characters, and converts unprintable control characters to `?'.

OPTIONS

-h: Help. Print a brief usage message to stderr and exit.
-k numkeep: Keep. Sets the maximum number of log files that tinylog will keep after rotation. Whenever tinylog rotates the most recent log file, it deletes any more than numkeep older log files found in the directory. The minimum number is 0, in which case no older log files are kept. If not specified, the default number of older log files kept is 5.
-r: Rotate on start. Normally on start-up, tinylog begins logging with an existing current file if it has been safely closed from a previous session. The -r option causes tinylog to immediately rotate any existing current file and begin logging with a new one.
-s logsize: Size. Sets the maximum size (in bytes) that a log file may grow before rotation. The minimum size is 2000. The default size is 100000.
-t: Timestamp. A current gmtime(3) timestamp string in the form of ``yyyymmddThhmmss.uuuuuu'' is prepended to each line written to the log file.
-V: Version. Print the version number to stderr and exit.
-z: Zip. This option instructs tinylog to run a compression utility when it rotates the log file. The compression utility may be specified in the environmental variable TINYLOG_ZIP. If the variable is not set or empty, tinylog will use a compiled-in default, usually /usr/bin/gzip. The compression utility should be designed to run without any arguments, reading from stdin and writing to stdout. After successful compression, tinylog will rename the rotated log file with a .Z extension.

ENVIRONMENT

TINYLOG_ZIP

If defined and the -z option is specified, will be taken as the executable for the compression utility to use when rotating a log file.

SIGNALS

tinylog traps the following signals for adminstrative control during runtime:

SIGHUP

Close and rotate current, then continue logging with a new current.

SIGTERM

Stop reading stdin, process any pending lines already read, flush and close current safely to disk, then exit 0 (no error). Stdin will be left at the first byte of any unprocessed data.

EXIT STATUS

tinylog exits with the following values:

0: Normally tinylog runs until eof is found on stdin, or until it receives a TERM signal. In these cases, tinylog writes any pending lines to the log, flushes and closes current, changes its mode to 0744, and exits 0.
100: tinylog failed on startup because of some usage error, such as invalid command-line option or missing argument. In this case tinylog will print a brief diagnostic to stderr on exit.
111: tinylog found another instance or active lockfile running in dir, or failed due to some other system or resource error on startup. In this case tinylog will print a brief diagnostic to stderr on exit.

Otherwise, after startup, tinylog tries very hard not to exit until eof is read on stdin. In the case of system or resource failures, tinylog will print a diagnostic message to stderr, pause for a brief interval, and then retry the failed operation.

AUTHOR

Wayne Marshall, http://b0llix.net/perp/