dependencies/yaz-2.1.28/doc/yaz-log.7

   1 .\"     Title: yaz\-log
   2 .\"    Author:
   3 .\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
   4 .\"      Date: 09/04/2006
   5 .\"    Manual:
   6 .\"    Source: YAZ 2.1.28
   7 .\"
   8 .TH "YAZ\-LOG" "7" "09/04/2006" "YAZ 2.1.28" ""
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 yaz\-log \- Log handling in all yaz\-based programs
  15 .SH "SYNOPSIS"
  16 .HP 9
  17 \fByaz\-XXXX\fR [\fB\-v\ \fR\fB\fIloglevel,...\fR\fR] [\fB\-l\ \fR\fB\fIlogfile\fR\fR]
  18 .SH "DESCRIPTION"
  19 .PP
  20 All YAZ\-based programs use a common log subsystem, and should support common command line options for controlling it. This man page documents those.
  21 .PP
  22 .SH "OPTIONS"
  23 .TP 3n
  24 \-l\fI logfile\fR
  25 Specify the file where the log is to be written. If none is specified,
  26 \fIstderr\fR
  27 is used. The log is appended to this file. If the file grows overly large, it is silently rotated: It is renamed to
  28 \fIlogfile\fR.1 (old such file is deleted), and a new file is opened. The limit defaults to 1GB, but can be set by the program.
  29 .TP 3n
  30 \-v\fI loglevel\fR
  31 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
  32 fatal,warn,log, and some application\-specific values. The default list can be cleared with the word
  33 none, or individual bits can be removed by prefixing them with a dash '\-'.
  34 .SH "LOG LEVELS TO CONTROL LOGGING"
  35 .PP
  36 Some of the log levels control the way the log is written.
  37 .PP
  38
  39 flush
  40 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
  41 debug
  42 implies
  43 flush
  44 as well.
  45 .PP
  46
  47 notime
  48 prevents the writing of time stamps. This is intended for automatic test scripts, which should produce predictable log files that are easy to compare.
  49 .SH "GENERAL LOG LEVELS IN YAZ ITSELF"
  50 .PP
  51 YAZ itself uses the following log levels:
  52 .PP
  53
  54 fatal
  55 for fatal errors, that prevent further execution of the program.
  56 .PP
  57
  58 warn
  59 for warnings about things that should be corrected.
  60 .PP
  61
  62 debug
  63 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).
  64 .PP
  65
  66 all
  67 turns on almost all hard\-coded log levels.
  68 .PP
  69
  70 loglevel
  71 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
  72 \-v none,loglevel, and do some common operations with it. Another way is to grep for
  73 \fByaz_log_module_level\fR
  74 in the source code, as in
  75 .sp
  76 .RS 3n
  77 .nf
  78       find . \-name '*.[ch]' \-print |
  79          xargs grep yaz_log_module_level |
  80          grep '"' |
  81          cut \-d'"' \-f2 |
  82          sort \-u
  83
  84 .fi
  85 .RE
  86 .sp
  87 .PP
  88
  89 eventl,
  90 malloc,
  91 nmem,
  92 odr
  93 are used internally for debugging yaz.
  94 .PP
  95 .SH "LOG LEVELS FOR CLIENTS"
  96 .PP
  97
  98 zoom
  99 logs the calls to the zoom API, which may be useful in debugging client applications.
 100 .SH "LOG LEVELS FOR SERVERS"
 101 .PP
 102
 103 server
 104 logs the server functions on a high level, starting up, listening on a port, etc.
 105 .PP
 106
 107 session
 108 logs individual sessions (connections).
 109 .PP
 110
 111 request
 112 logs a one\-liner for each request (init, search, etc).
 113 .PP
 114
 115 requestdetail
 116 logs the details of every request, before it is passed to the back\-end, and the results received from it.
 117 .PP
 118 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.
 119 .SH "EXAMPLES"
 120 .PP
 121 See what log levels yaz\-ztest is using:
 122 .sp
 123 .RS 3n
 124 .nf
 125     yaz\-ztest \-1 \-v none,loglevel
 126     14:43:29\-23/11 [loglevel] Setting log level to 4096 = 0x00001000
 127     14:43:29\-23/11 [loglevel] Static  log bit 00000001 'fatal' is off
 128     14:43:29\-23/11 [loglevel] Static  log bit 00000002 'debug' is off
 129     14:43:29\-23/11 [loglevel] Static  log bit 00000004 'warn' is off
 130     14:43:29\-23/11 [loglevel] Static  log bit 00000008 'log' is off
 131     14:43:29\-23/11 [loglevel] Static  log bit 00000080 'malloc' is off
 132     14:43:29\-23/11 [loglevel] Static  log bit 00000800 'flush' is off
 133     14:43:29\-23/11 [loglevel] Static  log bit 00001000 'loglevel' is ON
 134     14:43:29\-23/11 [loglevel] Static  log bit 00002000 'server' is off
 135     14:43:29\-23/11 [loglevel] Dynamic log bit 00004000 'session' is off
 136     14:43:29\-23/11 [loglevel] Dynamic log bit 00008000 'request' is off
 137     14:44:13\-23/11 yaz\-ztest [loglevel] returning log bit 0x4000 for 'session'
 138     14:44:13\-23/11 yaz\-ztest [loglevel] returning log bit 0x2000 for 'server'
 139     14:44:13\-23/11 yaz\-ztest [loglevel] returning NO log bit for 'eventl'
 140     14:44:20\-23/11 yaz\-ztest [loglevel] returning log bit 0x4000 for 'session'
 141     14:44:20\-23/11 yaz\-ztest [loglevel] returning log bit 0x8000 for 'request'
 142     14:44:20\-23/11 yaz\-ztest [loglevel] returning NO log bit for 'requestdetail'
 143     14:44:20\-23/11 yaz\-ztest [loglevel] returning NO log bit for 'odr'
 144     14:44:20\-23/11 yaz\-ztest [loglevel] returning NO log bit for 'ztest'
 145
 146 .fi
 147 .RE
 148 .sp
 149 .PP
 150 See the details of the requests for yaz\-ztest
 151 .sp
 152 .RS 3n
 153 .nf
 154    ./yaz\-ztest \-1 \-v requestdetail
 155    14:45:35\-23/11 yaz\-ztest [server] Adding static Z3950 listener on tcp:@:9999
 156    14:45:35\-23/11 yaz\-ztest [server] Starting server ./yaz\-ztest pid=32200
 157    14:45:38\-23/11 yaz\-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200)
 158    14:45:38\-23/11 yaz\-ztest [requestdetail] Got initRequest
 159    14:45:38\-23/11 yaz\-ztest [requestdetail] Id:        81
 160    14:45:38\-23/11 yaz\-ztest [requestdetail] Name:      YAZ
 161    14:45:38\-23/11 yaz\-ztest [requestdetail] Version:   2.0.28
 162    14:45:38\-23/11 yaz\-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort
 163    14:45:38\-23/11 yaz\-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK
 164    14:45:39\-23/11 yaz\-ztest [requestdetail] Got SearchRequest.
 165    14:45:39\-23/11 yaz\-ztest [requestdetail] ResultSet '1'
 166    14:45:39\-23/11 yaz\-ztest [requestdetail] Database 'Default'
 167    14:45:39\-23/11 yaz\-ztest [requestdetail] RPN query. Type: Bib\-1
 168    14:45:39\-23/11 yaz\-ztest [requestdetail]  term 'foo' (general)
 169    14:45:39\-23/11 yaz\-ztest [requestdetail] resultCount: 7
 170    14:45:39\-23/11 yaz\-ztest [request] Search Z: @attrset Bib\-1 foo  OK:7 hits
 171    14:45:41\-23/11 yaz\-ztest [requestdetail] Got PresentRequest.
 172    14:45:41\-23/11 yaz\-ztest [requestdetail] Request to pack 1+1 1
 173    14:45:41\-23/11 yaz\-ztest [requestdetail] pms=1048576, mrs=1048576
 174    14:45:41\-23/11 yaz\-ztest [request] Present: [1] 1+1  OK 1 records returned
 175
 176 .fi
 177 .RE
 178 .sp
 179 .SH "FILES"
 180 .PP
 181
 182 \fI\fIprefix\fR\fR\fI/include/yaz/log.h\fR
 183 \fI\fIprefix\fR\fR\fI/src/log.c\fR
 184 .SH "SEE ALSO"
 185 .PP
 186 yaz(7) yaz\-ztest(8) yaz\-client(1)