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.7 2006-10-04 13:21:33 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>
  52      <para>
  53       Specify the file where the log is to be written. If none is specified,
  54       <filename>stderr</filename> is used. The log is appended to this file.
  55       If the file grows overly large, it is silently rotated: It is renamed to
  56       <replaceable>logfile</replaceable>.1,
  57       <replaceable>logfile</replaceable>.2, .., 9
  58       (old such file is deleted), and a
  59       new file is opened. The limit defaults to 1GB, but can be set by the
  60       program.
  61       The rotating limit can be specified with option <literal>-r</literal>
  62       for the YAZ frontend server (yaz-ztest).
  63      </para>
  64      <para>
  65       Rotation can also be implicitly enabled by using a filename
  66       which gets changed for a given date, due to substitutions as
  67       given by the strftime(3) function.
  68      </para>
  69     </listitem>
  70    </varlistentry>
  71
  72    <varlistentry>
  73     <term>-v<replaceable> loglevel</replaceable></term>
  74     <listitem><para>
  75       Specify the logging level. The argument is a set of log level names,
  76       separated by commas (no whitespace!), optionally preceded by a '-' to
  77       negate that level. Most programs have their own default, often
  78       containing <literal>fatal,warn,log</literal>, and some
  79       application-specific values. The default list can be cleared with the
  80       word <literal>none</literal>, or individual bits can be removed by
  81       prefixing them with a dash '-'.
  82      </para></listitem>
  83    </varlistentry>
  84
  85   </variablelist>
  86  </refsect1>
  87
  88  <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
  89   <para>
  90    Some of the log levels control the way the log is written.
  91   </para>
  92   <para>
  93    <literal>flush</literal> causes the log to be flushed after every write.
  94    This can have serious implications to performance, and should not be used
  95    in production. On the other hand, when debugging a program crash, this can
  96    be extremely useful. The option <literal>debug</literal> implies
  97    <literal>flush</literal> as well.
  98   </para>
  99   <para>
 100    <literal>notime</literal> prevents the writing of time stamps. This is
 101    intended for automatic test scripts, which should produce predictable log
 102    files that are easy to compare.
 103   </para>
 104
 105  </refsect1>
 106
 107  <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
 108   <para>
 109    YAZ itself uses the following log levels:
 110   </para>
 111   <para>
 112    <literal>fatal</literal> for fatal errors, that prevent further execution
 113    of the program.
 114   </para>
 115   <para>
 116    <literal>warn</literal> for warnings about things that should be corrected.
 117   </para>
 118   <para>
 119    <literal>debug</literal> for debugging. This flag may be used temporarily
 120    when developing or debugging yaz, or a program that uses yaz. It is
 121    practically deprecated, you should be defining and using your own log
 122    levels (see below).
 123   </para>
 124   <para>
 125    <literal>all</literal> turns on almost all hard-coded log levels.
 126   </para>
 127   <para>
 128    <literal>loglevel</literal> logs information about the log levels used by
 129    the program. Every time the log level is changed, lists all bits that are
 130    on. Every time a module asks for its log bits, this is logged. This can be
 131    used for getting an idea of what log levels are available in any program
 132    that uses yaz-log. Start the program with <literal>-v
 133    none,loglevel</literal>, and do some common operations with it. Another way
 134    is to grep for <function>yaz_log_module_level</function> in the source
 135    code, as in
 136    <screen>
 137       find . -name '*.[ch]' -print |
 138          xargs grep yaz_log_module_level |
 139          grep '"' |
 140          cut -d'"' -f2 |
 141          sort -u
 142    </screen>
 143   </para>
 144   <para>
 145    <literal>eventl</literal>, <literal>malloc</literal>,
 146    <literal>nmem</literal>, <literal>odr</literal> are used internally for
 147    debugging yaz.
 148   </para>
 149   <para>
 150   </para>
 151  </refsect1>
 152
 153  <refsect1><title>LOG LEVELS FOR CLIENTS</title>
 154   <para>
 155    <literal>zoom</literal> logs the calls to the zoom API, which may be useful
 156    in debugging client applications.
 157   </para>
 158  </refsect1>
 159
 160  <refsect1><title>LOG LEVELS FOR SERVERS</title>
 161   <para>
 162    <literal>server</literal> logs the server functions on a high level,
 163    starting up, listening on a port, etc.
 164   </para>
 165   <para>
 166    <literal>session</literal> logs individual sessions (connections).
 167   </para>
 168   <para>
 169    <literal>request</literal> logs a one-liner for each request (init, search,
 170    etc).
 171   </para>
 172   <para>
 173    <literal>requestdetail</literal> logs the details of every request, before
 174    it is passed to the back-end, and the results received from it.
 175   </para>
 176   <para>
 177    Each server program (zebra, etc) is supposed to define its own log levels
 178    in addition to these. As they depend on the server in question, they can
 179    not be described here. See above how to find out about them.
 180   </para>
 181  </refsect1>
 182
 183  <refsect1><title>LOGGING EXAMPLES</title>
 184   <para>
 185    See what log levels yaz-ztest is using:
 186    <screen>
 187     yaz-ztest -1 -v none,loglevel
 188     14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000
 189     14:43:29-23/11 [loglevel] Static  log bit 00000001 'fatal' is off
 190     14:43:29-23/11 [loglevel] Static  log bit 00000002 'debug' is off
 191     14:43:29-23/11 [loglevel] Static  log bit 00000004 'warn' is off
 192     14:43:29-23/11 [loglevel] Static  log bit 00000008 'log' is off
 193     14:43:29-23/11 [loglevel] Static  log bit 00000080 'malloc' is off
 194     14:43:29-23/11 [loglevel] Static  log bit 00000800 'flush' is off
 195     14:43:29-23/11 [loglevel] Static  log bit 00001000 'loglevel' is ON
 196     14:43:29-23/11 [loglevel] Static  log bit 00002000 'server' is off
 197     14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
 198     14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
 199     14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
 200     14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server'
 201     14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl'
 202     14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
 203     14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request'
 204     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail'
 205     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr'
 206     14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest'
 207    </screen>
 208   </para>
 209   <para>
 210    See the details of the requests for yaz-ztest
 211    <screen>
 212    ./yaz-ztest -1 -v requestdetail
 213    14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999
 214    14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200
 215    14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
 216    14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest
 217    14:45:38-23/11 yaz-ztest [requestdetail] Id:        81
 218    14:45:38-23/11 yaz-ztest [requestdetail] Name:      YAZ
 219    14:45:38-23/11 yaz-ztest [requestdetail] Version:   2.0.28
 220    14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
 221    14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
 222    14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest.
 223    14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1'
 224    14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default'
 225    14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1
 226    14:45:39-23/11 yaz-ztest [requestdetail]  term 'foo' (general)
 227    14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7
 228    14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo  OK:7 hits
 229    14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest.
 230    14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
 231    14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
 232    14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1  OK 1 records returned
 233    </screen>
 234   </para>
 235  </refsect1>
 236
 237  <refsect1><title>LOG FILENAME EXAMPLES</title>
 238   <para>
 239    A file with format my_YYYYMMDD.log is where Y, M, D is year, month, and day
 240    digits is given as follows
 241    <literal>-l my_%Y%m%d.log</literal> . And since the filename
 242    is depending on day, rotaion will occur on midnight.
 243   </para>
 244   <para>
 245    A weekly log could be specified as
 246    <literal>-l my_%Y%U.log</literal>.
 247   </para>
 248  </refsect1>
 249
 250  <refsect1><title>FILES</title>
 251   <para>
 252    <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
 253    <filename><replaceable>prefix</replaceable>/src/log.c</filename>
 254   </para>
 255  </refsect1>
 256  <refsect1><title>SEE ALSO</title>
 257   <para>
 258    <citerefentry>
 259     <refentrytitle>yaz</refentrytitle>
 260     <manvolnum>7</manvolnum>
 261    </citerefentry>
 262
 263    <citerefentry>
 264     <refentrytitle>yaz-ztest</refentrytitle>
 265     <manvolnum>8</manvolnum>
 266    </citerefentry>
 267
 268    <citerefentry>
 269     <refentrytitle>yaz-client</refentrytitle>
 270     <manvolnum>1</manvolnum>
 271    </citerefentry>
 272
 273    <citerefentry>
 274     <refentrytitle>strftime</refentrytitle>
 275     <manvolnum>3</manvolnum>
 276    </citerefentry>
 277   </para>
 278  </refsect1>
 279 </refentry>
 280
 281 <!-- Keep this comment at the end of the file
 282 Local variables:
 283 mode: sgml
 284 sgml-omittag:t
 285 sgml-shorttag:t
 286 sgml-minimize-attributes:nil
 287 sgml-always-quote-attributes:t
 288 sgml-indent-step:1
 289 sgml-indent-data:t
 290 sgml-parent-document:nil
 291 sgml-local-catalogs: nil
 292 sgml-namecase-general:t
 293 End:
 294 -->