-<!-- $Id: tools.xml,v 1.41 2004-11-21 21:55:15 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.42 2004-11-23 14:11:03 heikki Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
The <literal>log level</literal> is a bit mask, that says on which level(s)
the log entry should be made, and optionally set some behaviour of the
logging. In the most simple cases, it can be one of <literal>YLOG_FATAL,
- YLOG_DEBUG, YLOG_WARN, YLOG_LOG</literal>. Those can be combined with bits
- that modify the way the log entry is written:<literal>YLOG_ERRNO,
- YLOG_NOTIME, YLOG_FLUSH</literal>.
- Most of the rest of the bits are deprecated, and should not be used.
+ YLOG_DEBUG, YLOG_WARN, YLOG_LOG</literal>. Those can be combined with bits
+ that modify the way the log entry is written:<literal>YLOG_ERRNO,
+ YLOG_NOTIME, YLOG_FLUSH</literal>.
+ Most of the rest of the bits are deprecated, and should not be used. Use
+ the dynamic log levels instead.
</para>
<para>
</para>
<para>
+ Yaz uses the following dynamic log levels:
+ <literal>server, session, request, requestdetail</literal> for the server
+ functionality.
+ <literal>zoom</literal> for the zoom client api.
+ <literal>ztest</literal> for the simple test server.
+ <literal>malloc, nmem, odr, eventl</literal> for internal debugging of yaz itself.
+ Of course, any program using yaz is welcome to define as many new ones, as
+ it needs.
+ </para>
+
+ <para>
By default the log is written to stderr, but this can be changed by a call
to <function>yaz_log_init_file</function> or
<function>yaz_log_init</function>. If the log is directed to a file, the
rotation feature.
</para>
+ <screen>
+ A typical yaz-log looks like this
+ 13:23:14-23/11 yaz-ztest(1) [session] Starting session from tcp:127.0.0.1 (pid=30968)
+ 13:23:14-23/11 yaz-ztest(1) [request] Init from 'YAZ' (81) (ver 2.0.28) OK
+ 13:23:17-23/11 yaz-ztest(1) [request] Search Z: @attrset Bib-1 foo OK:7 hits
+ 13:23:22-23/11 yaz-ztest(1) [request] Present: [1] 2+2 OK 2 records returned
+ 13:24:13-23/11 yaz-ztest(1) [request] Close OK
+ </screen>
+
<para>
The log entries start with a time stamp. This can be omitted by setting the
<literal>YLOG_NOTIME</literal> bit in the loglevel. This way automatic tests
</para>
<para>
- Next in a log line comes the prefix, often the name of the program. Then
+ Next in a log line comes the prefix, often the name of the program. For
+ yaz-based servers, it can also contain the session number. Then
comes one or more logbits in square brackets, depending on the logging
level set by <function>yaz_log_init_level</function> and the loglevel
- passed to <function>yaz_log_init_level</function>. Finally comes all format
+ passed to <function>yaz_log_init_level</function>. Finally comes the format
string and additional values passed to <function>yaz_log</function>
</para>
</para>
<para>
- The dynamic log levels and log rotation were introduced in &yaz; 2.0.28.
+ The dynamic log levels and log rotation were introduced in &yaz; 2.0.28. At
+ the same time, the log bit names were changed from
+ <literal>LOG_something</literal> to <literal>YLOG_something</literal>,
+ to avoid collision with <filename>syslog.h</filename>.
</para>
</sect1>
--- /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 / commitdiff