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         <varlistentry><term>line</term>
 124          <listitem>
 125           <para>
 126            Simple one-line log message indicating the most important
 127            things from a request and response.
 128            Available from version 1.3.38 and later.
 129           </para>
 130          </listitem>
 131         </varlistentry>
 132        </variablelist>
 133
 134       </para>
 135      </listitem>
 136     </varlistentry>
 137    </variablelist>
 138   </para>
 139  </refsect1>
 140
 141  <refsect1><title>The access log</title>
 142   <para>
 143    The access is is strictly one line per entry and aims for
 144    easy mangling with tools such as awk, grep, perl etc.
 145    Many values may be omitted in the packages in which case a single
 146    dash is printed instead. This is to ensure that all values have
 147    well-defined position.
 148   </para>
 149   <para>
 150    The basic format and order is
 151    <variablelist>
 152     <varlistentry><term>time (position 1)</term>
 153      <listitem><para>
 154        Full time of event
 155       </para>
 156      </listitem>
 157     </varlistentry>
 158
 159     <varlistentry><term>Custom message (position 2)</term>
 160      <listitem><para>
 161        The string as given in element <literal>message</literal>.
 162       </para>
 163      </listitem>
 164     </varlistentry>
 165
 166     <varlistentry><term>IP (position 3)</term>
 167      <listitem><para>
 168        IP address of origin (peer)
 169       </para>
 170       <para>
 171        If category <literal>user-acesss</literal> is used the
 172        user is written on position 3 and the IP is written on position 4.
 173       </para>
 174      </listitem>
 175     </varlistentry>
 176
 177     <varlistentry><term>session (position 4)</term>
 178      <listitem><para>
 179        Session ID. Can be used to identify a particular Z39.50 session.
 180        For HTTP this session ID only tracks the HTTP socket (kept alive).
 181        NOT to be confused the the HTTP cookie mechanism.
 182       </para>
 183      </listitem>
 184     </varlistentry>
 185
 186     <varlistentry><term>elapsed (position 5)</term>
 187      <listitem><para>
 188        Elapsed time .
 189        The elapsed time is the time between the point in time
 190        where a package was received form the client and the
 191        point where a response was received from the next filter
 192        in chain (backend eventually).
 193       </para>
 194      </listitem>
 195     </varlistentry>
 196     <varlistentry><term>protocol (position 6)</term>
 197      <listitem><para>
 198        Protocol type which is one of <literal>Z3950</literal> or
 199        <literal>HTTP_Request</literal> or
 200        <literal>HTTP_Response</literal>.
 201       </para>
 202      </listitem>
 203     </varlistentry>
 204    </variablelist>
 205   </para>
 206
 207   <para>
 208    For packages of with protocol marker <literal>Z3950</literal>
 209    the the access log line is followed by the APDU type + information
 210    depending on the type. The APDU type is on position 7.
 211
 212    <variablelist>
 213
 214     <varlistentry><term>initRequest</term>
 215      <listitem><para>
 216        Z39.50 Initialize Request with the information
 217        username, vhost,
 218        implementation ID, implementation name, implementation version.
 219       </para>
 220      </listitem>
 221     </varlistentry>
 222
 223     <varlistentry><term>initResponse</term>
 224      <listitem><para>
 225        Z39.50 Initialize Response with the information:
 226        status (OK or FAIL), implementatino ID, implementation name,
 227        implementation version.
 228       </para>
 229      </listitem>
 230     </varlistentry>
 231
 232     <varlistentry><term>searchRequest</term>
 233      <listitem><para>
 234        Z39.50 Search Request with the information:
 235        database(s), result set ID, record syntax, query.
 236       </para>
 237       <para>
 238        Multiple databases are separated by
 239        a plus-sign (<literal>+</literal>). The query itself is
 240        multiple tokens. For this reason it is placed as the last
 241        information on this log entry.
 242       </para>
 243      </listitem>
 244     </varlistentry>
 245
 246     <varlistentry><term>searchResponse</term>
 247      <listitem><para>
 248        Z39.50 Search Response with the information:
 249        status (OK or FAIL), hit count, number of records returned,
 250        next result set position.
 251       </para>
 252      </listitem>
 253     </varlistentry>
 254
 255     <varlistentry><term>presentRequest</term>
 256      <listitem><para>
 257        Z39.50 Present Request with the information:
 258        result Set ID, start position, number of records requested,
 259        record syntax, record composition.
 260       </para>
 261      </listitem>
 262     </varlistentry>
 263
 264     <varlistentry><term>presentResponse</term>
 265      <listitem><para>
 266        Z39.50 Present Response with the information:
 267        status (OK, DIAG, ERROR), number of records returned,
 268        next result set position.
 269       </para>
 270      </listitem>
 271     </varlistentry>
 272
 273     <varlistentry><term>scanRequest</term>
 274      <listitem><para>
 275        Z39.50 Scan Request with the information:
 276        database(s), number of terms requested, preferred position in
 277        response, step size, start point.
 278       </para>
 279       <para>
 280        start point is a multi token value in PQF notation.
 281       </para>
 282      </listitem>
 283     </varlistentry>
 284
 285     <varlistentry><term>scanResponse</term>
 286      <listitem><para>
 287        Z39.50 Scan Response with the information:
 288        status (OK, ERROR), number of entries returned, position of term,
 289        step size.
 290       </para>
 291      </listitem>
 292     </varlistentry>
 293
 294    </variablelist>
 295   </para>
 296
 297  </refsect1>
 298
 299  <refsect1><title>SCHEMA</title>
 300    <literallayout><xi:include
 301                      xi:href="../xml/schema/filter_log.rnc" xi:parse="text"
 302                      xmlns:xi="http://www.w3.org/2001/XInclude" />
 303    </literallayout>
 304  </refsect1>
 305
 306  <refsect1><title>EXAMPLES</title>
 307   <para>
 308    A typical configuration looks like this:
 309    <screen><![CDATA[
 310     <filter type="log">
 311      <message>B</message>
 312      <category access="true"/>
 313      <filename>logs/metaproxy.log</filename>
 314     </filter>
 315 ]]>
 316    </screen>
 317   </para>
 318  </refsect1>
 319
 320  <refsect1><title>SEE ALSO</title>
 321   <para>
 322    <citerefentry>
 323     <refentrytitle>metaproxy</refentrytitle>
 324     <manvolnum>1</manvolnum>
 325    </citerefentry>
 326   </para>
 327  </refsect1>
 328
 329  &copyright;
 330 </refentry>
 331
 332 <!-- Keep this comment at the end of the file
 333 Local variables:
 334 mode: nxml
 335 nxml-child-indent: 1
 336 End:
 337 -->