--- /dev/null
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!-- $Id: yaz-log-man.xml,v 1.1 2004-11-23 14:11:03 heikki Exp $ -->
+<refentry id="yaz-log">
+ <refmeta>
+ <refentrytitle>yaz-log</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>yaz-log</refname>
+ <refpurpose>Log handling in all yaz-based programs</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>yaz-XXXX</command>
+ <arg choice="opt"><option>-v <replaceable>loglevel,...</replaceable></option></arg>
+ <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ All YAZ-based programs use a common log subsystem, and should support
+ common command line options for controlling it. This man page documents
+ those.
+ </para>
+ <para>
+ </para>
+ </refsect1>
+
+ <refsect1><title>OPTIONS</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>-l<replaceable> logfile</replaceable></term>
+ <listitem><para>
+ Specify the file where the log is to be written. If none is specified,
+ <filename>stderr</filename> is used. The log is appended to this file.
+ If the file grows overly large, it is silently rotated: It is renamed to
+ <replaceable>logfile</replaceable>.1 (old such file is deleted), and a
+ new file is opened. The limit defaults to 1GB, but can be set by the
+ program.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-v<replaceable> loglevel</replaceable></term>
+ <listitem><para>
+ Specify the logging level. The argument is a set of log level names,
+ separated by commas (no whitespace!), optionally preceded by a '-' to
+ negate that level. Most programs have their own default, often
+ containing <literal>fatal,warn,log</literal>, and some
+ application-specific values. The default list can be cleared with the
+ word <literal>none</literal>, or individual bits can be removed by
+ prefixing them with a dash '-'.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
+ <para>
+ Some of the log levels control the way the log is written.
+ </para>
+ <para>
+ <literal>flush</literal> causes the log to be flushed after every write.
+ This can have serious implications to performance, and should not be used
+ in production. On the other hand, when debugging a program crash, this can
+ be extremely useful. The option <literal>debug</literal> implies
+ <literal>flush</literal> as well.
+ </para>
+ <para>
+ <literal>notime</literal> prevents the writing of time stamps. This is
+ intended for automatic test scripts, which should produce predictable log
+ files that are easy to compare.
+ </para>
+
+ </refsect1>
+
+ <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
+ <para>
+ YAZ itself uses the following log levels:
+ </para>
+ <para>
+ <literal>fatal</literal> for fatal errors, that prevent further execution
+ of the program.
+ </para>
+ <para>
+ <literal>warn</literal> for warnings about things that should be corrected.
+ </para>
+ <para>
+ <literal>debug</literal> for debugging. This flag may be used temporarily
+ when developing or debugging yaz, or a program that uses yaz. It is
+ practically deprecated, you should be defining and using your own log
+ levels (see below).
+ </para>
+ <para>
+ <literal>all</literal> turns on almost all hard-coded log levels.
+ </para>
+ <para>
+ <literal>loglevel</literal> logs information about the log levels used by
+ the program. Every time the log level is changed, lists all bits that are
+ on. Every time a module asks for its log bits, this is logged. This can be
+ used for getting an idea of what log levels are available in any program
+ that uses yaz-log. Start the program with <literal>-v
+ none,loglevel</literal>, and do some common operations with it. Another way
+ is to grep for <function>yaz_log_module_level</function> in the source
+ code, as in
+ <screen>
+ find . -name '*.[ch]' -print |
+ xargs grep yaz_log_module_level |
+ grep '"' |
+ cut -d'"' -f2 |
+ sort -u
+ </screen>
+ </para>
+ <para>
+ <literal>eventl</literal>, <literal>malloc</literal>,
+ <literal>nmem</literal>, <literal>odr</literal> are used internally for
+ debugging yaz.
+ </para>
+ <para>
+ </para>
+ </refsect1>
+
+ <refsect1><title>LOG LEVELS FOR CLIENTS</title>
+ <para>
+ <literal>zoom</literal> logs the calls to the zoom API, which may be useful
+ in debugging client applications.
+ </para>
+ </refsect1>
+
+ <refsect1><title>LOG LEVELS FOR SERVERS</title>
+ <para>
+ <literal>server</literal> logs the server functions on a high level,
+ starting up, listening on a port, etc.
+ </para>
+ <para>
+ <literal>session</literal> logs individual sessions (connections).
+ </para>
+ <para>
+ <literal>request</literal> logs a one-liner for each request (init, search,
+ etc).
+ </para>
+ <para>
+ <literal>requestdetail</literal> logs the details of every request, before
+ it is passed to the back-end, and the results received from it.
+ </para>
+ <para>
+ Each server program (zebra, etc) is supposed to define its own log levels
+ in addition to these. As they depend on the server in question, they can
+ not be described here. See above how to find out about them.
+ </para>
+ </refsect1>
+
+ <refsect1><title>EXAMPLES</title>
+ <para>
+ See what log levels yaz-ztest is using:
+ <screen>
+ yaz-ztest -1 -v none,loglevel
+ 14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000
+ 14:43:29-23/11 [loglevel] Static log bit 00000001 'fatal' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00000002 'debug' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00000004 'warn' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00000008 'log' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00000080 'malloc' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00000800 'flush' is off
+ 14:43:29-23/11 [loglevel] Static log bit 00001000 'loglevel' is ON
+ 14:43:29-23/11 [loglevel] Static log bit 00002000 'server' is off
+ 14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
+ 14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
+ 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
+ 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server'
+ 14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl'
+ 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session'
+ 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request'
+ 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail'
+ 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr'
+ 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest'
+ </screen>
+ </para>
+ <para>
+ See the details of the requests for yaz-ztest
+ <screen>
+ ./yaz-ztest -1 -v requestdetail
+ 14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999
+ 14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200
+ 14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
+ 14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest
+ 14:45:38-23/11 yaz-ztest [requestdetail] Id: 81
+ 14:45:38-23/11 yaz-ztest [requestdetail] Name: YAZ
+ 14:45:38-23/11 yaz-ztest [requestdetail] Version: 2.0.28
+ 14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
+ 14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
+ 14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest.
+ 14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1'
+ 14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default'
+ 14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1
+ 14:45:39-23/11 yaz-ztest [requestdetail] term 'foo' (general)
+ 14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7
+ 14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo OK:7 hits
+ 14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest.
+ 14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
+ 14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
+ 14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1 OK 1 records returned
+ </screen>
+ </para>
+ </refsect1>
+
+ <refsect1><title>FILES</title>
+ <para>
+ <filename><replaceable>prefix</replaceable>/include/yaz/ylog.h</filename>
+ <filename><replaceable>prefix</replaceable>/src/log.c</filename>
+ </para>
+ </refsect1>
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ yaz(7)
+ yaz-ztest(8) yaz-client(1)
+ </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->
projects / yaz-moved-to-github.git / blobdiff