1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
2 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 <!ENTITY % local SYSTEM "local.ent">
6 <!ENTITY % entities SYSTEM "entities.ent">
8 <!ENTITY % idcommon SYSTEM "common/common.ent">
11 <refentry id="yaz-log">
13 <productname>YAZ</productname>
14 <productnumber>&version;</productnumber>
15 <info><orgname>Index Data</orgname></info>
19 <refentrytitle>yaz-log</refentrytitle>
20 <manvolnum>7</manvolnum>
21 <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
25 <refname>yaz-log</refname>
26 <refpurpose>Log handling in all yaz-based programs</refpurpose>
31 <command>yaz-XXXX</command>
32 <arg choice="opt"><option>-v <replaceable>loglevel,...</replaceable></option></arg>
33 <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
37 <refsect1><title>DESCRIPTION</title>
39 All YAZ-based programs use a common log subsystem, and should support
40 common command line options for controlling it. This man page documents
47 <refsect1><title>OPTIONS</title>
51 <term>-l<replaceable> logfile</replaceable></term>
54 Specify the file where the log is to be written. If none is specified,
55 <filename>stderr</filename> is used. The log is appended to this file.
56 If the file grows overly large, it is silently rotated: It is renamed to
57 <replaceable>logfile</replaceable>.1,
58 <replaceable>logfile</replaceable>.2, .., 9
59 (old such file is deleted), and a
60 new file is opened. The limit defaults to 1GB, but can be set by the
62 The rotating limit can be specified with option <literal>-r</literal>
63 for the YAZ frontend server (yaz-ztest).
66 Rotation can also be implicitly enabled by using a filename
67 which gets changed for a given date, due to substitutions as
68 given by the strftime(3) function.
74 <term>-v<replaceable> loglevel</replaceable></term>
76 Specify the logging level. The argument is a set of log level names,
77 separated by commas (no whitespace!), optionally preceded by a '-' to
78 negate that level. Most programs have their own default, often
79 containing <literal>fatal,warn,log</literal>, and some
80 application-specific values. The default list can be cleared with the
81 word <literal>none</literal>, or individual bits can be removed by
82 prefixing them with a dash '-'.
89 <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
91 Some of the log levels control the way the log is written.
94 <literal>flush</literal> causes the log to be flushed after every write.
95 This can have serious implications to performance, and should not be used
96 in production. On the other hand, when debugging a program crash, this can
97 be extremely useful. The option <literal>debug</literal> implies
98 <literal>flush</literal> as well.
101 <literal>notime</literal> prevents the writing of time stamps. This is
102 intended for automatic test scripts, which should produce predictable log
103 files that are easy to compare.
108 <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
110 YAZ itself uses the following log levels:
113 <literal>fatal</literal> for fatal errors, that prevent further execution
117 <literal>warn</literal> for warnings about things that should be corrected.
120 <literal>debug</literal> for debugging. This flag may be used temporarily
121 when developing or debugging yaz, or a program that uses yaz. It is
122 practically deprecated, you should be defining and using your own log
126 <literal>all</literal> turns on almost all hard-coded log levels.
129 <literal>loglevel</literal> logs information about the log levels used by
130 the program. Every time the log level is changed, lists all bits that are
131 on. Every time a module asks for its log bits, this is logged. This can be
132 used for getting an idea of what log levels are available in any program
133 that uses yaz-log. Start the program with <literal>-v
134 none,loglevel</literal>, and do some common operations with it. Another way
135 is to grep for <function>yaz_log_module_level</function> in the source
138 find . -name '*.[ch]' -print |
139 xargs grep yaz_log_module_level |
146 <literal>eventl</literal>, <literal>malloc</literal>,
147 <literal>nmem</literal>, <literal>odr</literal> are used internally for
154 <refsect1><title>LOG LEVELS FOR CLIENTS</title>
156 <literal>zoom</literal> logs the calls to the zoom API, which may be useful
157 in debugging client applications.
161 <refsect1><title>LOG LEVELS FOR SERVERS</title>
163 <literal>server</literal> logs the server functions on a high level,
164 starting up, listening on a port, etc.
167 <literal>session</literal> logs individual sessions (connections).
170 <literal>request</literal> logs a one-liner for each request (init, search,
174 <literal>requestdetail</literal> logs the details of every request, before
175 it is passed to the back-end, and the results received from it.
178 Each server program (zebra, etc) is supposed to define its own log levels
179 in addition to these. As they depend on the server in question, they can
180 not be described here. See above how to find out about them.
184 <refsect1><title>LOGGING EXAMPLES</title>
186 See what log levels yaz-ztest is using:
188 yaz-ztest -1 -v none,loglevel
189 14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000
190 14:43:29-23/11 [loglevel] Static log bit 00000001 'fatal' is off
191 14:43:29-23/11 [loglevel] Static log bit 00000002 'debug' is off
192 14:43:29-23/11 [loglevel] Static log bit 00000004 'warn' is off
193 14:43:29-23/11 [loglevel] Static log bit 00000008 'log' is off
194 14:43:29-23/11 [loglevel] Static log bit 00000080 'malloc' is off
195 14:43:29-23/11 [loglevel] Static log bit 00000800 'flush' is off
196 14:43:29-23/11 [loglevel] Static log bit 00001000 'loglevel' is ON
197 14:43:29-23/11 [loglevel] Static log bit 00002000 'server' is off
198 14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
199 14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
200 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
201 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server'
202 14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl'
203 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
204 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request'
205 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail'
206 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr'
207 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest'
211 See the details of the requests for yaz-ztest
213 ./yaz-ztest -1 -v requestdetail
214 14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999
215 14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200
216 14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
217 14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest
218 14:45:38-23/11 yaz-ztest [requestdetail] Id: 81
219 14:45:38-23/11 yaz-ztest [requestdetail] Name: YAZ
220 14:45:38-23/11 yaz-ztest [requestdetail] Version: 2.0.28
221 14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
222 14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
223 14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest.
224 14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1'
225 14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default'
226 14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1
227 14:45:39-23/11 yaz-ztest [requestdetail] term 'foo' (general)
228 14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7
229 14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo OK:7 hits
230 14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest.
231 14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
232 14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
233 14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1 OK 1 records returned
238 <refsect1><title>LOG FILENAME EXAMPLES</title>
240 A file with format my_YYYYMMDD.log is where Y, M, D is year, month, and day
241 digits is given as follows
242 <literal>-l my_%Y%m%d.log</literal> . And since the filename
243 is depending on day, rotaion will occur on midnight.
246 A weekly log could be specified as
247 <literal>-l my_%Y%U.log</literal>.
251 <refsect1><title>FILES</title>
253 <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
254 <filename><replaceable>prefix</replaceable>/src/log.c</filename>
257 <refsect1><title>SEE ALSO</title>
260 <refentrytitle>yaz</refentrytitle>
261 <manvolnum>7</manvolnum>
265 <refentrytitle>yaz-ztest</refentrytitle>
266 <manvolnum>8</manvolnum>
270 <refentrytitle>yaz-client</refentrytitle>
271 <manvolnum>1</manvolnum>
275 <refentrytitle>strftime</refentrytitle>
276 <manvolnum>3</manvolnum>
282 <!-- Keep this comment at the end of the file
287 sgml-minimize-attributes:nil
288 sgml-always-quote-attributes:t
291 sgml-parent-document:nil
292 sgml-local-catalogs: nil
293 sgml-namecase-general:t