doc/yaz-log-man.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <!-- $Id: yaz-log-man.xml,v 1.4 2006-04-25 11:25:08 marc Exp $ -->
   3 <refentry id="yaz-log">
   4  <refmeta>
   5   <refentrytitle>yaz-log</refentrytitle>
   6   <manvolnum>7</manvolnum>
   7  </refmeta>
   8
   9  <refnamediv>
  10   <refname>yaz-log</refname>
  11   <refpurpose>Log handling in all yaz-based programs</refpurpose>
  12  </refnamediv>
  13
  14  <refsynopsisdiv>
  15   <cmdsynopsis>
  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>
  19   </cmdsynopsis>
  20  </refsynopsisdiv>
  21
  22  <refsect1><title>DESCRIPTION</title>
  23   <para>
  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
  26    those.
  27   </para>
  28   <para>
  29   </para>
  30  </refsect1>
  31
  32  <refsect1><title>OPTIONS</title>
  33
  34   <variablelist>
  35    <varlistentry>
  36     <term>-l<replaceable> logfile</replaceable></term>
  37     <listitem><para>
  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
  43       program.
  44     </para></listitem>
  45    </varlistentry>
  46
  47    <varlistentry>
  48     <term>-v<replaceable> loglevel</replaceable></term>
  49     <listitem><para>
  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 '-'.
  57      </para></listitem>
  58    </varlistentry>
  59
  60   </variablelist>
  61  </refsect1>
  62
  63  <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
  64   <para>
  65    Some of the log levels control the way the log is written.
  66   </para>
  67   <para>
  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.
  73   </para>
  74   <para>
  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.
  78   </para>
  79
  80  </refsect1>
  81
  82  <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
  83   <para>
  84    YAZ itself uses the following log levels:
  85   </para>
  86   <para>
  87    <literal>fatal</literal> for fatal errors, that prevent further execution
  88    of the program.
  89   </para>
  90   <para>
  91    <literal>warn</literal> for warnings about things that should be corrected.
  92   </para>
  93   <para>
  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
  97    levels (see below).
  98   </para>
  99   <para>
 100    <literal>all</literal> turns on almost all hard-coded log levels.
 101   </para>
 102   <para>
 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
 110    code, as in
 111    <screen>
 112       find . -name '*.[ch]' -print |
 113          xargs grep yaz_log_module_level |
 114          grep '"' |
 115          cut -d'"' -f2 |
 116          sort -u
 117    </screen>
 118   </para>
 119   <para>
 120    <literal>eventl</literal>, <literal>malloc</literal>,
 121    <literal>nmem</literal>, <literal>odr</literal> are used internally for
 122    debugging yaz.
 123   </para>
 124   <para>
 125   </para>
 126  </refsect1>
 127
 128  <refsect1><title>LOG LEVELS FOR CLIENTS</title>
 129   <para>
 130    <literal>zoom</literal> logs the calls to the zoom API, which may be useful
 131    in debugging client applications.
 132   </para>
 133  </refsect1>
 134
 135  <refsect1><title>LOG LEVELS FOR SERVERS</title>
 136   <para>
 137    <literal>server</literal> logs the server functions on a high level,
 138    starting up, listening on a port, etc.
 139   </para>
 140   <para>
 141    <literal>session</literal> logs individual sessions (connections).
 142   </para>
 143   <para>
 144    <literal>request</literal> logs a one-liner for each request (init, search,
 145    etc).
 146   </para>
 147   <para>
 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.
 150   </para>
 151   <para>
 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.
 155   </para>
 156  </refsect1>
 157
 158  <refsect1><title>EXAMPLES</title>
 159   <para>
 160    See what log levels yaz-ztest is using:
 161    <screen>
 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'
 182    </screen>
 183   </para>
 184   <para>
 185    See the details of the requests for yaz-ztest
 186    <screen>
 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
 208    </screen>
 209   </para>
 210  </refsect1>
 211
 212  <refsect1><title>FILES</title>
 213   <para>
 214    <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
 215    <filename><replaceable>prefix</replaceable>/src/log.c</filename>
 216   </para>
 217  </refsect1>
 218  <refsect1><title>SEE ALSO</title>
 219   <para>
 220    yaz(7)
 221    yaz-ztest(8) yaz-client(1)
 222   </para>
 223  </refsect1>
 224 </refentry>
 225
 226 <!-- Keep this comment at the end of the file
 227 Local variables:
 228 mode: sgml
 229 sgml-omittag:t
 230 sgml-shorttag:t
 231 sgml-minimize-attributes:nil
 232 sgml-always-quote-attributes:t
 233 sgml-indent-step:1
 234 sgml-indent-data:t
 235 sgml-parent-document:nil
 236 sgml-local-catalogs: nil
 237 sgml-namecase-general:t
 238 End:
 239 -->