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.12 2007-05-22 19:45:57 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>user-access</term>
65 One line log messages similar to <literal>access</literal> but
66 with the authenticated user on each log line.
70 <varlistentry><term>request-apdu</term>
77 <varlistentry><term>response-apdu</term>
84 <varlistentry><term>apdu</term>
87 Z39.50 APDU (request and response)
91 <varlistentry><term>request-session</term>
98 <varlistentry><term>response-session</term>
105 <varlistentry><term>session</term>
108 Session (request and response)
112 <varlistentry><term>init-options</term>
115 Z39.50 Init Request options
128 <refsect1><title>The access log</title>
130 The access is is strictly one line per entry and aims for
131 easy mangling with tools such as awk, grep, perl etc.
132 Many values may be omitted in the packages in which case a single
133 dash is printed instead. This is to ensure that all values have
134 well-defined position.
137 The basic format and order is
139 <varlistentry><term>time (position 1)</term>
146 <varlistentry><term>Custom message (position 2)</term>
148 The string as given in element <literal>message</literal>.
153 <varlistentry><term>IP (position 3)</term>
155 IP address of origin (peer)
158 If category <literal>user-acesss</literal> is used the
159 user is written on position 3 and the IP is written on position 4.
164 <varlistentry><term>session (position 4)</term>
166 Session ID. Can be used to identify a particular Z39.50 session.
167 For HTTP this session ID only tracks the HTTP socket (kept alive).
168 NOT to be confused the the HTTP cookie mechanism.
173 <varlistentry><term>elapsed (position 5)</term>
176 The elapsed time is the time between the point in time
177 where a package was received form the client and the
178 point where a response was received from the next filter
179 in chain (backend eventually).
183 <varlistentry><term>protocol (position 6)</term>
185 Protocol type which is one of <literal>Z3950</literal> or
186 <literal>HTTP_Request</literal> or
187 <literal>HTTP_Response</literal>.
195 For packages of with protocol marker <literal>Z3950</literal>
196 the the access log line is followed by the APDU type + information
197 depending on the type. The APDU type is on position 7.
201 <varlistentry><term>initRequest</term>
203 Z39.50 Initialize Request with the information
205 implementation ID, implementation name, implementation version.
210 <varlistentry><term>initResponse</term>
212 Z39.50 Initialize Response with the information:
213 status (OK or FAIL), implementatino ID, implementation name,
214 implementation version.
219 <varlistentry><term>searchRequest</term>
221 Z39.50 Search Request with the information:
222 database(s), result set ID, record syntax, query.
225 Multiple databases are separated by
226 a plus-sign (<literal>+</literal>). The query itself is
227 multiple tokens. For this reason it is placed as the last
228 information on this log entry.
233 <varlistentry><term>searchResponse</term>
235 Z39.50 Search Response with the information:
236 status (OK or FAIL), hit count, number of records returned,
237 next result set position.
242 <varlistentry><term>presentRequest</term>
244 Z39.50 Present Request with the information:
245 result Set ID, start position, number of records requested,
246 record syntax, record composition.
251 <varlistentry><term>presentResponse</term>
253 Z39.50 Present Response with the information:
254 status (OK, DIAG, ERROR), number of records returned,
255 next result set position.
260 <varlistentry><term>scanRequest</term>
262 Z39.50 Scan Request with the information:
263 database(s), number of terms requested, preferred position in
264 response, step size, start point.
267 start point is a multi token value in PQF notation.
272 <varlistentry><term>scanResponse</term>
274 Z39.50 Scan Response with the information:
275 status (OK, ERROR), number of entries returned, position of term,
286 <refsect1><title>EXAMPLES</title>
288 A typical configuration looks like this:
292 <category access="true"/>
293 <filename>logs/metaproxy.log</filename>
300 <refsect1><title>SEE ALSO</title>
303 <refentrytitle>metaproxy</refentrytitle>
304 <manvolnum>1</manvolnum>
312 <!-- Keep this comment at the end of the file
317 sgml-minimize-attributes:nil
318 sgml-always-quote-attributes:t
321 sgml-parent-document:nil
322 sgml-local-catalogs: nil
323 sgml-namecase-general:t