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">
7 <refentry id="ref-log">
9 <productname>Metaproxy</productname>
10 <info><orgname>Index Data</orgname></info>
14 <refentrytitle>log</refentrytitle>
15 <manvolnum>3mp</manvolnum>
16 <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
20 <refname>log</refname>
21 <refpurpose>Metaproxy Package Logging Module</refpurpose>
24 <refsect1><title>DESCRIPTION</title>
26 This filter logs packages sent - and received .
32 <varlistentry><term>message</term>
35 Specifies a custom message for the log message.
39 <varlistentry><term>filename</term>
42 Specifies a name of log file.
46 <varlistentry><term>category</term>
49 Specifies the category of messages to be logged. The category is an
50 XML attribute and value of attribute is a boolean;
51 <literal>true</literal> for enabled; <literal>false</literal>
53 The following category attributes are supported:
56 <varlistentry><term>access</term>
59 One line log messages inspired by Apache access log entries.
60 This is a brief message stating the request and response.
61 This is enabled by default. All other categories are disabled by
62 default. See the section ACCESS LOG.
66 <varlistentry><term>user-access</term>
69 One line log messages similar to <literal>access</literal> but
70 with the authenticated user on each log line.
74 <varlistentry><term>request-apdu</term>
81 <varlistentry><term>response-apdu</term>
88 <varlistentry><term>apdu</term>
91 Z39.50 APDU (request and response)
95 <varlistentry><term>request-session</term>
102 <varlistentry><term>response-session</term>
109 <varlistentry><term>session</term>
112 Session (request and response)
116 <varlistentry><term>init-options</term>
119 Z39.50 Init Request options
132 <refsect1><title>The access log</title>
134 The access is is strictly one line per entry and aims for
135 easy mangling with tools such as awk, grep, perl etc.
136 Many values may be omitted in the packages in which case a single
137 dash is printed instead. This is to ensure that all values have
138 well-defined position.
141 The basic format and order is
143 <varlistentry><term>time (position 1)</term>
150 <varlistentry><term>Custom message (position 2)</term>
152 The string as given in element <literal>message</literal>.
157 <varlistentry><term>IP (position 3)</term>
159 IP address of origin (peer)
162 If category <literal>user-acesss</literal> is used the
163 user is written on position 3 and the IP is written on position 4.
168 <varlistentry><term>session (position 4)</term>
170 Session ID. Can be used to identify a particular Z39.50 session.
171 For HTTP this session ID only tracks the HTTP socket (kept alive).
172 NOT to be confused the the HTTP cookie mechanism.
177 <varlistentry><term>elapsed (position 5)</term>
180 The elapsed time is the time between the point in time
181 where a package was received form the client and the
182 point where a response was received from the next filter
183 in chain (backend eventually).
187 <varlistentry><term>protocol (position 6)</term>
189 Protocol type which is one of <literal>Z3950</literal> or
190 <literal>HTTP_Request</literal> or
191 <literal>HTTP_Response</literal>.
199 For packages of with protocol marker <literal>Z3950</literal>
200 the the access log line is followed by the APDU type + information
201 depending on the type. The APDU type is on position 7.
205 <varlistentry><term>initRequest</term>
207 Z39.50 Initialize Request with the information
209 implementation ID, implementation name, implementation version.
214 <varlistentry><term>initResponse</term>
216 Z39.50 Initialize Response with the information:
217 status (OK or FAIL), implementatino ID, implementation name,
218 implementation version.
223 <varlistentry><term>searchRequest</term>
225 Z39.50 Search Request with the information:
226 database(s), result set ID, record syntax, query.
229 Multiple databases are separated by
230 a plus-sign (<literal>+</literal>). The query itself is
231 multiple tokens. For this reason it is placed as the last
232 information on this log entry.
237 <varlistentry><term>searchResponse</term>
239 Z39.50 Search Response with the information:
240 status (OK or FAIL), hit count, number of records returned,
241 next result set position.
246 <varlistentry><term>presentRequest</term>
248 Z39.50 Present Request with the information:
249 result Set ID, start position, number of records requested,
250 record syntax, record composition.
255 <varlistentry><term>presentResponse</term>
257 Z39.50 Present Response with the information:
258 status (OK, DIAG, ERROR), number of records returned,
259 next result set position.
264 <varlistentry><term>scanRequest</term>
266 Z39.50 Scan Request with the information:
267 database(s), number of terms requested, preferred position in
268 response, step size, start point.
271 start point is a multi token value in PQF notation.
276 <varlistentry><term>scanResponse</term>
278 Z39.50 Scan Response with the information:
279 status (OK, ERROR), number of entries returned, position of term,
290 <refsect1><title>SCHEMA</title>
291 <literallayout><xi:include
292 xi:href="../xml/schema/filter_log.rnc" xi:parse="text"
293 xmlns:xi="http://www.w3.org/2001/XInclude" />
297 <refsect1><title>EXAMPLES</title>
299 A typical configuration looks like this:
303 <category access="true"/>
304 <filename>logs/metaproxy.log</filename>
311 <refsect1><title>SEE ALSO</title>
314 <refentrytitle>metaproxy</refentrytitle>
315 <manvolnum>1</manvolnum>
323 <!-- Keep this comment at the end of the file
328 sgml-minimize-attributes:nil
329 sgml-always-quote-attributes:t
332 sgml-parent-document:nil
333 sgml-local-catalogs: nil
334 sgml-namecase-general:t