This file is indexed.

/usr/share/doc/yaz-doc/tools.log.html is in yaz-doc 4.2.30-2.1build1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. Log</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="tools.html" title="Chapter 7. Supporting Tools"><link rel="prev" href="tools.nmem.html" title="3. Nibble Memory"><link rel="next" href="marc.html" title="5. MARC"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4. Log</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="tools.nmem.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Supporting Tools</th><td width="20%" align="right"> <a accesskey="n" href="marc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tools.log"></a>4. Log</h2></div></div></div><p>
   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.  
  </p><p>
   The log functions are declared in header <code class="filename">yaz/log.h</code>
    and implemented in <code class="filename">src/log.c</code>.
    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 <code class="filename">yaz/log.h</code>.
    The key points of the interface are:
  </p><pre class="screen">
   void yaz_log(int level, const char *fmt, ...)

   void yaz_log_init(int level, const char *prefix, const char *name);
   void yaz_log_init_file(const char *fname);
   void yaz_log_init_level(int level);
   void yaz_log_init_prefix(const char *prefix);
   void yaz_log_time_format(const char *fmt);
   void yaz_log_init_max_size(int mx);

   int yaz_log_mask_str(const char *str);
   int yaz_log_module_level(const char *name);
  </pre><p>
   The reason for the whole log module is the <code class="function">yaz_log</code>
   function. It takes a bitmask indicating the log levels, a
   <code class="literal">printf</code>-like format string, and a variable number of
   arguments to log.
  </p><p>
   The <code class="literal">log level</code> 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 <code class="literal">YLOG_FATAL,
   YLOG_DEBUG, YLOG_WARN, YLOG_LOG</code>. Those can be combined with bits
   that modify the way the log entry is written:<code class="literal">YLOG_ERRNO,
   YLOG_NOTIME, YLOG_FLUSH</code>.
   Most of the rest of the bits are deprecated, and should not be used. Use
   the dynamic log levels instead.
  </p><p>
   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.
  </p><p>
   To define the log levels, the (main) program should pass a string to
   <code class="function">yaz_log_mask_str</code> 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 <code class="literal">YLOG_DEFAULT_LEVEL</code> 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 <code class="literal">'none'</code> is found,
   all bits are cleared. Typically this string comes from the command-line,
   often identified by <code class="literal">-v</code>. The
   <code class="function">yaz_log_mask_str</code> returns a log level that should be
   passed to <code class="function">yaz_log_init_level</code> for it to take effect.
  </p><p>
   Each module should check what log bits it should be used, by calling 
   <code class="function">yaz_log_module_level</code> with a suitable name for the
   module. The name is cleared from a preceding path and an extension, if any,
   so it is quite possible to use <code class="literal">__FILE__</code> for it. If the
   name has been passed to <code class="function">yaz_log_mask_str</code>, the routine
   returns a non-zero bitmask, which should then be used in consequent calls
   to yaz_log. (It can also be tested, so as to avoid unnecessary calls to
   yaz_log, in time-critical places, or when the log entry would take time 
   to construct.) 
  </p><p>
   Yaz uses the following dynamic log levels:
   <code class="literal">server, session, request, requestdetail</code> for the server
   functionality.
   <code class="literal">zoom</code> for the zoom client api.
   <code class="literal">ztest</code> for the simple test server.
   <code class="literal">malloc, nmem, odr, eventl</code> for internal debugging of yaz itself.
   Of course, any program using yaz is welcome to define as many new ones, as
   it needs.
  </p><p>
   By default the log is written to stderr, but this can be changed by a call
   to <code class="function">yaz_log_init_file</code> or
   <code class="function">yaz_log_init</code>. If the log is directed to a file, the
   file size is checked at every write, and if it exceeds the limit given in
   <code class="function">yaz_log_init_max_size</code>, the log is rotated. The
   rotation keeps one old version (with a <code class="literal">.1</code> appended to
   the name). The size defaults to 1GB. Setting it to zero will disable the
   rotation feature.
  </p><pre class="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
  </pre><p>
   The log entries start with a time stamp. This can be omitted by setting the
   <code class="literal">YLOG_NOTIME</code> 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
   <code class="function">yaz_log_time_format</code>, which takes a format string just
   like <code class="function">strftime</code>.
  </p><p>
   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 <code class="function">yaz_log_init_level</code> and the loglevel
   passed to <code class="function">yaz_log_init_level</code>. Finally comes the format
   string and additional values passed to <code class="function">yaz_log</code>
  </p><p>
   The log level <code class="literal">YLOG_LOGLVL</code>, enabled by the string
   <code class="literal">loglevel</code>, 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 <code class="literal">[loglevel]</code>.
  </p><p>
   The log system is almost independent of the rest of YAZ, the only
   important dependence is of <code class="filename">nmem</code>, and that only for
   using the semaphore definition there. 
  </p><p>
   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
   <code class="literal">LOG_something</code> to <code class="literal">YLOG_something</code>, 
   to avoid collision with <code class="filename">syslog.h</code>.
  </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tools.nmem.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tools.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="marc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Nibble Memory </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. MARC</td></tr></table></div></body></html>