doc/yaz-log-man.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   3 [
   4      <!ENTITY % local SYSTEM "local.ent">
   5      %local;
   6      <!ENTITY % entities SYSTEM "entities.ent">
   7      %entities;
   8      <!ENTITY % common SYSTEM "common/common.ent">
   9      %common;
  10 ]>
  11 <!-- $Id: yaz-log-man.xml,v 1.6 2006-08-28 19:18:02 adam Exp $ -->
  12 <refentry id="yaz-log">
  13  <refentryinfo>
  14   <productname>YAZ</productname>
  15   <productnumber>&version;</productnumber>
  16  </refentryinfo>
  17
  18  <refmeta>
  19   <refentrytitle>yaz-log</refentrytitle>
  20   <manvolnum>7</manvolnum>
  21  </refmeta>
  22
  23  <refnamediv>
  24   <refname>yaz-log</refname>
  25   <refpurpose>Log handling in all yaz-based programs</refpurpose>
  26  </refnamediv>
  27
  28  <refsynopsisdiv>
  29   <cmdsynopsis>
  30    <command>yaz-XXXX</command>
  31    <arg choice="opt"><option>-v <replaceable>loglevel,...</replaceable></option></arg>
  32    <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
  33   </cmdsynopsis>
  34  </refsynopsisdiv>
  35
  36  <refsect1><title>DESCRIPTION</title>
  37   <para>
  38    All YAZ-based programs use a common log subsystem, and should support
  39    common command line options for controlling it. This man page documents
  40    those.
  41   </para>
  42   <para>
  43   </para>
  44  </refsect1>
  45
  46  <refsect1><title>OPTIONS</title>
  47
  48   <variablelist>
  49    <varlistentry>
  50     <term>-l<replaceable> logfile</replaceable></term>
  51     <listitem><para>
  52       Specify the file where the log is to be written. If none is specified,
  53       <filename>stderr</filename> is used. The log is appended to this file.
  54       If the file grows overly large, it is silently rotated: It is renamed to
  55       <replaceable>logfile</replaceable>.1 (old such file is deleted), and a
  56       new file is opened. The limit defaults to 1GB, but can be set by the
  57       program.
  58     </para></listitem>
  59    </varlistentry>
  60
  61    <varlistentry>
  62     <term>-v<replaceable> loglevel</replaceable></term>
  63     <listitem><para>
  64       Specify the logging level. The argument is a set of log level names,
  65       separated by commas (no whitespace!), optionally preceded by a '-' to
  66       negate that level. Most programs have their own default, often
  67       containing <literal>fatal,warn,log</literal>, and some
  68       application-specific values. The default list can be cleared with the
  69       word <literal>none</literal>, or individual bits can be removed by
  70       prefixing them with a dash '-'.
  71      </para></listitem>
  72    </varlistentry>
  73
  74   </variablelist>
  75  </refsect1>
  76
  77  <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
  78   <para>
  79    Some of the log levels control the way the log is written.
  80   </para>
  81   <para>
  82    <literal>flush</literal> causes the log to be flushed after every write.
  83    This can have serious implications to performance, and should not be used
  84    in production. On the other hand, when debugging a program crash, this can
  85    be extremely useful. The option <literal>debug</literal> implies
  86    <literal>flush</literal> as well.
  87   </para>
  88   <para>
  89    <literal>notime</literal> prevents the writing of time stamps. This is
  90    intended for automatic test scripts, which should produce predictable log
  91    files that are easy to compare.
  92   </para>
  93
  94  </refsect1>
  95
  96  <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
  97   <para>
  98    YAZ itself uses the following log levels:
  99   </para>
 100   <para>
 101    <literal>fatal</literal> for fatal errors, that prevent further execution
 102    of the program.
 103   </para>
 104   <para>
 105    <literal>warn</literal> for warnings about things that should be corrected.
 106   </para>
 107   <para>
 108    <literal>debug</literal> for debugging. This flag may be used temporarily
 109    when developing or debugging yaz, or a program that uses yaz. It is
 110    practically deprecated, you should be defining and using your own log
 111    levels (see below).
 112   </para>
 113   <para>
 114    <literal>all</literal> turns on almost all hard-coded log levels.
 115   </para>
 116   <para>
 117    <literal>loglevel</literal> logs information about the log levels used by
 118    the program. Every time the log level is changed, lists all bits that are
 119    on. Every time a module asks for its log bits, this is logged. This can be
 120    used for getting an idea of what log levels are available in any program
 121    that uses yaz-log. Start the program with <literal>-v
 122    none,loglevel</literal>, and do some common operations with it. Another way
 123    is to grep for <function>yaz_log_module_level</function> in the source
 124    code, as in
 125    <screen>
 126       find . -name '*.[ch]' -print |
 127          xargs grep yaz_log_module_level |
 128          grep '"' |
 129          cut -d'"' -f2 |
 130          sort -u
 131    </screen>
 132   </para>
 133   <para>
 134    <literal>eventl</literal>, <literal>malloc</literal>,
 135    <literal>nmem</literal>, <literal>odr</literal> are used internally for
 136    debugging yaz.
 137   </para>
 138   <para>
 139   </para>
 140  </refsect1>
 141
 142  <refsect1><title>LOG LEVELS FOR CLIENTS</title>
 143   <para>
 144    <literal>zoom</literal> logs the calls to the zoom API, which may be useful
 145    in debugging client applications.
 146   </para>
 147  </refsect1>
 148
 149  <refsect1><title>LOG LEVELS FOR SERVERS</title>
 150   <para>
 151    <literal>server</literal> logs the server functions on a high level,
 152    starting up, listening on a port, etc.
 153   </para>
 154   <para>
 155    <literal>session</literal> logs individual sessions (connections).
 156   </para>
 157   <para>
 158    <literal>request</literal> logs a one-liner for each request (init, search,
 159    etc).
 160   </para>
 161   <para>
 162    <literal>requestdetail</literal> logs the details of every request, before
 163    it is passed to the back-end, and the results received from it.
 164   </para>
 165   <para>
 166    Each server program (zebra, etc) is supposed to define its own log levels
 167    in addition to these. As they depend on the server in question, they can
 168    not be described here. See above how to find out about them.
 169   </para>
 170  </refsect1>
 171
 172  <refsect1><title>EXAMPLES</title>
 173   <para>
 174    See what log levels yaz-ztest is using:
 175    <screen>
 176     yaz-ztest -1 -v none,loglevel
 177     14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000
 178     14:43:29-23/11 [loglevel] Static  log bit 00000001 'fatal' is off
 179     14:43:29-23/11 [loglevel] Static  log bit 00000002 'debug' is off
 180     14:43:29-23/11 [loglevel] Static  log bit 00000004 'warn' is off
 181     14:43:29-23/11 [loglevel] Static  log bit 00000008 'log' is off
 182     14:43:29-23/11 [loglevel] Static  log bit 00000080 'malloc' is off
 183     14:43:29-23/11 [loglevel] Static  log bit 00000800 'flush' is off
 184     14:43:29-23/11 [loglevel] Static  log bit 00001000 'loglevel' is ON
 185     14:43:29-23/11 [loglevel] Static  log bit 00002000 'server' is off
 186     14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
 187     14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
 188     14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
 189     14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server'
 190     14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl'
 191     14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
 192     14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request'
 193     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail'
 194     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr'
 195     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest'
 196    </screen>
 197   </para>
 198   <para>
 199    See the details of the requests for yaz-ztest
 200    <screen>
 201    ./yaz-ztest -1 -v requestdetail
 202    14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999
 203    14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200
 204    14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
 205    14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest
 206    14:45:38-23/11 yaz-ztest [requestdetail] Id:        81
 207    14:45:38-23/11 yaz-ztest [requestdetail] Name:      YAZ
 208    14:45:38-23/11 yaz-ztest [requestdetail] Version:   2.0.28
 209    14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
 210    14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
 211    14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest.
 212    14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1'
 213    14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default'
 214    14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1
 215    14:45:39-23/11 yaz-ztest [requestdetail]  term 'foo' (general)
 216    14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7
 217    14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo  OK:7 hits
 218    14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest.
 219    14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
 220    14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
 221    14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1  OK 1 records returned
 222    </screen>
 223   </para>
 224  </refsect1>
 225
 226  <refsect1><title>FILES</title>
 227   <para>
 228    <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
 229    <filename><replaceable>prefix</replaceable>/src/log.c</filename>
 230   </para>
 231  </refsect1>
 232  <refsect1><title>SEE ALSO</title>
 233   <para>
 234    yaz(7)
 235    yaz-ztest(8) yaz-client(1)
 236   </para>
 237  </refsect1>
 238 </refentry>
 239
 240 <!-- Keep this comment at the end of the file
 241 Local variables:
 242 mode: sgml
 243 sgml-omittag:t
 244 sgml-shorttag:t
 245 sgml-minimize-attributes:nil
 246 sgml-always-quote-attributes:t
 247 sgml-indent-step:1
 248 sgml-indent-data:t
 249 sgml-parent-document:nil
 250 sgml-local-catalogs: nil
 251 sgml-namecase-general:t
 252 End:
 253 -->