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 <refentry id="ref-log">
9 <refentrytitle>log</refentrytitle>
10 <manvolnum>3mp</manvolnum>
11 <refmiscinfo>Metaproxy Module</refmiscinfo>
15 <refname>log</refname>
16 <refpurpose>Metaproxy Package Logging Module</refpurpose>
19 <refsect1><title>DESCRIPTION</title>
21 This filter logs packages sent - and received .
27 <varlistentry><term>message</term>
30 Specifies a custom message for the log message.
34 <varlistentry><term>filename</term>
37 Specifies a name of log file.
41 <varlistentry><term>category</term>
44 Specifies the category of messages to be logged. The category is an
45 XML attribute and value of attribute is a boolean;
46 <literal>true</literal> for enabled; <literal>false</literal>
48 The following category attributes are supported:
51 <varlistentry><term>access</term>
54 One line log messages inspired by Apache access log entries.
55 This is a brief message stating the request and response.
56 This is enabled by default. All other categories are disabled by
57 default. See the section ACCESS LOG.
61 <varlistentry><term>user-access</term>
64 One line log messages similar to <literal>access</literal> but
65 with the authenticated user on each log line.
69 <varlistentry><term>request-apdu</term>
76 <varlistentry><term>response-apdu</term>
83 <varlistentry><term>apdu</term>
86 Z39.50 APDU (request and response)
90 <varlistentry><term>request-session</term>
97 <varlistentry><term>response-session</term>
104 <varlistentry><term>session</term>
107 Session (request and response)
111 <varlistentry><term>init-options</term>
114 Z39.50 Init Request options
127 <refsect1><title>The access log</title>
129 The access is is strictly one line per entry and aims for
130 easy mangling with tools such as awk, grep, perl etc.
131 Many values may be omitted in the packages in which case a single
132 dash is printed instead. This is to ensure that all values have
133 well-defined position.
136 The basic format and order is
138 <varlistentry><term>time (position 1)</term>
145 <varlistentry><term>Custom message (position 2)</term>
147 The string as given in element <literal>message</literal>.
152 <varlistentry><term>IP (position 3)</term>
154 IP address of origin (peer)
157 If category <literal>user-acesss</literal> is used the
158 user is written on position 3 and the IP is written on position 4.
163 <varlistentry><term>session (position 4)</term>
165 Session ID. Can be used to identify a particular Z39.50 session.
166 For HTTP this session ID only tracks the HTTP socket (kept alive).
167 NOT to be confused the the HTTP cookie mechanism.
172 <varlistentry><term>elapsed (position 5)</term>
175 The elapsed time is the time between the point in time
176 where a package was received form the client and the
177 point where a response was received from the next filter
178 in chain (backend eventually).
182 <varlistentry><term>protocol (position 6)</term>
184 Protocol type which is one of <literal>Z3950</literal> or
185 <literal>HTTP_Request</literal> or
186 <literal>HTTP_Response</literal>.
194 For packages of with protocol marker <literal>Z3950</literal>
195 the the access log line is followed by the APDU type + information
196 depending on the type. The APDU type is on position 7.
200 <varlistentry><term>initRequest</term>
202 Z39.50 Initialize Request with the information
204 implementation ID, implementation name, implementation version.
209 <varlistentry><term>initResponse</term>
211 Z39.50 Initialize Response with the information:
212 status (OK or FAIL), implementatino ID, implementation name,
213 implementation version.
218 <varlistentry><term>searchRequest</term>
220 Z39.50 Search Request with the information:
221 database(s), result set ID, record syntax, query.
224 Multiple databases are separated by
225 a plus-sign (<literal>+</literal>). The query itself is
226 multiple tokens. For this reason it is placed as the last
227 information on this log entry.
232 <varlistentry><term>searchResponse</term>
234 Z39.50 Search Response with the information:
235 status (OK or FAIL), hit count, number of records returned,
236 next result set position.
241 <varlistentry><term>presentRequest</term>
243 Z39.50 Present Request with the information:
244 result Set ID, start position, number of records requested,
245 record syntax, record composition.
250 <varlistentry><term>presentResponse</term>
252 Z39.50 Present Response with the information:
253 status (OK, DIAG, ERROR), number of records returned,
254 next result set position.
259 <varlistentry><term>scanRequest</term>
261 Z39.50 Scan Request with the information:
262 database(s), number of terms requested, preferred position in
263 response, step size, start point.
266 start point is a multi token value in PQF notation.
271 <varlistentry><term>scanResponse</term>
273 Z39.50 Scan Response with the information:
274 status (OK, ERROR), number of entries returned, position of term,
285 <refsect1><title>EXAMPLES</title>
287 A typical configuration looks like this:
291 <category access="true"/>
292 <filename>logs/metaproxy.log</filename>
299 <refsect1><title>SEE ALSO</title>
302 <refentrytitle>metaproxy</refentrytitle>
303 <manvolnum>1</manvolnum>
311 <!-- Keep this comment at the end of the file
316 sgml-minimize-attributes:nil
317 sgml-always-quote-attributes:t
320 sgml-parent-document:nil
321 sgml-local-catalogs: nil
322 sgml-namecase-general:t