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