README
1CRONOLOG version 1.6.1
2
3"cronolog" is a simple program that reads log messages from its input
4and writes them to a set of output files, the names of which are
5constructed using template and the current date and time. The
6template uses the same format specifiers as the Unix date command
7(which are the same as the standard C strftime library function).
8
9"cronolog" is intended to be used in conjunction with a Web server, such
10as Apache to split the access log into daily or monthly logs. For
11example the Apache configuration directives:
12
13 TransferLog "|/www/sbin/cronolog /www/logs/%Y/%m/%d/access.log"
14 ErrorLog "|/www/sbin/cronolog /www/logs/%Y/%m/%d/errors.log"
15
16would instruct Apache to pipe its access and error log messages into
17separate copies of cronolog, which would create new log files each day
18in a directory hierarchy structured by date, i.e. on 31 December 1996
19messages would be written to
20
21 /www/logs/1996/12/31/access.log
22 /www/logs/1996/12/31/errors.log
23
24after midnight the files
25
26 /www/logs/1997/01/01/access.log
27 /www/logs/1997/01/01/errors.log
28
29would be used, with the directories 1997, 1997/01 and 1997/01/01 being
30created if they did not already exist.
31
32Each character in the template represents a character in the expanded
33filename, except for date and time format specifiers, which are
34replaced by their expansion. Format specifiers consist of a `%'
35followed by one of the following characters:
36
37 % a literal % character
38 n a new-line character
39 t a horizontal tab character
40
41Time fields:
42
43 H hour (00..23)
44 I hour (01..12)
45 p the locale's AM or PM indicator
46 M minute (00..59)
47 S second (00..61, which allows for leap seconds)
48 X the locale's time representation (e.g.: "15:12:47")
49 Z time zone (e.g. GMT), or nothing if the time zone cannot be determined
50
51Date fields:
52
53 a the locale's abbreviated weekday name (e.g.: Sun..Sat)
54 A the locale's full weekday name (e.g.: Sunday .. Saturday)
55 b the locale's abbreviated month name (e.g.: Jan .. Dec)
56 B the locale's full month name, (e.g.: January .. December)
57 c the locale's date and time (e.g.: "Sun Dec 15 14:12:47 GMT 1996")
58 d day of month (01 .. 31)
59 j day of year (001 .. 366)
60 m month (01 .. 12)
61 U week of the year with Sunday as first day of week (00..53, where
62 week 1 is the week containing the first Sunday of the year)
63 W week of the year with Monday as first day of week (00..53, where
64 week 1 is the week containing the first Monday of the year)
65 w day of week (0 .. 6, where 0 corresponds to Sunday)
66 x locale's date representation (e.g. today in Britain: "15/12/96")
67 y year without the century (00 .. 99)
68 Y year with the century (1970 .. 2038)
69
70Other specifiers may be available depending on the C library's
71implementation of the strftime function. Before writing a message
72cronolog checks the time to see whether the current log file is still
73valid and if not it closes the current file, expands the template
74using the current date and time to generate a new file name, opens the
75new file (creating missing directories on the path of the new log file
76as needed unless the program is compiled with -DDONT_CREATE_SUBDIRS)
77and calculates the time at which the new file will become invalid.
78
79The most up-to-date version of "cronolog" can be found at:
80
81 http://www.ford-mason.co.uk/resources/cronolog/
82
83
84INSTALLATION
85============
86
87Cronolog uses GNU autoconf, so it is configured and built
88with the standard sequence:
89
90 ./configure
91 make
92
93To install type "make install" or simply copy the executable
94"src/cronolog" to a suitable directory.
95
96Cronolog has a number of options that can be set either by including
97in CFLAGS when configuring, or by editing the file "src/config.h":
98
99 -DFILE_MODE=octal-number mode used for creating files (default is 0664)
100 -DDIR_MODE=octal-number mode used for creating directories (default is 0775)
101 -DDONT_CREATE_SUBDIRS don't include code to create missing directories
102 -DNEED_GETOPT_DEFS if your platform doesn't declare getopt()
103
104e.g. to set the file mode to 0600:
105
106 CFLAGS="-O2 -DFILE_MODE=0600" ./configure
107
108
109TESTING
110=======
111
112The package includes a simple test harness program (cronotest), which
113tests out the lower level functions and prints out debugging
114information. The test program is run with the command line:
115
116 cronotest [-d] "template" count
117
118template is the filename template and count is the number of periods
119to evaluate, for example:
120
121 $ cronotest "%Y/%m/%d/access.log" 4
122 Determining periodicity of "%Y/%m/%d/access.log"
123 %Y -> yearly
124 %m -> monthly
125 %d -> daily
126 Rotation period is per day
127 Start time is Sun Dec 15 15:55:43 1996 (850665343)
128 Period 1 starts at Sun Dec 15 00:00:00 1996 (850608000): "1996/12/15/access.log"
129 Period 2 starts at Mon Dec 16 00:00:00 1996 (850694400): "1996/12/16/access.log"
130 Period 3 starts at Tue Dec 17 00:00:00 1996 (850780800): "1996/12/17/access.log"
131 Period 4 starts at Wed Dec 18 00:00:00 1996 (850867200): "1996/12/18/access.log"
132
133Specifying the flag -d instructs the test program to create missing
134subdirectories, for example, having created a directory 1996:
135
136 $ cronotest -d "%Y/%m/%d/access.log" 4
137 Determining periodicity of "%Y/%m/%d/access.log"
138 %Y -> yearly
139 %m -> monthly
140 %d -> daily
141 Rotation period is per day
142 Start time is Sun Dec 15 16:00:21 1996 (850665621)
143 Period 1 starts at Sun Dec 15 00:00:00 1996 (850608000): "1996/12/15/access.log"
144 Creating missing components of 1996/12/15/access.log
145 Testing directory "1996"
146 Testing directory "1996/12"
147 Directory "1996/12" does not exist -- creating
148 Testing directory "1996/12/15"
149 Directory "1996/12/15" does not exist -- creating
150 Period 2 starts at Mon Dec 16 00:00:00 1996 (850694400): "1996/12/16/access.log"
151 Creating missing components of 1996/12/16/access.log
152 Initial prefix "1996" known to exist
153 Initial prefix "1996/12" known to exist
154 Testing directory 1996/12/16
155 Directory "1996/12/16" does not exist -- creating
156 Period 3 starts at Tue Dec 17 00:00:00 1996 (850780800): "1996/12/17/access.log"
157 Creating missing components of 1996/12/17/access.log
158 Initial prefix "1996" known to exist
159 Initial prefix "1996/12" known to exist
160 Testing directory 1996/12/17
161 Directory "1996/12/17" does not exist -- creating
162 Period 4 starts at Wed Dec 18 00:00:00 1996 (850867200): "1996/12/18/access.log"
163 Creating missing components of 1996/12/18/access.log
164 Initial prefix "1996" known to exist
165 Initial prefix "1996/12" known to exist
166 Testing directory 1996/12/18
167 Directory "1996/12/18" does not exist -- creating
168
169
170Extra debugging code was added to cronolog at version 1.5b8 to
171facilitate interactive testing. To activate this cronolog must be
172must be invoked with -x (use -x- to send debug messages to stderr).
173In this mode each time it reads a message cronolog will print a
174message giving the current time, the start of the next period and the
175number of seconds until the start of the next period. This option is
176obviously not very useful when cronolog is being used for a production
177server handling several thousands or millions of requests a day, but
178can be useful for checking that cronolog is working correctly. You
179could set up a virtual server that was only used for testing and
180periodically send it a request. The -s option allows a start time to
181be specified -- cronolog will pretend that that is the current time.
182
183The following transcript shows how cronolog can be used for such a
184test. Lines prefixed by "**" are the lines I typed. The log file
185template creates a new log file every minute in a new directory. I
186specified a start time a minute before the change from GMT to BST
187(British Summer Time).
188
189 ** [andrew@icarus src]$ cronolog -x- -s "29 March 1998 00:59" \
190 "tmp/%Y.%m.%d/%H:%M/%Y.%m.%d-%H:%M-access.log"
191 cronolog version 1.5b8
192
193 Copyright (C) 1997 Ford & Mason Ltd.
194 This is free software; see the source for copying conditions.
195 There is NO warranty; not even for MERCHANTABILITY or FITNESS
196 FOR A PARTICULAR PURPOSE.
197
198 Written by Andrew Ford <A.Ford@ford-mason.co.uk>
199
200 The latest version can be found at:
201
202 http://www.ford-mason.co.uk/resources/cronolog/
203
204 Using offset of 1606971 seconds from real time
205 Determining periodicity of "tmp/%Y.%m.%d/%H:%M/%Y.%m.%d-%H:%M-access.log"
206 %Y -> yearly
207 %m -> monthly
208 %d -> daily
209 %H -> hourly
210 %M -> per minute
211 periodicity = minute
212 ** MESSAGE ONE
213 1998/03/29-00:59:04 GMT (891133144): using log file \
214 "tmp/1998.03.29/00:59/1998.03.29-00:59-access.log" \
215 until 1998/03/29-02:00:00 BST (891133200) (for 56 secs)
216 Creating missing components of "tmp/1998.03.29/00:59/1998.03.29-00:59-access.log"
217 Testing directory "tmp"
218 Directory "tmp" does not exist -- creating
219 Testing directory "tmp/1998.03.29"
220 Directory "tmp/1998.03.29" does not exist -- creating
221 Testing directory "tmp/1998.03.29/00:59"
222 Directory "tmp/1998.03.29/00:59" does not exist -- creating
223 1998/03/29-00:59:04 GMT (891133144): wrote message; \
224 next period starts at 1998/03/29-02:00:00 BST (891133200) in 56 secs
225 ** MESSAGE TWO
226 1998/03/29-00:59:32 GMT (891133172): wrote message; \
227 next period starts at 1998/03/29-02:00:00 BST (891133200) in 28 secs
228 ** MESSAGE THREE
229 1998/03/29-02:00:00 BST (891133200): using log file \
230 "tmp/1998.03.29/02:00/1998.03.29-02:00-access.log" \
231 until 1998/03/29-02:01:00 BST (891133260) (for 60 secs)
232 Creating missing components of "tmp/1998.03.29/02:00/1998.03.29-02:00-access.log"
233 Initial prefix "tmp" known to exist
234 Initial prefix "tmp/1998.03.29" known to exist
235 Testing directory "tmp/1998.03.29/02:00"
236 Directory "tmp/1998.03.29/02:00" does not exist -- creating
237 1998/03/29-02:00:00 BST (891133200): wrote message; \
238 next period starts at 1998/03/29-02:01:00 BST (891133260) in 60 secs
239
240This output shows cronolog:
241 * checking the periodicity of the log file template
242 * creating missing directories for new log files
243 * skipping stat() tests on directories it "knows" already exist
244 * recalculating the time until a new log file needs to be opened
245