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