<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Batteries.FingerTree.html">
<link rel="next" href="Batteries.MultiMap.html">
<link rel="Up" href="Batteries.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="BatArray" rel="Chapter" href="BatArray.html">
<link title="BatAvlTree" rel="Chapter" href="BatAvlTree.html">
<link title="BatBase64" rel="Chapter" href="BatBase64.html">
<link title="BatBig_int" rel="Chapter" href="BatBig_int.html">
<link title="BatBigarray" rel="Chapter" href="BatBigarray.html">
<link title="BatBitSet" rel="Chapter" href="BatBitSet.html">
<link title="BatBool" rel="Chapter" href="BatBool.html">
<link title="BatBounded" rel="Chapter" href="BatBounded.html">
<link title="BatBuffer" rel="Chapter" href="BatBuffer.html">
<link title="BatCache" rel="Chapter" href="BatCache.html">
<link title="BatChar" rel="Chapter" href="BatChar.html">
<link title="BatCharParser" rel="Chapter" href="BatCharParser.html">
<link title="BatComplex" rel="Chapter" href="BatComplex.html">
<link title="BatConcurrent" rel="Chapter" href="BatConcurrent.html">
<link title="BatDeque" rel="Chapter" href="BatDeque.html">
<link title="BatDigest" rel="Chapter" href="BatDigest.html">
<link title="BatDllist" rel="Chapter" href="BatDllist.html">
<link title="BatDynArray" rel="Chapter" href="BatDynArray.html">
<link title="BatEnum" rel="Chapter" href="BatEnum.html">
<link title="BatFile" rel="Chapter" href="BatFile.html">
<link title="BatFingerTree" rel="Chapter" href="BatFingerTree.html">
<link title="BatFloat" rel="Chapter" href="BatFloat.html">
<link title="BatFormat" rel="Chapter" href="BatFormat.html">
<link title="BatGc" rel="Chapter" href="BatGc.html">
<link title="BatGenlex" rel="Chapter" href="BatGenlex.html">
<link title="BatGlobal" rel="Chapter" href="BatGlobal.html">
<link title="BatHashcons" rel="Chapter" href="BatHashcons.html">
<link title="BatHashtbl" rel="Chapter" href="BatHashtbl.html">
<link title="BatHeap" rel="Chapter" href="BatHeap.html">
<link title="BatIMap" rel="Chapter" href="BatIMap.html">
<link title="BatIO" rel="Chapter" href="BatIO.html">
<link title="BatISet" rel="Chapter" href="BatISet.html">
<link title="BatInnerIO" rel="Chapter" href="BatInnerIO.html">
<link title="BatInnerPervasives" rel="Chapter" href="BatInnerPervasives.html">
<link title="BatInnerWeaktbl" rel="Chapter" href="BatInnerWeaktbl.html">
<link title="BatInt" rel="Chapter" href="BatInt.html">
<link title="BatInt32" rel="Chapter" href="BatInt32.html">
<link title="BatInt64" rel="Chapter" href="BatInt64.html">
<link title="BatInterfaces" rel="Chapter" href="BatInterfaces.html">
<link title="BatLazyList" rel="Chapter" href="BatLazyList.html">
<link title="BatLexing" rel="Chapter" href="BatLexing.html">
<link title="BatList" rel="Chapter" href="BatList.html">
<link title="BatLog" rel="Chapter" href="BatLog.html">
<link title="BatLogger" rel="Chapter" href="BatLogger.html">
<link title="BatMap" rel="Chapter" href="BatMap.html">
<link title="BatMarshal" rel="Chapter" href="BatMarshal.html">
<link title="BatMultiMap" rel="Chapter" href="BatMultiMap.html">
<link title="BatMultiPMap" rel="Chapter" href="BatMultiPMap.html">
<link title="BatMutex" rel="Chapter" href="BatMutex.html">
<link title="BatNativeint" rel="Chapter" href="BatNativeint.html">
<link title="BatNum" rel="Chapter" href="BatNum.html">
<link title="BatNumber" rel="Chapter" href="BatNumber.html">
<link title="BatOo" rel="Chapter" href="BatOo.html">
<link title="BatOptParse" rel="Chapter" href="BatOptParse.html">
<link title="BatOption" rel="Chapter" href="BatOption.html">
<link title="BatOrd" rel="Chapter" href="BatOrd.html">
<link title="BatParserCo" rel="Chapter" href="BatParserCo.html">
<link title="BatPathGen" rel="Chapter" href="BatPathGen.html">
<link title="BatPervasives" rel="Chapter" href="BatPervasives.html">
<link title="BatPrintexc" rel="Chapter" href="BatPrintexc.html">
<link title="BatPrintf" rel="Chapter" href="BatPrintf.html">
<link title="BatQueue" rel="Chapter" href="BatQueue.html">
<link title="BatRMutex" rel="Chapter" href="BatRMutex.html">
<link title="BatRandom" rel="Chapter" href="BatRandom.html">
<link title="BatRef" rel="Chapter" href="BatRef.html">
<link title="BatRefList" rel="Chapter" href="BatRefList.html">
<link title="BatResult" rel="Chapter" href="BatResult.html">
<link title="BatReturn" rel="Chapter" href="BatReturn.html">
<link title="BatScanf" rel="Chapter" href="BatScanf.html">
<link title="BatSeq" rel="Chapter" href="BatSeq.html">
<link title="BatSet" rel="Chapter" href="BatSet.html">
<link title="BatSplay" rel="Chapter" href="BatSplay.html">
<link title="BatStack" rel="Chapter" href="BatStack.html">
<link title="BatStream" rel="Chapter" href="BatStream.html">
<link title="BatString" rel="Chapter" href="BatString.html">
<link title="BatSubstring" rel="Chapter" href="BatSubstring.html">
<link title="BatSys" rel="Chapter" href="BatSys.html">
<link title="BatText" rel="Chapter" href="BatText.html">
<link title="BatTuple" rel="Chapter" href="BatTuple.html">
<link title="BatUChar" rel="Chapter" href="BatUChar.html">
<link title="BatUTF8" rel="Chapter" href="BatUTF8.html">
<link title="BatUnit" rel="Chapter" href="BatUnit.html">
<link title="BatUnix" rel="Chapter" href="BatUnix.html">
<link title="BatUref" rel="Chapter" href="BatUref.html">
<link title="BatVect" rel="Chapter" href="BatVect.html">
<link title="Batteries" rel="Chapter" href="Batteries.html">
<link title="BatteriesConfig" rel="Chapter" href="BatteriesConfig.html">
<link title="BatteriesPrint" rel="Chapter" href="BatteriesPrint.html">
<link title="BatteriesThread" rel="Chapter" href="BatteriesThread.html">
<link title="Extlib" rel="Chapter" href="Extlib.html"><link title="log modules" rel="Section" href="#6_logmodules">
<link title="log events" rel="Section" href="#6_logevents">
<link title="log formatters" rel="Section" href="#6_logformatters">
<link title="logger initialization" rel="Section" href="#6_loggerinitialization">
<link title="log utilities" rel="Section" href="#6_logutilities">
<title>Batteries user guide : Batteries.Logger</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Batteries.FingerTree.html" title="Batteries.FingerTree">Previous</a>
<a class="up" href="Batteries.html" title="Batteries">Up</a>
<a class="post" href="Batteries.MultiMap.html" title="Batteries.MultiMap">Next</a>
</div>
<h1>Module <a href="type_Batteries.Logger.html">Batteries.Logger</a></h1>
<pre><span class="keyword">module</span> Logger: <code class="type">BatLogger</code></pre><hr width="100%">
<br>
<h6 id="6_logmodules">log modules</h6><br>
<pre><span id="TYPElog"><span class="keyword">type</span> <code class="type"></code>log</span> </pre>
<pre><code><span id="TYPElevel"><span class="keyword">type</span> <code class="type"></code>level</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.NONE"><span class="constructor">NONE</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.FATAL"><span class="constructor">FATAL</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.ERROR"><span class="constructor">ERROR</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.WARN"><span class="constructor">WARN</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.NOTICE"><span class="constructor">NOTICE</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.INFO"><span class="constructor">INFO</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlevel.DEBUG"><span class="constructor">DEBUG</span></span></code></td>
</tr></table>
<pre><span id="VALmake_log"><span class="keyword">val</span> make_log</span> : <code class="type">string -> <a href="BatLogger.html#TYPElog">log</a></code></pre><div class="info ">
<code class="code">make_log name</code> returns a new logger.<br>
</div>
<pre><span id="VALlog_name"><span class="keyword">val</span> log_name</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> string</code></pre><div class="info ">
<code class="code">log_name logger</code> returns the name of the logger.<br>
</div>
<pre><span id="VALlog_enable"><span class="keyword">val</span> log_enable</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> <a href="BatLogger.html#TYPElevel">level</a> -> unit</code></pre><div class="info ">
<code class="code">log_enable logger level</code> enables a log level for a logger.<br>
</div>
<pre><span id="VALlog_level"><span class="keyword">val</span> log_level</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> <a href="BatLogger.html#TYPElevel">level</a></code></pre><div class="info ">
<code class="code">log_level logger</code> returns the currently enabled level for a logger.<br>
</div>
<pre><span id="VALlog_enabled"><span class="keyword">val</span> log_enabled</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> <a href="BatLogger.html#TYPElevel">level</a> -> bool</code></pre><div class="info ">
<code class="code">log_enabled logger level</code> returns true if the specified level is
currently enabled for the logger.<br>
</div>
<br>
<h6 id="6_logevents">log events</h6><br>
<pre><span id="TYPEevent"><span class="keyword">type</span> <code class="type"></code>event</span> = <code class="type">string * (string * string) list</code> </pre>
<div class="info ">
A log <code class="code">event</code> consists of an event name and a list of key-value
parameters (an association list). Events are constructed by
<code class="code">log</code> when a log level is enabled and passed to log formatters
to render them to any logging output stream.<br>
</div>
<pre><span id="VALlog"><span class="keyword">val</span> log</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> <a href="BatLogger.html#TYPElevel">level</a> -> (unit -> <a href="BatLogger.html#TYPEevent">event</a>) -> unit</code></pre><div class="info ">
<code class="code">log logger level event_fun</code> raises a log event if if the
specified level is currently enabled for the logger. The
function <code class="code">event_fun ()</code> is called to return the event record,
and is a function in order to delay construction or formatting
of any event parameters in the case where the specified log
level is not enabled. For example:
<p>
<pre class="codepre"><code class="code">log io_log <span class="constructor">INFO</span> (<span class="keyword">fun</span> () <span class="keywordsign">-></span> <span class="string">"connect"</span>, [<span class="string">"ADDR"</span>, addr])</code></pre>
<p>
would only log the <code class="code"><span class="string">"connect"</span></code> event (with the <code class="code"><span class="string">"ADDR"</span></code> string
parameter) when the <code class="code"><span class="constructor">INFO</span></code> log level was enabled for the
<code class="code">io_log</code> logger.<br>
</div>
<pre><span id="VALwith_log"><span class="keyword">val</span> with_log</span> : <code class="type"><a href="BatLogger.html#TYPElog">log</a> -><br> <a href="BatLogger.html#TYPElevel">level</a> -><br> (unit -> <a href="BatLogger.html#TYPEevent">event</a>) -> ?result:('a -> string) -> (unit -> 'a) -> 'a</code></pre><div class="info ">
<code class="code">with_log logger level event_fun ?result body</code> logs an event
before and after calling <code class="code">body ()</code>. The function <code class="code">event_fun ()</code>
is called to return the event record to be logged. After the
body is evaluated, the <code class="code">result</code> function is used to convert the
body's result value into a string, which is added to the event
record as a <code class="code"><span class="string">"RESULT"</span></code> parameter (if no <code class="code">result</code> function is
supplied then a <code class="code"><span class="string">"-"</span></code> is used). In the case where the body
raises an exception, an <code class="code"><span class="string">"EXN"</span></code> parameter is instead added to
the event containing the name of the exception. In addition, an
indentation level is maintained throughout the duration of the
body such that any other log statements occurring inside the
body will see an incremented indentation level. This is added
to the event key-value arguments as an additional <code class="code"><span class="string">"I"</span></code>
parameter.<br>
</div>
<br>
<h6 id="6_logformatters">log formatters</h6><br>
<pre><span id="TYPEformatter"><span class="keyword">type</span> <code class="type"></code>formatter</span> = <code class="type"><a href="BatLogger.html#TYPElog">log</a> -> <a href="BatLogger.html#TYPElevel">level</a> -> <a href="BatLogger.html#TYPEevent">event</a> -> float -> unit</code> </pre>
<div class="info ">
the type of a log formatter is a function that takes the
logger, the level of the log statement (which will be the
currently enabled level or one of its successors), the event
record, and a unix timestamp indicating the time the event was
created.<br>
</div>
<pre><span id="VALregister_formatter"><span class="keyword">val</span> register_formatter</span> : <code class="type">string -> <a href="BatLogger.html#TYPEformatter">formatter</a> -> unit</code></pre><div class="info ">
<code class="code">register_formatter name formatter</code> registers a named log
formatter. The name is only used for subsequent calls to
identify the formatter via <code class="code">unregister_formatter</code>.<br>
</div>
<pre><span id="VALunregister_formatter"><span class="keyword">val</span> unregister_formatter</span> : <code class="type">string -> unit</code></pre><div class="info ">
<code class="code">unregister_formatter name</code> unregisters a named log formatter.<br>
</div>
<pre><span id="VALmake_std_formatter"><span class="keyword">val</span> make_std_formatter</span> : <code class="type">'a <a href="BatIO.html#TYPEoutput">BatIO.output</a> -> <a href="BatLogger.html#TYPEformatter">formatter</a></code></pre><div class="info ">
<code class="code">make_std_formatter oc</code> constructs a formatter from an output
channel. This formatter will format log events as
tab-separated <code class="code"><keyword>:<value></code> pairs. The resulting
formatter must be registered via <code class="code">register_formatter</code> to be
used when events are raised. This formatter also always outputs
special parameters that describe the event timestamp (an
ISO-8610 timestamp prefixed by <code class="code"><span class="string">"D"</span></code>), the event name (the log
module name followed by a dot, followed by the event name,
prefixed by <code class="code"><span class="string">"E"</span></code>), the log level (prefixed by <code class="code"><span class="string">"L"</span></code>), the
indentation level ( prefixed by <code class="code"><span class="string">"I"</span></code>), followed by any other
event parameters. For example, the log statement:
<p>
<pre class="codepre"><code class="code">log io_log <span class="constructor">INFO</span> (<span class="keyword">fun</span> () <span class="keywordsign">-></span> <span class="string">"connect"</span>, [<span class="string">"ADDR"</span>, addr])</code></pre>
<p>
would produce formatted output like the following when the
<code class="code">io_log</code> <code class="code"><span class="constructor">INFO</span></code> level was enabled:
<p>
<pre class="codepre"><code class="code"><span class="constructor">D</span>:2009-01-26<span class="constructor">T00</span>:47:45.033329<span class="constructor">Z</span> <span class="constructor">E</span>:io.connect <span class="constructor">L</span>:<span class="constructor">INFO</span> <span class="constructor">I</span>:1 <span class="constructor">ADDR</span>:localhost:8080</code></pre><br>
</div>
<pre><span id="VALstderr_formatter"><span class="keyword">val</span> stderr_formatter</span> : <code class="type"><a href="BatLogger.html#TYPEformatter">formatter</a></code></pre><div class="info ">
<code class="code">stderr_formatter</code> is a standard formatter that outputs log
events to stderr using the same format as
<code class="code">make_std_formatter</code>. The resulting formatter must be
registered via <code class="code">register_formatter</code> or supplied to <code class="code">init</code> or
<code class="code">init_from_string</code> to be used when events are raised.<br>
</div>
<pre><span id="VALnull_formatter"><span class="keyword">val</span> null_formatter</span> : <code class="type"><a href="BatLogger.html#TYPEformatter">formatter</a></code></pre><div class="info ">
<code class="code">null_formatter</code> is a formatter that does not output any
events, but simply discards them.<br>
</div>
<pre><span id="VALmake_dbg_formatter"><span class="keyword">val</span> make_dbg_formatter</span> : <code class="type">'a <a href="BatIO.html#TYPEoutput">BatIO.output</a> -> <a href="BatLogger.html#TYPEformatter">formatter</a></code></pre><div class="info ">
<code class="code">make_dbg_formatter oc</code> constructs a debug formatter from an
output channel. The debug formatter outputs simplified format
that is easier to read for debugging purposes and displays
indentation level. E.g.:
<p>
<pre class="codepre"><code class="code"> with_log io_log <span class="constructor">DEBUG</span> (<span class="keyword">fun</span> () <span class="keywordsign">-></span> <span class="string">"listener"</span> [<span class="string">"ADDR"</span>, addr])<br>
accept_connections <span class="comment">(* calls other log statements *)</span><br>
</code></pre>
<p>
would produce formatted output like the following when the <code class="code">io_log</code>
<code class="code"><span class="constructor">DEBUG</span></code> level was enabled:
<p>
<pre class="codepre"><code class="code"> <span class="keywordsign">#</span><span class="keywordsign">#</span><span class="keywordsign">#</span> io.listener <span class="constructor">ADDR</span>:localhost:8080 [<span class="constructor">DEBUG</span>]<br>
<span class="keywordsign">#</span><span class="keywordsign">#</span><span class="keywordsign">#</span> <span class="keywordsign">|</span> io.connected <span class="constructor">CLIENT_ADDR</span>:192.168.0.23:28303 [<span class="constructor">DEBUG</span>]<br>
<span class="keywordsign">#</span><span class="keywordsign">#</span><span class="keywordsign">#</span> <span class="keywordsign">|</span> io.disconnected <span class="constructor">CLIENT_ADDR</span>:192.168.0.23:28303 [<span class="constructor">DEBUG</span>]<br>
...<br>
<span class="keywordsign">#</span><span class="keywordsign">#</span><span class="keywordsign">#</span> io.listener <span class="constructor">ADDR</span>:localhost:8080 <span class="constructor">RESULT</span>:- [<span class="constructor">DEBUG</span>]<br>
</code></pre><br>
</div>
<pre><span id="VALdbg_formatter"><span class="keyword">val</span> dbg_formatter</span> : <code class="type"><a href="BatLogger.html#TYPEformatter">formatter</a></code></pre><div class="info ">
<code class="code">dbg_formatter</code> is a debug formatter that outputs log events to
stderr using the same format as <code class="code">make_dbg_formatter</code>. The
resulting formatter must be registered via <code class="code">register_formatter</code>
or supplied to <code class="code">init</code> or <code class="code">init_from_string</code> to be used when
events are raised.<br>
</div>
<br>
<h6 id="6_loggerinitialization">logger initialization</h6><br>
<pre><span id="VALinit"><span class="keyword">val</span> init</span> : <code class="type">(string * <a href="BatLogger.html#TYPElevel">level</a>) list -> <a href="BatLogger.html#TYPEformatter">formatter</a> -> unit</code></pre><div class="info ">
<code class="code">init name_level_list formatter</code> initializes the logging
system enabling the specified levels for each named
logger. The formatter is the initial formatter for any log
events that are output and is registered with the name
"default" (other formatters may be registered by
<code class="code">register_formatter</code>).<br>
</div>
<pre><span id="VALinit_from_string"><span class="keyword">val</span> init_from_string</span> : <code class="type">string -> <a href="BatLogger.html#TYPEformatter">formatter</a> -> unit</code></pre><div class="info ">
<code class="code">init_from_string name_level_string formatter</code> initializes the
logging system enabling the specified levels for each named
logger. The string must be a comma separated list of <code class="code"><logger
name>:<level name></code> pairs, e.g. <code class="code"><span class="string">"FOO:ERROR,BAR:WARN"</span></code>. If a
un-prefixed level name is specified, then that becomes the
default log level for all newly created logs, and all currently
created logs are enabled to that level. If the logger does not
yet exist, it is created. The formatter is the initial
formatter for any log events that are output and is registered
with the name "default" (other formatters may be registered by
<code class="code">register_formatter</code>).<br>
</div>
<br>
<h6 id="6_logutilities">log utilities</h6><br>
<pre><span id="VALlevel_of_name"><span class="keyword">val</span> level_of_name</span> : <code class="type">string -> <a href="BatLogger.html#TYPElevel">level</a></code></pre><div class="info ">
<code class="code">level_of_name str</code> returns the <code class="code">level</code> associated with <code class="code">str</code>.<br>
</div>
<pre><span id="VALname_of_level"><span class="keyword">val</span> name_of_level</span> : <code class="type"><a href="BatLogger.html#TYPElevel">level</a> -> string</code></pre><div class="info ">
<code class="code">name_of_level level</code> returns the name of the specified <code class="code">level</code>.<br>
</div>
<pre><span id="VALformat_timestamp"><span class="keyword">val</span> format_timestamp</span> : <code class="type">'a <a href="BatIO.html#TYPEoutput">BatIO.output</a> -> float -> unit</code></pre><div class="info ">
<code class="code">format_timestamp oc timestamp</code> prints an ISO-8601 formatted
timestamp (extended to specify higher-resolution seconds) to
the output channel, <code class="code">oc</code>.<br>
</div>
</body></html>
