svlogd.8.html (11981B)
1 2 3 4 <html> 5 <head> 6 <title>svlogd(8) manual page</title> 7 </head> 8 <body bgcolor='white'> 9 <a href='http://smarden.org/pape/'>G. Pape</a><br><a href='index.html'>runit</A><hr><p> 10 11 <h2><a name='sect0'>Name</a></h2> 12 svlogd - runit’s service logging daemon 13 <h2><a name='sect1'>Synopsis</a></h2> 14 <b>svlogd</b> [-tttv] [-r <i>c]</i> [-R 15 <i>xyz]</i> [-l <i>len]</i> [-b <i>buflen]</i> <i>logs</i> 16 <h2><a name='sect2'>Description</a></h2> 17 <i>logs</i> consists of one or more arguments, 18 each specifying a directory. <p> 19 <b>svlogd</b> continuously reads log data from its 20 standard input, optionally filters log messages, and writes the data to 21 one or more automatically rotated <i>logs</i>. <p> 22 Recent log files can automatically 23 be processed by an arbitrary processor program when they are rotated, and 24 <b>svlogd</b> can be told to alert selected log messages to standard error, and 25 through udp. <p> 26 <b>svlogd</b> runs until it sees end-of-file on standard input or is 27 sent a TERM signal, see below. 28 <h3><a name='sect3'>Log Directory</a></h3> 29 A log directory <i>log</i> contains 30 some number of old log files, and the current log file <i>current</i>. Old log 31 files have a file name starting with <i>@</i> followed by a precise timestamp 32 (see the daemontools’ <b>tai64n</b> program), indicating when <i>current</i> was rotated 33 and renamed to this file. <p> 34 A log directory additionally contains the lock 35 file <i>lock</i>, maybe <i>state</i> and <i>newstate</i>, and optionally the file <i>config</i>. <b>svlogd</b> 36 creates necessary files if they don’t exist. <p> 37 If <b>svlogd</b> has trouble opening 38 a log directory, it prints a warning, and ignores this log directory. If 39 <b>svlogd</b> is unable to open all log directories given at the command line, 40 it exits with an error. This can happen on start-up or after receiving a 41 HUP signal. 42 <h3><a name='sect4'>Log File Rotation</a></h3> 43 <b>svlogd</b> appends selected log messages to the 44 <i>current</i> log file. If <i>current</i> has <i>size</i> bytes or more (or there is a new-line 45 within the last <i>len</i> of <i>size</i> bytes), or is older than a specified amount 46 of <i>time</i>, <i>current</i> is rotated: <p> 47 <b>svlogd</b> closes <i>current</i>, changes permission 48 of <i>current</i> to 0755, renames <i>current</i> to @<i>timestamp.s,</i> and starts with a new 49 empty <i>current</i>. If <b>svlogd</b> sees <i>num</i> or more old log files in the log directory, 50 it removes the oldest one. Note that this doesn’t decrease the number of 51 log files if there are already more than <i>num</i> log files, this must be done 52 manually, e.g. for keeping 10 log files: <p> 53 ls -1 \@* |sort |sed -ne ’10,$p’ |xargs 54 rm<br> 55 56 <h3><a name='sect5'>Processor</a></h3> 57 If <b>svlogd</b> is told to process recent log files, it saves <i>current</i> 58 to @<i>timestamp.u,</i> feeds @<i>timestamp.u</i> through ‘‘sh -c "<i>processor</i>"’’ and writes the 59 output to @<i>timestamp.t.</i> If the <i>processor</i> finishes successfully, @<i>timestamp.t</i> 60 is renamed to @<i>timestamp.s,</i> and @<i>timestamp.u</i> is deleted; otherwise @<i>timestamp.t</i> 61 is deleted and the <i>processor</i> is started again. <b>svlogd</b> also saves any output 62 that the <i>processor</i> writes to file descriptor 5, and makes that output available 63 on file descriptor 4 when running <i>processor</i> on the next log file rotation. 64 <p> 65 A <i>processor</i> is run in the background. If <b>svlogd</b> sees a previously started 66 <i>processor</i> still running when trying to start a new one for the same <i>log</i>, 67 it blocks until the currently running <i>processor</i> has finished successfully. 68 Only the HUP signal works in that situation. Note that this may block any 69 program feeding its log data to <b>svlogd.</b> 70 <p> 71 <h3><a name='sect6'>Config</a></h3> 72 On startup, and after receiving 73 a HUP signal, <b>svlogd</b> checks for each log directory <i>log</i> if the configuration 74 file <i>log/config</i> exists, and if so, reads the file line by line and adjusts 75 configuration for <i>log</i> as follows: <p> 76 If the line is empty, or starts with 77 a ‘‘#’’, it is ignored. A line of the form 78 <dl> 79 80 <dt>s<i>size</i> </dt> 81 <dd>sets the maximum file size 82 of <i>current</i> when <b>svlogd</b> should rotate the current log file to <i>size</i> bytes. 83 Default is 1000000. If <i>size</i> is zero, <b>svlogd</b> doesn’t rotate log files. You 84 should set <i>size</i> to at least (2 * <i>len</i>). </dd> 85 86 <dt>n<i>num</i> </dt> 87 <dd>sets the number of old log files 88 <b>svlogd</b> should maintain to <i>num</i>. If <b>svlogd</b> sees more that <i>num</i> old log files 89 in <i>log</i> after log file rotation, it deletes the oldest one. Default is 10. 90 If <i>num</i> is zero, <b>svlogd</b> doesn’t remove old log files. </dd> 91 92 <dt>N<i>min</i> </dt> 93 <dd>sets the minimum 94 number of old log files <b>svlogd</b> should maintain to <i>min</i>. <i>min</i> must be less 95 than <i>num</i>. If <i>min</i> is set, and <b>svlogd</b> cannot write to <i>current</i> because the 96 filesystem is full, and it sees more than <i>min</i> old log files, it deletes 97 the oldest one. </dd> 98 99 <dt>t<i>timeout</i> </dt> 100 <dd>sets the maximum age of the <i>current</i> log file when 101 <b>svlogd</b> should rotate the current log file to <i>timeout</i> seconds. If <i>current</i> 102 is <i>timeout</i> seconds old, and is not empty, <b>svlogd</b> forces log file rotation. 103 </dd> 104 105 <dt>!<i>processor</i> </dt> 106 <dd>tells <b>svlogd</b> to feed each recent log file through <i>processor</i> 107 (see above) on log file rotation. By default log files are not processed. 108 </dd> 109 110 <dt>u<i>a.b.c.d[:port]</i> </dt> 111 <dd>tells <b>svlogd</b> to transmit the first <i>len</i> characters of selected 112 log messages to the IP address <i>a.b.c.d</i>, port number <i>port</i>. If <i>port</i> isn’t set, 113 the default port for syslog is used (514). <i>len</i> can be set through the -l 114 option, see below. If <b>svlogd</b> has trouble sending udp packets, it writes 115 error messages to the log directory. Attention: logging through udp is unreliable, 116 and should be used in private networks only. </dd> 117 118 <dt>U<i>a.b.c.d[:port]</i> </dt> 119 <dd>is the same as 120 the <i>u</i> line above, but the log messages are no longer written to the log 121 directory, but transmitted through udp only. Error messages from <b>svlogd</b> 122 concerning sending udp packages still go to the log directory. </dd> 123 124 <dt>p<i>prefix</i> </dt> 125 <dd>tells 126 <b>svlogd</b> to prefix each line to be written to the log directory, to standard 127 error, or through UDP, with <i>prefix</i>. </dd> 128 </dl> 129 <p> 130 If a line starts with a <i>-</i>, <i>+</i>, <i>e</i>, or <i>E</i>, 131 <b>svlogd</b> matches the first <i>len</i> characters of each log message against <i>pattern</i> 132 and acts accordingly: 133 <dl> 134 135 <dt>-<i>pattern</i> </dt> 136 <dd>the log message is deselected. </dd> 137 138 <dt>+<i>pattern</i> </dt> 139 <dd>the 140 log message is selected. </dd> 141 142 <dt>e<i>pattern</i> </dt> 143 <dd>the log message is selected to be printed 144 to standard error. </dd> 145 146 <dt>E<i>pattern</i> </dt> 147 <dd>the log message is deselected to be printed 148 to standard error. </dd> 149 </dl> 150 <p> 151 Initially each line is selected to be written to <i>log/current</i>. 152 Deselected log messages are discarded from <i>log</i>. Initially each line is deselected 153 to be written to standard err. Log messages selected for standard error 154 are written to standard error. 155 <h2><a name='sect7'>Pattern Matching</a></h2> 156 <b>svlogd</b> matches a log message 157 against the string <i>pattern</i> as follows: <p> 158 <i>pattern</i> is applied to the log message 159 one character by one, starting with the first. A character not a star (‘‘*’’) 160 and not a plus (‘‘+’’) matches itself. A plus matches the next character in 161 <i>pattern</i> in the log message one or more times. A star before the end of <i>pattern</i> 162 matches any string in the log message that does not include the next character 163 in <i>pattern</i>. A star at the end of <i>pattern</i> matches any string. <p> 164 Timestamps optionally 165 added by <b>svlogd</b> are not considered part of the log message. <p> 166 An <b>svlogd</b> pattern 167 is not a regular expression. For example consider a log message like this 168 <p> 169 2005-12-18_09:13:50.97618 tcpsvd: info: pid 1977 from 10.4.1.14<br> 170 <p> 171 The following pattern doesn’t match <p> 172 -*pid*<br> 173 <p> 174 because the first star matches up to the first p in tcpsvd, and then the 175 match fails because i is not s. To match this log message, you can use a 176 pattern like this instead <p> 177 -*: *: pid *<br> 178 179 <h2><a name='sect8'>Options</a></h2> 180 181 <dl> 182 183 <dt><b>-t</b> </dt> 184 <dd>timestamp. Prefix each selected line with a precise timestamp 185 (see the daemontools’ <b>tai64n</b> program) when writing to <i>log</i> or to standard 186 error. </dd> 187 188 <dt><b>-tt</b> </dt> 189 <dd>timestamp. Prefix each selected line with a human readable, sortable 190 UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx when writing to <i>log</i> or 191 to standard error. </dd> 192 193 <dt><b>-ttt</b> </dt> 194 <dd>timestamp. Prefix each selected line with a human 195 readable, sortable UTC timestamp of the form YYYY-MM-DDTHH:MM:SS.xxxxx when 196 writing to <i>log</i> or to standard error. </dd> 197 198 <dt><b>-r <i>c</b> </i></dt> 199 <dd>replace. <i>c</i> must be a single character. 200 Replace non-printable characters in log messages with <i>c</i>. Characters are replaced 201 before pattern matching is applied. </dd> 202 203 <dt><b>-R <i>xyz</b> </i></dt> 204 <dd>replace charset. Additionally to 205 non-printable characters, replace all characters found in <i>xyz</i> with <i>c</i> (default 206 ‘‘_’’). </dd> 207 208 <dt><b>-l <i>len</b> </i></dt> 209 <dd>line length. Pattern matching applies to the first <i>len</i> characters 210 of a log message only. Default is 1000. </dd> 211 212 <dt><b>-b <i>buflen</b> </i></dt> 213 <dd>buffer size. Set the size 214 of the buffer <b>svlogd</b> uses when reading from standard input and writing 215 to <i>logs</i> to <i>buflen</i>. Default is 1024. <i>buflen</i> must be greater than <i>len</i>. For <b>svlogd</b> 216 instances that process a lot of data in short time, the buffer size should 217 be increased to improve performance. </dd> 218 219 <dt><b>-v</b> </dt> 220 <dd>verbose. Print verbose messages to 221 standard error. </dd> 222 </dl> 223 224 <h2><a name='sect9'>Signals</a></h2> 225 If <b>svlogd</b> is sent a HUP signal, it closes and reopens 226 all <i>logs</i>, and updates their configuration according to <i>log/config</i>. If <b>svlogd</b> 227 has trouble opening a log directory, it prints a warning, and discards 228 this log directory. If <b>svlogd</b> is unable to open all log directories given 229 at the command line, it exits with an error. <p> 230 If <b>svlogd</b> is sent a TERM signal, 231 or if it sees end-of-file on standard input, it stops reading standard input, 232 processes the data in the buffer, waits for all <i>processor</i> subprocesses 233 to finish if any, and exits 0 as soon as possible. <p> 234 If <b>svlogd</b> is sent an 235 ALRM signal, it forces log file rotation for all <i>logs</i> with a non empty 236 <i>current</i> log file. 237 <h2><a name='sect10'>See Also</a></h2> 238 <i>sv(8)</i>, <i>runsv(8)</i>, <i>chpst(8)</i>, <i>runit(8)</i>, <i>runit-init(8)</i>, 239 <i>runsvdir(8)</i>, <i>runsvchdir(8)</i> <p> 240 <i>http://smarden.org/runit/</i> 241 <h2><a name='sect11'>Author</a></h2> 242 Gerrit Pape <pape@smarden.org> 243 <p> 244 245 <hr><p> 246 <a name='toc'><b>Table of Contents</b></a><p> 247 <ul> 248 <li><a name='toc0' href='#sect0'>Name</a></li> 249 <li><a name='toc1' href='#sect1'>Synopsis</a></li> 250 <li><a name='toc2' href='#sect2'>Description</a></li> 251 <ul> 252 <li><a name='toc3' href='#sect3'>Log Directory</a></li> 253 <li><a name='toc4' href='#sect4'>Log File Rotation</a></li> 254 <li><a name='toc5' href='#sect5'>Processor</a></li> 255 <li><a name='toc6' href='#sect6'>Config</a></li> 256 </ul> 257 <li><a name='toc7' href='#sect7'>Pattern Matching</a></li> 258 <li><a name='toc8' href='#sect8'>Options</a></li> 259 <li><a name='toc9' href='#sect9'>Signals</a></li> 260 <li><a name='toc10' href='#sect10'>See Also</a></li> 261 <li><a name='toc11' href='#sect11'>Author</a></li> 262 </ul> 263 </body> 264 </html>