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