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.11 2007-05-22 13:03:32 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>request-apdu</term>
  63          <listitem>
  64           <para>
  65            Z39.50 Request APDU.
  66           </para>
  67          </listitem>
  68         </varlistentry>
  69         <varlistentry><term>response-apdu</term>
  70          <listitem>
  71           <para>
  72            Z39.50 Response APDU.
  73           </para>
  74          </listitem>
  75         </varlistentry>
  76         <varlistentry><term>apdu</term>
  77          <listitem>
  78           <para>
  79            Z39.50 APDU (request and response)
  80           </para>
  81          </listitem>
  82         </varlistentry>
  83         <varlistentry><term>request-session</term>
  84          <listitem>
  85           <para>
  86            Request session.
  87           </para>
  88          </listitem>
  89         </varlistentry>
  90         <varlistentry><term>response-session</term>
  91          <listitem>
  92           <para>
  93            Response session.
  94           </para>
  95          </listitem>
  96         </varlistentry>
  97         <varlistentry><term>session</term>
  98          <listitem>
  99           <para>
 100            Session (request and response)
 101           </para>
 102          </listitem>
 103         </varlistentry>
 104         <varlistentry><term>init-options</term>
 105          <listitem>
 106           <para>
 107            Z39.50 Init Request options
 108           </para>
 109          </listitem>
 110         </varlistentry>
 111        </variablelist>
 112
 113       </para>
 114      </listitem>
 115     </varlistentry>
 116    </variablelist>
 117   </para>
 118  </refsect1>
 119
 120  <refsect1><title>The access log</title>
 121   <para>
 122    The access is is strictly one line per entry and aims for
 123    easy mangling with tools such as awk, grep, perl etc.
 124    Many values may be omitted in the packages in which case a single
 125    dash is printed instead. This is to ensure that all values have
 126    well-defined position.
 127   </para>
 128   <para>
 129    The basic format and order is
 130    <variablelist>
 131     <varlistentry><term>time (position 1)</term>
 132      <listitem><para>
 133        Full time of event
 134       </para>
 135      </listitem>
 136     </varlistentry>
 137
 138     <varlistentry><term>Custom message (position 2)</term>
 139      <listitem><para>
 140        The string as given in element <literal>message</literal>.
 141       </para>
 142      </listitem>
 143     </varlistentry>
 144
 145     <varlistentry><term>IP (position 3)</term>
 146      <listitem><para>
 147        IP address of origin (peer)
 148       </para>
 149      </listitem>
 150     </varlistentry>
 151
 152     <varlistentry><term>session (position 4)</term>
 153      <listitem><para>
 154        Session ID. Can be used to identify a particular Z39.50 session.
 155        For HTTP this session ID only tracks the HTTP socket (kept alive).
 156        NOT to be confused the the HTTP cookie mechanism.
 157       </para>
 158      </listitem>
 159     </varlistentry>
 160
 161     <varlistentry><term>elapsed (position 5)</term>
 162      <listitem><para>
 163        Elapsed time .
 164        The elapsed time is the time between the point in time
 165        where a package was received form the client and the
 166        point where a response was received from the next filter
 167        in chain (backend eventually).
 168       </para>
 169      </listitem>
 170     </varlistentry>
 171     <varlistentry><term>protocol (position 6)</term>
 172      <listitem><para>
 173        Protocol type which is one of <literal>Z3950</literal> or
 174        <literal>HTTP_Request</literal> or
 175        <literal>HTTP_Response</literal>.
 176       </para>
 177      </listitem>
 178     </varlistentry>
 179    </variablelist>
 180   </para>
 181
 182   <para>
 183    For packages of with protocol marker <literal>Z3950</literal>
 184    the the access log line is followed by the APDU type + information
 185    depending on the type. The APDU type is on position 7.
 186
 187    <variablelist>
 188
 189     <varlistentry><term>initRequest</term>
 190      <listitem><para>
 191        Z39.50 Initialize Request with the information
 192        username, vhost,
 193        implementation ID, implementation name, implementation version.
 194       </para>
 195      </listitem>
 196     </varlistentry>
 197
 198     <varlistentry><term>initResponse</term>
 199      <listitem><para>
 200        Z39.50 Initialize Response with the information:
 201        status (OK or FAIL), implementatino ID, implementation name,
 202        implementation version.
 203       </para>
 204      </listitem>
 205     </varlistentry>
 206
 207     <varlistentry><term>searchRequest</term>
 208      <listitem><para>
 209        Z39.50 Search Request with the information:
 210        database(s), result set ID, record syntax, query.
 211       </para>
 212       <para>
 213        Multiple databases are separated by
 214        a plus-sign (<literal>+</literal>). The query itself is
 215        multiple tokens. For this reason it is placed as the last
 216        information on this log entry.
 217       </para>
 218      </listitem>
 219     </varlistentry>
 220
 221     <varlistentry><term>searchResponse</term>
 222      <listitem><para>
 223        Z39.50 Search Response with the information:
 224        status (OK or FAIL), hit count, number of records returned,
 225        next result set position.
 226       </para>
 227      </listitem>
 228     </varlistentry>
 229
 230     <varlistentry><term>presentRequest</term>
 231      <listitem><para>
 232        Z39.50 Present Request with the information:
 233        result Set ID, start position, number of records requested,
 234        record syntax, record composition.
 235       </para>
 236      </listitem>
 237     </varlistentry>
 238
 239     <varlistentry><term>presentResponse</term>
 240      <listitem><para>
 241        Z39.50 Present Response with the information:
 242        status (OK, DIAG, ERROR), number of records returned,
 243        next result set position.
 244       </para>
 245      </listitem>
 246     </varlistentry>
 247
 248     <varlistentry><term>scanRequest</term>
 249      <listitem><para>
 250        Z39.50 Scan Request with the information:
 251        database(s), number of terms requested, preferred position in
 252        response, step size, start point.
 253       </para>
 254       <para>
 255        start point is a multi token value in PQF notation.
 256       </para>
 257      </listitem>
 258     </varlistentry>
 259
 260     <varlistentry><term>scanResponse</term>
 261      <listitem><para>
 262        Z39.50 Scan Response with the information:
 263        status (OK, ERROR), number of entries returned, position of term,
 264        step size.
 265       </para>
 266      </listitem>
 267     </varlistentry>
 268
 269    </variablelist>
 270   </para>
 271
 272  </refsect1>
 273
 274  <refsect1><title>EXAMPLES</title>
 275   <para>
 276    A typical configuration looks like this:
 277    <screen><![CDATA[
 278     <filter type="log">
 279      <message>B</message>
 280      <category access="true"/>
 281      <filename>logs/metaproxy.log</filename>
 282     </filter>
 283 ]]>
 284    </screen>
 285   </para>
 286  </refsect1>
 287
 288  <refsect1><title>SEE ALSO</title>
 289   <para>
 290    <citerefentry>
 291     <refentrytitle>metaproxy</refentrytitle>
 292     <manvolnum>1</manvolnum>
 293    </citerefentry>
 294   </para>
 295  </refsect1>
 296
 297  &copyright;
 298 </refentry>
 299
 300 <!-- Keep this comment at the end of the file
 301 Local variables:
 302 mode: sgml
 303 sgml-omittag:t
 304 sgml-shorttag:t
 305 sgml-minimize-attributes:nil
 306 sgml-always-quote-attributes:t
 307 sgml-indent-step:1
 308 sgml-indent-data:t
 309 sgml-parent-document:nil
 310 sgml-local-catalogs: nil
 311 sgml-namecase-general:t
 312 End:
 313 -->