File: yaz-log-man.xml

package info (click to toggle)
yaz 3.0.34-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,404 kB
  • ctags: 12,108
  • sloc: xml: 116,075; ansic: 52,205; sh: 9,746; tcl: 2,043; makefile: 1,141; yacc: 347
file content (293 lines) | stat: -rw-r--r-- 10,652 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
[ 
     <!ENTITY % local SYSTEM "local.ent">
     %local;
     <!ENTITY % entities SYSTEM "entities.ent">
     %entities;
     <!ENTITY % idcommon SYSTEM "common/common.ent">
     %idcommon;
]>
<refentry id="yaz-log">
 <refentryinfo>
  <productname>YAZ</productname>
  <productnumber>&version;</productnumber>
 </refentryinfo>
 
 <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,
      <replaceable>logfile</replaceable>.2, .., 9 
      (old such file is deleted), and a
      new file is opened. The limit defaults to 1GB, but can be set by the
      program.
      The rotating limit can be specified with option <literal>-r</literal>
      for the YAZ frontend server (yaz-ztest).
     </para>
     <para>
      Rotation can also be implicitly enabled by using a filename
      which gets changed for a given date, due to substitutions as
      given by the strftime(3) function.
     </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>LOGGING 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>LOG FILENAME EXAMPLES</title>
  <para>
   A file with format my_YYYYMMDD.log is where Y, M, D is year, month, and day
   digits is given as follows
   <literal>-l my_%Y%m%d.log</literal>. And since the filename
   is depending on day, rotaion will occur on midnight.
  </para>
  <para>
   A weekly log could be specified as 
   <literal>-l my_%Y%U.log</literal>.
  </para>
 </refsect1>
  
 <refsect1><title>FILES</title>
  <para>
   <filename><replaceable>prefix</replaceable>/include/yaz/log.h</filename>
   <filename><replaceable>prefix</replaceable>/src/log.c</filename>
  </para>
 </refsect1>
 <refsect1><title>SEE ALSO</title>
  <para>
   <citerefentry>
    <refentrytitle>yaz</refentrytitle>
    <manvolnum>7</manvolnum>
   </citerefentry>

   <citerefentry>
    <refentrytitle>yaz-ztest</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>

   <citerefentry>
    <refentrytitle>yaz-client</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>

   <citerefentry>
    <refentrytitle>strftime</refentrytitle>
    <manvolnum>3</manvolnum>
   </citerefentry>
  </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:
-->