README
1CRONOLOG version 1.7.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 a 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 replaced
34by their expansion. Format specifiers consist of a `%' followed by one
35of 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 your 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 recent, or up-to-date version of "cronolog" can be found at:
80
81 http://BSDforge.com/projects/sysutils/cronolog/
82 or
83 http://BSDforge.com/projects/sysutils/cronolog-devel/
84
85
86INSTALLATION
87============
88
89Cronolog uses GNU autoconf, so it is configured and built
90with the standard sequence:
91
92 ./configure
93 make
94
95To install type "make install" or simply copy the executable
96"src/cronolog" to a suitable directory.
97
98Cronolog has a number of options that can be set either by including
99in CFLAGS when configuring, or by editing the file "src/config.h":
100
101 -DFILE_MODE=octal-number mode used for creating files (default is 0664)
102 -DDIR_MODE=octal-number mode used for creating directories (default is 0775)
103 -DDONT_CREATE_SUBDIRS don't include code to create missing directories
104 -DNEED_GETOPT_DEFS if your platform doesn't declare getopt()
105
106e.g. to set the file mode to 0600:
107
108 CFLAGS="-O2 -DFILE_MODE=0600" ./configure
109
110
111TESTING
112=======
113
114The package includes a simple test harness program (cronotest), which
115tests out the lower level functions and prints out debugging
116information. The test program is run with the command line:
117
118 cronotest [-d] "template" count
119
120template is the filename template and count is the number of periods
121to evaluate, for example:
122
123 $ cronotest "%Y/%m/%d/access.log" 4
124 Determining periodicity of "%Y/%m/%d/access.log"
125 %Y -> yearly
126 %m -> monthly
127 %d -> daily
128 Rotation period is per day
129 Start time is Sun Dec 15 15:55:43 1996 (850665343)
130 Period 1 starts at Sun Dec 15 00:00:00 1996 (850608000): "1996/12/15/access.log"
131 Period 2 starts at Mon Dec 16 00:00:00 1996 (850694400): "1996/12/16/access.log"
132 Period 3 starts at Tue Dec 17 00:00:00 1996 (850780800): "1996/12/17/access.log"
133 Period 4 starts at Wed Dec 18 00:00:00 1996 (850867200): "1996/12/18/access.log"
134
135Specifying the flag -d instructs the test program to create missing
136subdirectories, for example, having created a directory 1996:
137
138 $ cronotest -d "%Y/%m/%d/access.log" 4
139 Determining periodicity of "%Y/%m/%d/access.log"
140 %Y -> yearly
141 %m -> monthly
142 %d -> daily
143 Rotation period is per day
144 Start time is Sun Dec 15 16:00:21 1996 (850665621)
145 Period 1 starts at Sun Dec 15 00:00:00 1996 (850608000): "1996/12/15/access.log"
146 Creating missing components of 1996/12/15/access.log
147 Testing directory "1996"
148 Testing directory "1996/12"
149 Directory "1996/12" does not exist -- creating
150 Testing directory "1996/12/15"
151 Directory "1996/12/15" does not exist -- creating
152 Period 2 starts at Mon Dec 16 00:00:00 1996 (850694400): "1996/12/16/access.log"
153 Creating missing components of 1996/12/16/access.log
154 Initial prefix "1996" known to exist
155 Initial prefix "1996/12" known to exist
156 Testing directory 1996/12/16
157 Directory "1996/12/16" does not exist -- creating
158 Period 3 starts at Tue Dec 17 00:00:00 1996 (850780800): "1996/12/17/access.log"
159 Creating missing components of 1996/12/17/access.log
160 Initial prefix "1996" known to exist
161 Initial prefix "1996/12" known to exist
162 Testing directory 1996/12/17
163 Directory "1996/12/17" does not exist -- creating
164 Period 4 starts at Wed Dec 18 00:00:00 1996 (850867200): "1996/12/18/access.log"
165 Creating missing components of 1996/12/18/access.log
166 Initial prefix "1996" known to exist
167 Initial prefix "1996/12" known to exist
168 Testing directory 1996/12/18
169 Directory "1996/12/18" does not exist -- creating
170
171
172Extra debugging code was added to cronolog at version 1.5b8 to
173facilitate interactive testing. To activate this cronolog must be
174must be invoked with -x (use -x- to send debug messages to stderr).
175In this mode each time it reads a message cronolog will print a
176message giving the current time, the start of the next period and the
177number of seconds until the start of the next period. This option is
178obviously not very useful when cronolog is being used for a production
179server handling several thousands or millions of requests a day, but
180can be useful for checking that cronolog is working correctly. You
181could set up a virtual server that was only used for testing and
182periodically send it a request. The -s option allows a start time to
183be specified -- cronolog will pretend that that is the current time.
184
185The following transcript shows how cronolog can be used for such a
186test. Lines prefixed by "**" are the lines I typed. The log file
187template creates a new log file every minute in a new directory. I
188specified a start time a minute before the change from GMT to BST
189(British Summer Time).
190
191 ** [andrew@icarus src]$ cronolog -x- -s "29 March 1998 00:59" \
192 "tmp/%Y.%m.%d/%H:%M/%Y.%m.%d-%H:%M-access.log"
193 cronolog version 1.5b8
194
195 Copyright (C) 1997 Ford & Mason Ltd.
196 This is free software; see the source for copying conditions.
197 There is NO warranty; not even for MERCHANTABILITY or FITNESS
198 FOR A PARTICULAR PURPOSE.
199
200 Written by Andrew Ford <A.Ford@ford-mason.co.uk>
201
202 The latest version can be found at:
203
204 http://www.ford-mason.co.uk/resources/cronolog/
205
206 Using offset of 1606971 seconds from real time
207 Determining periodicity of "tmp/%Y.%m.%d/%H:%M/%Y.%m.%d-%H:%M-access.log"
208 %Y -> yearly
209 %m -> monthly
210 %d -> daily
211 %H -> hourly
212 %M -> per minute
213 periodicity = minute
214 ** MESSAGE ONE
215 1998/03/29-00:59:04 GMT (891133144): using log file \
216 "tmp/1998.03.29/00:59/1998.03.29-00:59-access.log" \
217 until 1998/03/29-02:00:00 BST (891133200) (for 56 secs)
218 Creating missing components of "tmp/1998.03.29/00:59/1998.03.29-00:59-access.log"
219 Testing directory "tmp"
220 Directory "tmp" does not exist -- creating
221 Testing directory "tmp/1998.03.29"
222 Directory "tmp/1998.03.29" does not exist -- creating
223 Testing directory "tmp/1998.03.29/00:59"
224 Directory "tmp/1998.03.29/00:59" does not exist -- creating
225 1998/03/29-00:59:04 GMT (891133144): wrote message; \
226 next period starts at 1998/03/29-02:00:00 BST (891133200) in 56 secs
227 ** MESSAGE TWO
228 1998/03/29-00:59:32 GMT (891133172): wrote message; \
229 next period starts at 1998/03/29-02:00:00 BST (891133200) in 28 secs
230 ** MESSAGE THREE
231 1998/03/29-02:00:00 BST (891133200): using log file \
232 "tmp/1998.03.29/02:00/1998.03.29-02:00-access.log" \
233 until 1998/03/29-02:01:00 BST (891133260) (for 60 secs)
234 Creating missing components of "tmp/1998.03.29/02:00/1998.03.29-02:00-access.log"
235 Initial prefix "tmp" known to exist
236 Initial prefix "tmp/1998.03.29" known to exist
237 Testing directory "tmp/1998.03.29/02:00"
238 Directory "tmp/1998.03.29/02:00" does not exist -- creating
239 1998/03/29-02:00:00 BST (891133200): wrote message; \
240 next period starts at 1998/03/29-02:01:00 BST (891133260) in 60 secs
241
242This output shows cronolog:
243 * checking the periodicity of the log file template
244 * creating missing directories for new log files
245 * skipping stat() tests on directories it "knows" already exist
246 * recalculating the time until a new log file needs to be opened
247