doc/log.xml

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