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>time-format</term>
42 Date+time format if log is written to a custom file (see filename configuration, below), using the format of
44 url="http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">
48 Use option -m in invocation of Metaproxy command to set format if yaz_log is used (no filename given).
52 <varlistentry><term>filename</term>
55 Specifies a name of log file. If this is omitted, logging is performed
56 using the log system of YAZ (yaz_log).
60 <varlistentry><term>category</term>
63 Specifies the category of messages to be logged. The category is an
64 XML attribute and value of attribute is a boolean;
65 <literal>true</literal> for enabled; <literal>false</literal>
67 The following category attributes are supported:
70 <varlistentry><term>access</term>
73 One line log messages inspired by Apache access log entries.
74 This is a brief message stating the request and response.
75 This is enabled by default. All other categories are disabled by
76 default. See the section ACCESS LOG.
80 <varlistentry><term>user-access</term>
83 One line log messages similar to <literal>access</literal> but
84 with the authenticated user on each log line.
88 <varlistentry><term>request-apdu</term>
95 <varlistentry><term>response-apdu</term>
102 <varlistentry><term>apdu</term>
105 Z39.50 APDU (request and response)
109 <varlistentry><term>request-session</term>
116 <varlistentry><term>response-session</term>
123 <varlistentry><term>session</term>
126 Session (request and response)
130 <varlistentry><term>init-options</term>
133 Z39.50 Init Request options
146 <refsect1><title>The access log</title>
148 The access is is strictly one line per entry and aims for
149 easy mangling with tools such as awk, grep, perl etc.
150 Many values may be omitted in the packages in which case a single
151 dash is printed instead. This is to ensure that all values have
152 well-defined position.
155 The basic format and order is
157 <varlistentry><term>time (position 1)</term>
164 <varlistentry><term>Custom message (position 2)</term>
166 The string as given in element <literal>message</literal>.
171 <varlistentry><term>IP (position 3)</term>
173 IP address of origin (peer)
176 If category <literal>user-acesss</literal> is used the
177 user is written on position 3 and the IP is written on position 4.
182 <varlistentry><term>session (position 4)</term>
184 Session ID. Can be used to identify a particular Z39.50 session.
185 For HTTP this session ID only tracks the HTTP socket (kept alive).
186 NOT to be confused the the HTTP cookie mechanism.
191 <varlistentry><term>elapsed (position 5)</term>
194 The elapsed time is the time between the point in time
195 where a package was received form the client and the
196 point where a response was received from the next filter
197 in chain (backend eventually).
201 <varlistentry><term>protocol (position 6)</term>
203 Protocol type which is one of <literal>Z3950</literal> or
204 <literal>HTTP_Request</literal> or
205 <literal>HTTP_Response</literal>.
213 For packages of with protocol marker <literal>Z3950</literal>
214 the the access log line is followed by the APDU type + information
215 depending on the type. The APDU type is on position 7.
219 <varlistentry><term>initRequest</term>
221 Z39.50 Initialize Request with the information
223 implementation ID, implementation name, implementation version.
228 <varlistentry><term>initResponse</term>
230 Z39.50 Initialize Response with the information:
231 status (OK or FAIL), implementatino ID, implementation name,
232 implementation version.
237 <varlistentry><term>searchRequest</term>
239 Z39.50 Search Request with the information:
240 database(s), result set ID, record syntax, query.
243 Multiple databases are separated by
244 a plus-sign (<literal>+</literal>). The query itself is
245 multiple tokens. For this reason it is placed as the last
246 information on this log entry.
251 <varlistentry><term>searchResponse</term>
253 Z39.50 Search Response with the information:
254 status (OK or FAIL), hit count, number of records returned,
255 next result set position.
260 <varlistentry><term>presentRequest</term>
262 Z39.50 Present Request with the information:
263 result Set ID, start position, number of records requested,
264 record syntax, record composition.
269 <varlistentry><term>presentResponse</term>
271 Z39.50 Present Response with the information:
272 status (OK, DIAG, ERROR), number of records returned,
273 next result set position.
278 <varlistentry><term>scanRequest</term>
280 Z39.50 Scan Request with the information:
281 database(s), number of terms requested, preferred position in
282 response, step size, start point.
285 start point is a multi token value in PQF notation.
290 <varlistentry><term>scanResponse</term>
292 Z39.50 Scan Response with the information:
293 status (OK, ERROR), number of entries returned, position of term,
304 <refsect1><title>SCHEMA</title>
305 <literallayout><xi:include
306 xi:href="../xml/schema/filter_log.rnc" xi:parse="text"
307 xmlns:xi="http://www.w3.org/2001/XInclude" />
311 <refsect1><title>EXAMPLES</title>
313 A typical configuration looks like this:
317 <category access="true"/>
318 <filename>logs/metaproxy.log</filename>
325 <refsect1><title>SEE ALSO</title>
328 <refentrytitle>metaproxy</refentrytitle>
329 <manvolnum>1</manvolnum>
337 <!-- Keep this comment at the end of the file