Ubuntu Manpage: cronolog - write log messages to log files named according to a template

NAME

       cronolog - write log messages to log files named according to a template

SYNOPSIS

       cronolog [OPTION]... template

DESCRIPTION

       cronolog  is  a  simple program that reads log messages from its input and writes them to a set of output
       files, the names of which are constructed using template and the current date  and  time.   The  template
       uses  the  same  format  specifiers  as  the  Unix  date(1) command (which are the same as the standard C
       strftime library function).

       Before writing a message cronolog checks the time to see whether the current log file is still valid  and
       if not it closes the current file, expands the template using the current date and time to generate a new
       file name, opens the new file (creating missing directories on the path of the new  log  file  as  needed
       unless  the program is compiled with -DDONT_CREATE_SUBDIRS) and calculates the time at which the new file
       will become invalid.

       cronolog is intended to be used in conjunction with a Web server, such as Apache to split the access  log
       into daily or monthly logs.  For example the Apache configuration directives:

               TransferLog "|/usr/bin/cronolog /www/logs/%Y/%m/%d/access.log"
               ErrorLog    "|/usr/bin/cronolog /www/logs/%Y/%m/%d/errors.log"

       would  instruct  Apache to pipe its access and error log messages into separate copies of cronolog, which
       would create new log files each day in a directory hierarchy structured by date, i.e. on 31 December 1996
       messages would be written to

               /www/logs/1996/12/31/access.log
               /www/logs/1996/12/31/errors.log

       after midnight the files

               /www/logs/1997/01/01/access.log
               /www/logs/1997/01/01/errors.log

       would  be  used,  with the directories 1997, 1997/01 and 1997/01/01 being created if they did not already
       exist.  (Note that prior to version 1.2 Apache did not allow a program to be specified as the argument of
       the ErrorLog directive.)

Options

cronolog accepts the following options and arguments:

-H NAME

--hardlink=NAME
maintain a hard link from NAME to the current log file.

-S NAME

--symlink=NAME

-l NAME

--link=NAME
maintain a symbolic link from NAME to the current log file.

-P NAME

--prev-simlink=NAME
maintain a symbolic link from NAME to the previous log file. Requires that the --symlink option
is specified, as cronolog renames the current link to the name specified for the previous link.

-h

--help print a help message and then exit.

-p PERIOD

--period=PERIOD
specifies the period explicitly as an optional digit string followed by one of units: seconds,
minutes, hours, days, weeks or months. The count cannot be greater than the number of units in
the next larger unit, i.e. you cannot specify "120 minutes", and for seconds, minutes and hours
the count must be a factor of the next higher unit, i.e you can specify 1, 2, 3, 4, 5, 6, 10, 15,
20 or 30 minutes but not say 7 minutes.

-d PERIOD

--delay=PERIOD
specifies the delay from the start of the period before the log file is rolled over. For example
specifying (explicitly or implicitly) a period of 15 minutes and a delay of 5 minutes results in
the log files being rotated at five past, twenty past, twentyfive to and ten to each hour. The
delay cannot be longer than the period.

-o

--once-only
create single output log from template, which is not rotated.

-x FILE

--debug=FILE
write debug messages to FILE or to the standard error stream if FILE is "-". (See the README file
for more details.)

-s TIME

--start-time=TIME
pretend that the starting time is TIME (for debugging purposes). TIME should be something like DD
MONTH YYYY HH:MM:SS (the day and month are reversed if the american option is specified). If the
seconds are omitted then they are taken as zero and if the hours and minutes are omitted then the
time of day is taken as 00:00:00 (i.e. midnight). The day, month and year can be separated by
spaces, hyphens (-) or solidi (/).

-a

--american
Interprete the date part of the starting time the American way (month then day).

-e

--european
Interprete the date part of the starting time the European way (day then month). This is the
default.

-v

--version
print version information and exit.

Template format

       Each  character in the template represents a character in the expanded filename, except for date and time
       format specifiers, which are replaced by their expansion.  Format specifiers consist of a `%' followed by
       one of the following characters:

       %      a literal % character

       n      a new-line character

       t      a horizontal tab character

       Time fields:

       H      hour (00..23)

       I      hour (01..12)

       p      the locale's AM or PM indicator

       M      minute (00..59)

       S      second (00..61, which allows for leap seconds)

       X      the locale's time representation (e.g.: "15:12:47")

       Z      time zone (e.g. GMT), or nothing if the time zone cannot be determined

       Date fields:

       a      the locale's abbreviated weekday name (e.g.: Sun..Sat)

       A      the locale's full weekday name (e.g.: Sunday .. Saturday)

       b      the locale's abbreviated month name (e.g.: Jan .. Dec)

       B      the locale's full month name, (e.g.: January .. December)

       c      the locale's date and time (e.g.: "Sun Dec 15 14:12:47 GMT 1996")

       d      day of month (01 .. 31)

       j      day of year (001 .. 366)

       m      month (01 .. 12)

       U      week of the year with Sunday as first day of week (00..53, where week 1 is the week containing the
              first Sunday of the year)

       W      week of the year with Monday as first day of week (00..53, where week 1 is the week containing the
              first Monday of the year)

       w      day of week (0 .. 6, where 0 corresponds to Sunday)

       x      locale's date representation (e.g. today in April in Britain: "13/04/97")

       y      year without the century (00 .. 99)

       Y      year with the century (1970 .. 2038)

       Other specifiers may be available depending on the C library's implementation of the strftime function.

FUTURE DIRECTIONS

       The  functionality  of  cronolog could be built into Apache, thus saving the overhead of having a process
       per log stream and that of transferring data from the server process to the cronolog process.   The  main
       complication is handling the case where multiple log streams are written to the same file (template), for
       example where different virtual servers write to the same set of log files.

AUTHOR

       Andrew Ford <A.Ford@ford-mason.co.uk>

       cronolog is based on a program called rotatelogs by Ben Laurie, which is packaged  with  the  Apache  web
       server.

       The symbolic link option was suggested by Juergen Lesny.

                                                   March 1998                                       cronolog(1m)