1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
3 <!ENTITY copyright SYSTEM "copyright.xml">
4 <!ENTITY % idcommon SYSTEM "common/common.ent">
7 <!-- $Id: log.xml,v 1.11 2007-05-22 13:03:32 adam Exp $ -->
8 <refentry id="ref-log">
10 <refentrytitle>log</refentrytitle>
11 <manvolnum>3mp</manvolnum>
12 <refmiscinfo>Metaproxy Module</refmiscinfo>
16 <refname>log</refname>
17 <refpurpose>Metaproxy Package Logging Module</refpurpose>
20 <refsect1><title>DESCRIPTION</title>
22 This filter logs packages sent - and received .
28 <varlistentry><term>message</term>
31 Specifies a custom message for the log message.
35 <varlistentry><term>filename</term>
38 Specifies a name of log file.
42 <varlistentry><term>category</term>
45 Specifies the category of messages to be logged. The category is an
46 XML attribute and value of attribute is a boolean;
47 <literal>true</literal> for enabled; <literal>false</literal>
49 The following category attributes are supported:
52 <varlistentry><term>access</term>
55 One line log messages inspired by Apache access log entries.
56 This is a brief message stating the request and response.
57 This is enabled by default. All other categories are disabled by
58 default. See the section ACCESS LOG.
62 <varlistentry><term>request-apdu</term>
69 <varlistentry><term>response-apdu</term>
76 <varlistentry><term>apdu</term>
79 Z39.50 APDU (request and response)
83 <varlistentry><term>request-session</term>
90 <varlistentry><term>response-session</term>
97 <varlistentry><term>session</term>
100 Session (request and response)
104 <varlistentry><term>init-options</term>
107 Z39.50 Init Request options
120 <refsect1><title>The access log</title>
122 The access is is strictly one line per entry and aims for
123 easy mangling with tools such as awk, grep, perl etc.
124 Many values may be omitted in the packages in which case a single
125 dash is printed instead. This is to ensure that all values have
126 well-defined position.
129 The basic format and order is
131 <varlistentry><term>time (position 1)</term>
138 <varlistentry><term>Custom message (position 2)</term>
140 The string as given in element <literal>message</literal>.
145 <varlistentry><term>IP (position 3)</term>
147 IP address of origin (peer)
152 <varlistentry><term>session (position 4)</term>
154 Session ID. Can be used to identify a particular Z39.50 session.
155 For HTTP this session ID only tracks the HTTP socket (kept alive).
156 NOT to be confused the the HTTP cookie mechanism.
161 <varlistentry><term>elapsed (position 5)</term>
164 The elapsed time is the time between the point in time
165 where a package was received form the client and the
166 point where a response was received from the next filter
167 in chain (backend eventually).
171 <varlistentry><term>protocol (position 6)</term>
173 Protocol type which is one of <literal>Z3950</literal> or
174 <literal>HTTP_Request</literal> or
175 <literal>HTTP_Response</literal>.
183 For packages of with protocol marker <literal>Z3950</literal>
184 the the access log line is followed by the APDU type + information
185 depending on the type. The APDU type is on position 7.
189 <varlistentry><term>initRequest</term>
191 Z39.50 Initialize Request with the information
193 implementation ID, implementation name, implementation version.
198 <varlistentry><term>initResponse</term>
200 Z39.50 Initialize Response with the information:
201 status (OK or FAIL), implementatino ID, implementation name,
202 implementation version.
207 <varlistentry><term>searchRequest</term>
209 Z39.50 Search Request with the information:
210 database(s), result set ID, record syntax, query.
213 Multiple databases are separated by
214 a plus-sign (<literal>+</literal>). The query itself is
215 multiple tokens. For this reason it is placed as the last
216 information on this log entry.
221 <varlistentry><term>searchResponse</term>
223 Z39.50 Search Response with the information:
224 status (OK or FAIL), hit count, number of records returned,
225 next result set position.
230 <varlistentry><term>presentRequest</term>
232 Z39.50 Present Request with the information:
233 result Set ID, start position, number of records requested,
234 record syntax, record composition.
239 <varlistentry><term>presentResponse</term>
241 Z39.50 Present Response with the information:
242 status (OK, DIAG, ERROR), number of records returned,
243 next result set position.
248 <varlistentry><term>scanRequest</term>
250 Z39.50 Scan Request with the information:
251 database(s), number of terms requested, preferred position in
252 response, step size, start point.
255 start point is a multi token value in PQF notation.
260 <varlistentry><term>scanResponse</term>
262 Z39.50 Scan Response with the information:
263 status (OK, ERROR), number of entries returned, position of term,
274 <refsect1><title>EXAMPLES</title>
276 A typical configuration looks like this:
280 <category access="true"/>
281 <filename>logs/metaproxy.log</filename>
288 <refsect1><title>SEE ALSO</title>
291 <refentrytitle>metaproxy</refentrytitle>
292 <manvolnum>1</manvolnum>
300 <!-- Keep this comment at the end of the file
305 sgml-minimize-attributes:nil
306 sgml-always-quote-attributes:t
309 sgml-parent-document:nil
310 sgml-local-catalogs: nil
311 sgml-namecase-general:t