-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY copyright SYSTEM "copyright.xml">
+ <!ENTITY % idcommon SYSTEM "common/common.ent">
+ %idcommon;
]>
-<!-- $Id: log.xml,v 1.4 2006-04-25 12:48:52 marc Exp $ -->
-<refentry>
+<refentry id="ref-log">
+ <refentryinfo>
+ <productname>Metaproxy</productname>
+ <orgname>Index Data</orgname>
+ </refentryinfo>
+
<refmeta>
<refentrytitle>log</refentrytitle>
<manvolnum>3mp</manvolnum>
- <refmiscinfo>Metaproxy Module</refmiscinfo>
-</refmeta>
-
+ <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
+ </refmeta>
+
<refnamediv>
<refname>log</refname>
- <refpurpose>logs packages</refpurpose>
+ <refpurpose>Metaproxy Package Logging Module</refpurpose>
</refnamediv>
-
+
<refsect1><title>DESCRIPTION</title>
<para>
- This filter logs packages sent - and received .
+ This filter logs packages sent - and received .
+ </para>
+
+ <para>
+ Configurable values:
+ <variablelist>
+ <varlistentry><term>message</term>
+ <listitem>
+ <para>
+ Specifies a custom message for the log message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>time-format</term>
+ <listitem>
+ <para>
+ Date+time format if log is written to a custom file (see filename configuration, below), using the format of
+ <ulink
+ url="http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">
+ strftime(3)</ulink>.
+ </para>
+ <para>
+ Use option -m in invocation of Metaproxy command to set format if yaz_log is used (no filename given).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>filename</term>
+ <listitem>
+ <para>
+ Specifies a name of log file. If this is omitted, logging is performed
+ using the log system of YAZ (yaz_log).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>category</term>
+ <listitem>
+ <para>
+ Specifies the category of messages to be logged. The category is an
+ XML attribute and value of attribute is a boolean;
+ <literal>true</literal> for enabled; <literal>false</literal>
+ for disabled.
+ The following category attributes are supported:
+
+ <variablelist>
+ <varlistentry><term>access</term>
+ <listitem>
+ <para>
+ One line log messages inspired by Apache access log entries.
+ This is a brief message stating the request and response.
+ This is enabled by default. All other categories are disabled by
+ default. See the section ACCESS LOG.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>user-access</term>
+ <listitem>
+ <para>
+ One line log messages similar to <literal>access</literal> but
+ with the authenticated user on each log line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>request-apdu</term>
+ <listitem>
+ <para>
+ Z39.50 Request APDU.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>response-apdu</term>
+ <listitem>
+ <para>
+ Z39.50 Response APDU.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>apdu</term>
+ <listitem>
+ <para>
+ Z39.50 APDU (request and response)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>request-session</term>
+ <listitem>
+ <para>
+ Request session.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>response-session</term>
+ <listitem>
+ <para>
+ Response session.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>session</term>
+ <listitem>
+ <para>
+ Session (request and response)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>init-options</term>
+ <listitem>
+ <para>
+ Z39.50 Init Request options
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>line</term>
+ <listitem>
+ <para>
+ Simple one-line log message indicating the most important
+ things from a request and response.
+ Available from version 1.3.38 and later.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1><title>The access log</title>
+ <para>
+ The access is is strictly one line per entry and aims for
+ easy mangling with tools such as awk, grep, perl etc.
+ Many values may be omitted in the packages in which case a single
+ dash is printed instead. This is to ensure that all values have
+ well-defined position.
+ </para>
+ <para>
+ The basic format and order is
+ <variablelist>
+ <varlistentry><term>time (position 1)</term>
+ <listitem><para>
+ Full time of event
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>Custom message (position 2)</term>
+ <listitem><para>
+ The string as given in element <literal>message</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>IP (position 3)</term>
+ <listitem><para>
+ IP address of origin (peer)
+ </para>
+ <para>
+ If category <literal>user-acesss</literal> is used the
+ user is written on position 3 and the IP is written on position 4.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>session (position 4)</term>
+ <listitem><para>
+ Session ID. Can be used to identify a particular Z39.50 session.
+ For HTTP this session ID only tracks the HTTP socket (kept alive).
+ NOT to be confused the the HTTP cookie mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>elapsed (position 5)</term>
+ <listitem><para>
+ Elapsed time .
+ The elapsed time is the time between the point in time
+ where a package was received form the client and the
+ point where a response was received from the next filter
+ in chain (backend eventually).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>protocol (position 6)</term>
+ <listitem><para>
+ Protocol type which is one of <literal>Z3950</literal> or
+ <literal>HTTP_Request</literal> or
+ <literal>HTTP_Response</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ For packages of with protocol marker <literal>Z3950</literal>
+ the the access log line is followed by the APDU type + information
+ depending on the type. The APDU type is on position 7.
+
+ <variablelist>
+
+ <varlistentry><term>initRequest</term>
+ <listitem><para>
+ Z39.50 Initialize Request with the information
+ username, vhost,
+ implementation ID, implementation name, implementation version.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>initResponse</term>
+ <listitem><para>
+ Z39.50 Initialize Response with the information:
+ status (OK or FAIL), implementatino ID, implementation name,
+ implementation version.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>searchRequest</term>
+ <listitem><para>
+ Z39.50 Search Request with the information:
+ database(s), result set ID, record syntax, query.
+ </para>
+ <para>
+ Multiple databases are separated by
+ a plus-sign (<literal>+</literal>). The query itself is
+ multiple tokens. For this reason it is placed as the last
+ information on this log entry.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>searchResponse</term>
+ <listitem><para>
+ Z39.50 Search Response with the information:
+ status (OK or FAIL), hit count, number of records returned,
+ next result set position.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>presentRequest</term>
+ <listitem><para>
+ Z39.50 Present Request with the information:
+ result Set ID, start position, number of records requested,
+ record syntax, record composition.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>presentResponse</term>
+ <listitem><para>
+ Z39.50 Present Response with the information:
+ status (OK, DIAG, ERROR), number of records returned,
+ next result set position.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>scanRequest</term>
+ <listitem><para>
+ Z39.50 Scan Request with the information:
+ database(s), number of terms requested, preferred position in
+ response, step size, start point.
+ </para>
+ <para>
+ start point is a multi token value in PQF notation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>scanResponse</term>
+ <listitem><para>
+ Z39.50 Scan Response with the information:
+ status (OK, ERROR), number of entries returned, position of term,
+ step size.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
</para>
+
+ </refsect1>
+
+ <refsect1><title>SCHEMA</title>
+ <literallayout><xi:include
+ xi:href="../xml/schema/filter_log.rnc" xi:parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
</refsect1>
-
+
<refsect1><title>EXAMPLES</title>
<para>
A typical configuration looks like this:
<screen><![CDATA[
<filter type="log">
<message>B</message>
+ <category access="true"/>
+ <filename>logs/metaproxy.log</filename>
</filter>
]]>
</screen>
</para>
- </refsect1>
-
+ </refsect1>
+
<refsect1><title>SEE ALSO</title>
<para>
<citerefentry>
</citerefentry>
</para>
</refsect1>
-
+
©right;
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
+mode: nxml
+nxml-child-indent: 1
End:
-->
projects / metaproxy-moved-to-github.git / blobdiff