1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2 <!-- $Id: yaz-log-man.xml,v 1.2 2004-12-13 20:17:41 adam Exp $ -->
3 <refentry id="yaz-log">
5 <refentrytitle>yaz-log</refentrytitle>
6 <manvolnum>7</manvolnum>
10 <refname>yaz-log</refname>
11 <refpurpose>Log handling in all yaz-based programs</refpurpose>
16 <command>yaz-XXXX</command>
17 <arg choice="opt"><option>-v <replaceable>loglevel,...</replaceable></option></arg>
18 <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
22 <refsect1><title>DESCRIPTION</title>
24 All YAZ-based programs use a common log subsystem, and should support
25 common command line options for controlling it. This man page documents
32 <refsect1><title>OPTIONS</title>
36 <term>-l<replaceable> logfile</replaceable></term>
38 Specify the file where the log is to be written. If none is specified,
39 <filename>stderr</filename> is used. The log is appended to this file.
40 If the file grows overly large, it is silently rotated: It is renamed to
41 <replaceable>logfile</replaceable>.1 (old such file is deleted), and a
42 new file is opened. The limit defaults to 1GB, but can be set by the
48 <term>-v<replaceable> loglevel</replaceable></term>
50 Specify the logging level. The argument is a set of log level names,
51 separated by commas (no whitespace!), optionally preceded by a '-' to
52 negate that level. Most programs have their own default, often
53 containing <literal>fatal,warn,log</literal>, and some
54 application-specific values. The default list can be cleared with the
55 word <literal>none</literal>, or individual bits can be removed by
56 prefixing them with a dash '-'.
63 <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
65 Some of the log levels control the way the log is written.
68 <literal>flush</literal> causes the log to be flushed after every write.
69 This can have serious implications to performance, and should not be used
70 in production. On the other hand, when debugging a program crash, this can
71 be extremely useful. The option <literal>debug</literal> implies
72 <literal>flush</literal> as well.
75 <literal>notime</literal> prevents the writing of time stamps. This is
76 intended for automatic test scripts, which should produce predictable log
77 files that are easy to compare.
82 <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
84 YAZ itself uses the following log levels:
87 <literal>fatal</literal> for fatal errors, that prevent further execution
91 <literal>warn</literal> for warnings about things that should be corrected.
94 <literal>debug</literal> for debugging. This flag may be used temporarily
95 when developing or debugging yaz, or a program that uses yaz. It is
96 practically deprecated, you should be defining and using your own log
100 <literal>all</literal> turns on almost all hard-coded log levels.
103 <literal>loglevel</literal> logs information about the log levels used by
104 the program. Every time the log level is changed, lists all bits that are
105 on. Every time a module asks for its log bits, this is logged. This can be
106 used for getting an idea of what log levels are available in any program
107 that uses yaz-log. Start the program with <literal>-v
108 none,loglevel</literal>, and do some common operations with it. Another way
109 is to grep for <function>yaz_log_module_level</function> in the source
112 find . -name '*.[ch]' -print |
113 xargs grep yaz_log_module_level |
120 <literal>eventl</literal>, <literal>malloc</literal>,
121 <literal>nmem</literal>, <literal>odr</literal> are used internally for
128 <refsect1><title>LOG LEVELS FOR CLIENTS</title>
130 <literal>zoom</literal> logs the calls to the zoom API, which may be useful
131 in debugging client applications.
135 <refsect1><title>LOG LEVELS FOR SERVERS</title>
137 <literal>server</literal> logs the server functions on a high level,
138 starting up, listening on a port, etc.
141 <literal>session</literal> logs individual sessions (connections).
144 <literal>request</literal> logs a one-liner for each request (init, search,
148 <literal>requestdetail</literal> logs the details of every request, before
149 it is passed to the back-end, and the results received from it.
152 Each server program (zebra, etc) is supposed to define its own log levels
153 in addition to these. As they depend on the server in question, they can
154 not be described here. See above how to find out about them.
158 <refsect1><title>EXAMPLES</title>
160 See what log levels yaz-ztest is using:
162 yaz-ztest -1 -v none,loglevel
163 14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000
164 14:43:29-23/11 [loglevel] Static log bit 00000001 'fatal' is off
165 14:43:29-23/11 [loglevel] Static log bit 00000002 'debug' is off
166 14:43:29-23/11 [loglevel] Static log bit 00000004 'warn' is off
167 14:43:29-23/11 [loglevel] Static log bit 00000008 'log' is off
168 14:43:29-23/11 [loglevel] Static log bit 00000080 'malloc' is off
169 14:43:29-23/11 [loglevel] Static log bit 00000800 'flush' is off
170 14:43:29-23/11 [loglevel] Static log bit 00001000 'loglevel' is ON
171 14:43:29-23/11 [loglevel] Static log bit 00002000 'server' is off
172 14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
173 14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
174 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
175 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server'
176 14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl'
177 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
178 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request'
179 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail'
180 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr'
181 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest'
185 See the details of the requests for yaz-ztest
187 ./yaz-ztest -1 -v requestdetail
188 14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999
189 14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200
190 14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
191 14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest
192 14:45:38-23/11 yaz-ztest [requestdetail] Id: 81
193 14:45:38-23/11 yaz-ztest [requestdetail] Name: YAZ
194 14:45:38-23/11 yaz-ztest [requestdetail] Version: 2.0.28
195 14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
196 14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
197 14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest.
198 14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1'
199 14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default'
200 14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1
201 14:45:39-23/11 yaz-ztest [requestdetail] term 'foo' (general)
202 14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7
203 14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo OK:7 hits
204 14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest.
205 14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
206 14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
207 14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1 OK 1 records returned
212 <refsect1><title>FILES</title>
214 <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
215 <filename><replaceable>prefix</replaceable>/src/log.c</filename>
218 <refsect1><title>SEE ALSO</title>
221 yaz-ztest(8) yaz-client(1)
226 <!-- Keep this comment at the end of the file
231 sgml-minimize-attributes:nil
232 sgml-always-quote-attributes:t
235 sgml-parent-document:nil
236 sgml-local-catalogs: nil
237 sgml-namecase-general:t