-<!-- $Id: tools.xml,v 1.40 2004-11-17 13:03:07 heikki Exp $ -->
+<!-- $Id: tools.xml,v 1.44 2005-02-08 13:51:30 adam Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
<sect1 id="tools.log"><title>Log</title>
<para>
- Yaz has evolved a fairly complex log system which should be useful both
- for debugging &yaz; itself, debugging applications that use yaz, and for
+ &yaz; has evolved a fairly complex log system which should be useful both
+ for debugging &yaz; itself, debugging applications that use &yaz;, and for
production use of those applications.
</para>
<para>
- The log functions are declared in <filename>log.h</filename> and
- implemented in <filename>log.c</filename>. The key points of the interface
- are:
+ The log functions are declared in header <filename>yaz/log.h</filename>
+ and implemented in <filename>src/log.c</filename>.
+ Due to name clash with syslog and some math utilities the logging
+ interface has been modified as of YAZ 2.0.29. The obsolete interface
+ is still available if in header file <filename>yaz/log.h</filename>.
+ The key points of the interface are:
</para>
<screen>
void yaz_log(int level, const char *fmt, ...)
<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>LOG_FATAL,
- LOG_DEBUG, LOG_WARN, LOG_LOG</literal>. Those can be combined with bits
- that modify the way the log entry is written:<literal>LOG_ERRNO, LOG_NOTIME,
- LOG_FLUSH</literal>. Most of the rest of the bits are deprecated, and
- should not be used.
+ 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. Use
+ the dynamic log levels instead.
</para>
<para>
- Applications that use yaz, should not use the LOG_LOG for ordinary
+ Applications that use &yaz;, should not use the LOG_LOG for ordinary
messages, but should make use of the dynamic loglevel system. This consists
of two parts, defining the loglevel and checking it.
</para>
<function>yaz_log_mask_str</function> to define which log levels are to be
logged. This string should be a comma-separated list of log level names,
and can contain both hard-coded names and dynamic ones. The log level
- calculation starts with <literal>LOG_DEFAULT_LEVEL</literal> and adds a bit
+ calculation starts with <literal>YLOG_DEFAULT_LEVEL</literal> and adds a bit
for each word it meets, unless the word starts with a '-', in which case it
clears the bit. If the string <literal>'none'</literal> is found,
all bits are cleared. Typically this string comes from the command-line,
</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>LOG_NOTIME</literal> bit in the loglevel. This way automatic tests
+ <literal>YLOG_NOTIME</literal> bit in the loglevel. This way automatic tests
can be hoped to produce identical log files, that are easy to diff. The
format of the time stamp can be set with
<function>yaz_log_time_format</function>, which takes a format string just
</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>
- The log level <literal>LOG_LOGLVL</literal>, enabled by the string
+ The log level <literal>YLOG_LOGLVL</literal>, enabled by the string
<literal>loglevel</literal>, will log all the log-level affecting
operations. This can come in handy if you need to know what other log
levels would be useful. Grep the logfile for <literal>[loglevel]</literal>.
</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>
#define YAZ_MARC_OAIMARC 2
#define YAZ_MARC_MARCXML 3
#define YAZ_MARC_ISO2709 4
+ #define YAZ_MARC_XCHANGE 5
/* supply iconv handle for character set conversion .. */
void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
projects / yaz-moved-to-github.git / blobdiff