From b6ed17b957403d2db0475df7759de72ce3eda2ee Mon Sep 17 00:00:00 2001 From: Heikki Levanto Date: Tue, 23 Nov 2004 14:11:03 +0000 Subject: [PATCH] Added a man page for yaz-log (7) --- doc/Makefile.am | 9 +- doc/tools.xml | 41 +++++++-- doc/yaz-log-man.xml | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 278 insertions(+), 11 deletions(-) create mode 100644 doc/yaz-log-man.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 538474f..4518ada 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.56 2004-11-16 17:08:11 heikki Exp $ +## $Id: Makefile.am,v 1.57 2004-11-23 14:11:03 heikki Exp $ docdir=$(datadir)/doc/@PACKAGE@ @@ -26,10 +26,10 @@ HTMLFILES = \ MANFILES=yaz-client.1 yaz-ztest.8 \ yaz-config.8 yaz.7 zoomsh.1 yaz-asncomp.1 \ - yaz-marcdump.1 yaz-iconv.1 + yaz-marcdump.1 yaz-iconv.1 yaz-log.7 REFFILES=yaz-client-man.xml yaz-ztest-man.xml yaz-config-man.xml \ yaz-man.xml zoomsh-man.xml yaz-asncomp-man.xml \ - yaz-marcdump-man.xml yaz-iconv-man.xml + yaz-marcdump-man.xml yaz-iconv-man.xml yaz-log-man.xml SUPPORTFILES=yazhtml.dsl yazphp.dsl yazprint.dsl tkl.xsl xml.dcl id.eps \ apilayer.obj yaz.css @@ -64,6 +64,9 @@ yaz-marcdump.1: yaz-marcdump-man.xml yaz-iconv.1: yaz-iconv-man.xml docbook2man $(srcdir)/yaz-iconv-man.xml +yaz-log.7: yaz-log-man.xml + docbook2man $(srcdir)/yaz-log-man.xml + $(HTMLFILES): $(XMLFILES) jade -E14 -D $(srcdir) -d yazhtml.dsl -t sgml $(srcdir)/xml.dcl yaz.xml diff --git a/doc/tools.xml b/doc/tools.xml index add24b4..ea838c7 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -1835,10 +1835,11 @@ typedef struct oident The log level 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 YLOG_FATAL, - YLOG_DEBUG, YLOG_WARN, YLOG_LOG. Those can be combined with bits - that modify the way the log entry is written:YLOG_ERRNO, - YLOG_NOTIME, YLOG_FLUSH. - Most of the rest of the bits are deprecated, and should not be used. + YLOG_DEBUG, YLOG_WARN, YLOG_LOG. Those can be combined with bits + that modify the way the log entry is written:YLOG_ERRNO, + YLOG_NOTIME, YLOG_FLUSH. + Most of the rest of the bits are deprecated, and should not be used. Use + the dynamic log levels instead. @@ -1874,6 +1875,17 @@ typedef struct oident + Yaz uses the following dynamic log levels: + server, session, request, requestdetail for the server + functionality. + zoom for the zoom client api. + ztest for the simple test server. + malloc, nmem, odr, eventl for internal debugging of yaz itself. + Of course, any program using yaz is welcome to define as many new ones, as + it needs. + + + By default the log is written to stderr, but this can be changed by a call to yaz_log_init_file or yaz_log_init. If the log is directed to a file, the @@ -1884,6 +1896,15 @@ typedef struct oident rotation feature. + + 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 + + The log entries start with a time stamp. This can be omitted by setting the YLOG_NOTIME bit in the loglevel. This way automatic tests @@ -1894,10 +1915,11 @@ typedef struct oident - 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 yaz_log_init_level and the loglevel - passed to yaz_log_init_level. Finally comes all format + passed to yaz_log_init_level. Finally comes the format string and additional values passed to yaz_log @@ -1915,7 +1937,10 @@ typedef struct oident - 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 + LOG_something to YLOG_something, + to avoid collision with syslog.h. diff --git a/doc/yaz-log-man.xml b/doc/yaz-log-man.xml new file mode 100644 index 0000000..c2126bb --- /dev/null +++ b/doc/yaz-log-man.xml @@ -0,0 +1,239 @@ + + + + + yaz-log + 7 + + + + yaz-log + Log handling in all yaz-based programs + + + + + yaz-XXXX + + + + + + DESCRIPTION + + All YAZ-based programs use a common log subsystem, and should support + common command line options for controlling it. This man page documents + those. + + + + + + OPTIONS + + + + -l logfile + + Specify the file where the log is to be written. If none is specified, + stderr is used. The log is appended to this file. + If the file grows overly large, it is silently rotated: It is renamed to + logfile.1 (old such file is deleted), and a + new file is opened. The limit defaults to 1GB, but can be set by the + program. + + + + + -v loglevel + + 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 fatal,warn,log, and some + application-specific values. The default list can be cleared with the + word none, or individual bits can be removed by + prefixing them with a dash '-'. + + + + + + + LOG LEVELS TO CONTROL LOGGING + + Some of the log levels control the way the log is written. + + + flush 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 debug implies + flush as well. + + + notime prevents the writing of time stamps. This is + intended for automatic test scripts, which should produce predictable log + files that are easy to compare. + + + + + GENERAL LOG LEVELS IN YAZ ITSELF + + YAZ itself uses the following log levels: + + + fatal for fatal errors, that prevent further execution + of the program. + + + warn for warnings about things that should be corrected. + + + debug 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). + + + all turns on almost all hard-coded log levels. + + + loglevel 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 -v + none,loglevel, and do some common operations with it. Another way + is to grep for yaz_log_module_level in the source + code, as in + + find . -name '*.[ch]' -print | + xargs grep yaz_log_module_level | + grep '"' | + cut -d'"' -f2 | + sort -u + + + + eventl, malloc, + nmem, odr are used internally for + debugging yaz. + + + + + + LOG LEVELS FOR CLIENTS + + zoom logs the calls to the zoom API, which may be useful + in debugging client applications. + + + + LOG LEVELS FOR SERVERS + + server logs the server functions on a high level, + starting up, listening on a port, etc. + + + session logs individual sessions (connections). + + + request logs a one-liner for each request (init, search, + etc). + + + requestdetail logs the details of every request, before + it is passed to the back-end, and the results received from it. + + + 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. + + + + EXAMPLES + + See what log levels yaz-ztest is using: + + 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' + + + + See the details of the requests for yaz-ztest + + ./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 + + + + + FILES + + prefix/include/yaz/ylog.h + prefix/src/log.c + + + SEE ALSO + + yaz(7) + yaz-ztest(8) yaz-client(1) + + + + + -- 1.7.10.4