doc/log.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
   3  <!ENTITY copyright SYSTEM "copyright.xml">
   4  <!ENTITY % idcommon SYSTEM "common/common.ent">
   5      %idcommon;
   6 ]>
   7 <!-- $Id: log.xml,v 1.12 2007-05-22 19:45:57 adam Exp $ -->
   8 <refentry id="ref-log">
   9  <refmeta>
  10   <refentrytitle>log</refentrytitle>
  11   <manvolnum>3mp</manvolnum>
  12    <refmiscinfo>Metaproxy Module</refmiscinfo>
  13 </refmeta>
  14
  15  <refnamediv>
  16   <refname>log</refname>
  17   <refpurpose>Metaproxy Package Logging Module</refpurpose>
  18  </refnamediv>
  19
  20  <refsect1><title>DESCRIPTION</title>
  21   <para>
  22    This filter logs packages sent - and received .
  23   </para>
  24
  25   <para>
  26    Configurable values:
  27    <variablelist>
  28     <varlistentry><term>message</term>
  29      <listitem>
  30       <para>
  31        Specifies a custom message for the log message.
  32       </para>
  33      </listitem>
  34     </varlistentry>
  35     <varlistentry><term>filename</term>
  36      <listitem>
  37       <para>
  38        Specifies a name of log file.
  39       </para>
  40      </listitem>
  41     </varlistentry>
  42     <varlistentry><term>category</term>
  43      <listitem>
  44       <para>
  45        Specifies the category of messages to be logged. The category is an
  46        XML attribute and value of attribute is a boolean;
  47        <literal>true</literal> for enabled; <literal>false</literal>
  48        for disabled.
  49        The following category attributes are supported:
  50
  51        <variablelist>
  52         <varlistentry><term>access</term>
  53          <listitem>
  54           <para>
  55            One line log messages inspired by Apache access log entries.
  56            This is a brief message stating the request and response.
  57            This is enabled by default. All other categories are disabled by
  58            default. See the section ACCESS LOG.
  59           </para>
  60          </listitem>
  61         </varlistentry>
  62         <varlistentry><term>user-access</term>
  63          <listitem>
  64           <para>
  65            One line log messages similar to <literal>access</literal> but
  66            with the authenticated user on each log line.
  67           </para>
  68          </listitem>
  69         </varlistentry>
  70         <varlistentry><term>request-apdu</term>
  71          <listitem>
  72           <para>
  73            Z39.50 Request APDU.
  74           </para>
  75          </listitem>
  76         </varlistentry>
  77         <varlistentry><term>response-apdu</term>
  78          <listitem>
  79           <para>
  80            Z39.50 Response APDU.
  81           </para>
  82          </listitem>
  83         </varlistentry>
  84         <varlistentry><term>apdu</term>
  85          <listitem>
  86           <para>
  87            Z39.50 APDU (request and response)
  88           </para>
  89          </listitem>
  90         </varlistentry>
  91         <varlistentry><term>request-session</term>
  92          <listitem>
  93           <para>
  94            Request session.
  95           </para>
  96          </listitem>
  97         </varlistentry>
  98         <varlistentry><term>response-session</term>
  99          <listitem>
 100           <para>
 101            Response session.
 102           </para>
 103          </listitem>
 104         </varlistentry>
 105         <varlistentry><term>session</term>
 106          <listitem>
 107           <para>
 108            Session (request and response)
 109           </para>
 110          </listitem>
 111         </varlistentry>
 112         <varlistentry><term>init-options</term>
 113          <listitem>
 114           <para>
 115            Z39.50 Init Request options
 116           </para>
 117          </listitem>
 118         </varlistentry>
 119        </variablelist>
 120
 121       </para>
 122      </listitem>
 123     </varlistentry>
 124    </variablelist>
 125   </para>
 126  </refsect1>
 127
 128  <refsect1><title>The access log</title>
 129   <para>
 130    The access is is strictly one line per entry and aims for
 131    easy mangling with tools such as awk, grep, perl etc.
 132    Many values may be omitted in the packages in which case a single
 133    dash is printed instead. This is to ensure that all values have
 134    well-defined position.
 135   </para>
 136   <para>
 137    The basic format and order is
 138    <variablelist>
 139     <varlistentry><term>time (position 1)</term>
 140      <listitem><para>
 141        Full time of event
 142       </para>
 143      </listitem>
 144     </varlistentry>
 145
 146     <varlistentry><term>Custom message (position 2)</term>
 147      <listitem><para>
 148        The string as given in element <literal>message</literal>.
 149       </para>
 150      </listitem>
 151     </varlistentry>
 152
 153     <varlistentry><term>IP (position 3)</term>
 154      <listitem><para>
 155        IP address of origin (peer)
 156       </para>
 157       <para>
 158        If category <literal>user-acesss</literal> is used the
 159        user is written on position 3 and the IP is written on position 4.
 160       </para>
 161      </listitem>
 162     </varlistentry>
 163
 164     <varlistentry><term>session (position 4)</term>
 165      <listitem><para>
 166        Session ID. Can be used to identify a particular Z39.50 session.
 167        For HTTP this session ID only tracks the HTTP socket (kept alive).
 168        NOT to be confused the the HTTP cookie mechanism.
 169       </para>
 170      </listitem>
 171     </varlistentry>
 172
 173     <varlistentry><term>elapsed (position 5)</term>
 174      <listitem><para>
 175        Elapsed time .
 176        The elapsed time is the time between the point in time
 177        where a package was received form the client and the
 178        point where a response was received from the next filter
 179        in chain (backend eventually).
 180       </para>
 181      </listitem>
 182     </varlistentry>
 183     <varlistentry><term>protocol (position 6)</term>
 184      <listitem><para>
 185        Protocol type which is one of <literal>Z3950</literal> or
 186        <literal>HTTP_Request</literal> or
 187        <literal>HTTP_Response</literal>.
 188       </para>
 189      </listitem>
 190     </varlistentry>
 191    </variablelist>
 192   </para>
 193
 194   <para>
 195    For packages of with protocol marker <literal>Z3950</literal>
 196    the the access log line is followed by the APDU type + information
 197    depending on the type. The APDU type is on position 7.
 198
 199    <variablelist>
 200
 201     <varlistentry><term>initRequest</term>
 202      <listitem><para>
 203        Z39.50 Initialize Request with the information
 204        username, vhost,
 205        implementation ID, implementation name, implementation version.
 206       </para>
 207      </listitem>
 208     </varlistentry>
 209
 210     <varlistentry><term>initResponse</term>
 211      <listitem><para>
 212        Z39.50 Initialize Response with the information:
 213        status (OK or FAIL), implementatino ID, implementation name,
 214        implementation version.
 215       </para>
 216      </listitem>
 217     </varlistentry>
 218
 219     <varlistentry><term>searchRequest</term>
 220      <listitem><para>
 221        Z39.50 Search Request with the information:
 222        database(s), result set ID, record syntax, query.
 223       </para>
 224       <para>
 225        Multiple databases are separated by
 226        a plus-sign (<literal>+</literal>). The query itself is
 227        multiple tokens. For this reason it is placed as the last
 228        information on this log entry.
 229       </para>
 230      </listitem>
 231     </varlistentry>
 232
 233     <varlistentry><term>searchResponse</term>
 234      <listitem><para>
 235        Z39.50 Search Response with the information:
 236        status (OK or FAIL), hit count, number of records returned,
 237        next result set position.
 238       </para>
 239      </listitem>
 240     </varlistentry>
 241
 242     <varlistentry><term>presentRequest</term>
 243      <listitem><para>
 244        Z39.50 Present Request with the information:
 245        result Set ID, start position, number of records requested,
 246        record syntax, record composition.
 247       </para>
 248      </listitem>
 249     </varlistentry>
 250
 251     <varlistentry><term>presentResponse</term>
 252      <listitem><para>
 253        Z39.50 Present Response with the information:
 254        status (OK, DIAG, ERROR), number of records returned,
 255        next result set position.
 256       </para>
 257      </listitem>
 258     </varlistentry>
 259
 260     <varlistentry><term>scanRequest</term>
 261      <listitem><para>
 262        Z39.50 Scan Request with the information:
 263        database(s), number of terms requested, preferred position in
 264        response, step size, start point.
 265       </para>
 266       <para>
 267        start point is a multi token value in PQF notation.
 268       </para>
 269      </listitem>
 270     </varlistentry>
 271
 272     <varlistentry><term>scanResponse</term>
 273      <listitem><para>
 274        Z39.50 Scan Response with the information:
 275        status (OK, ERROR), number of entries returned, position of term,
 276        step size.
 277       </para>
 278      </listitem>
 279     </varlistentry>
 280
 281    </variablelist>
 282   </para>
 283
 284  </refsect1>
 285
 286  <refsect1><title>EXAMPLES</title>
 287   <para>
 288    A typical configuration looks like this:
 289    <screen><![CDATA[
 290     <filter type="log">
 291      <message>B</message>
 292      <category access="true"/>
 293      <filename>logs/metaproxy.log</filename>
 294     </filter>
 295 ]]>
 296    </screen>
 297   </para>
 298  </refsect1>
 299
 300  <refsect1><title>SEE ALSO</title>
 301   <para>
 302    <citerefentry>
 303     <refentrytitle>metaproxy</refentrytitle>
 304     <manvolnum>1</manvolnum>
 305    </citerefentry>
 306   </para>
 307  </refsect1>
 308
 309  &copyright;
 310 </refentry>
 311
 312 <!-- Keep this comment at the end of the file
 313 Local variables:
 314 mode: sgml
 315 sgml-omittag:t
 316 sgml-shorttag:t
 317 sgml-minimize-attributes:nil
 318 sgml-always-quote-attributes:t
 319 sgml-indent-step:1
 320 sgml-indent-data:t
 321 sgml-parent-document:nil
 322 sgml-local-catalogs: nil
 323 sgml-namecase-general:t
 324 End:
 325 -->