<html><head>

        <META http-equiv="content-type" content="text/html; charset=utf-8">

        <title>std.logging</title>

        </head><body>

        <h1>std.logging</h1>

        <!-- Generated by Ddoc from src/std/logging.d -->

Implements application level logging mechanism.

<br><br>

This module defines a set of functions useful for many common logging tasks.  The module must be initialized (ideally in single threaded mode) by calling initializeLogging. Messages of different severity level are logged by calling the template functions log and logf. Verbose messages can be logged by calling the template functions  vlog and vlogf.

<br><br>

<b>Examples:</b><br>

<pre class="d_code"><font color=blue>import</font> std.<u>logging</u>;

<font color=blue>int</font> main(string[] args)

{

   initializeLogging(ActorLogger.getCreator(args[0]));

   <font color=green>// ...

</font>   logf(Level.info, <font color=red>"Log message from %s"</font>, args[0]);

}

</pre>

<br><br>

<b>Note:</b><br>

Logging can be disable at compile time by defining the LOGGING_DISABLED version.

<br><br>

<dl><dt><big>enum <u>Level</u>;

</big></dt>

<dd>Defines the severity levels supported by the logging library.

<br><br>

Logging messages of severity level <u>Level</u>.fatal will also cause the program to halt. Messages of a given severity will be written in the log file of that severity and the log files of lower severity.<br><br>

<dl><dt><big><u>fatal</u><br><u>error</u><br><u>warning</u><br><u>info</u></big></dt>

<dd><br><br>

</dd>

</dl>

</dd>

<dt><big>void <u>initializeLogging</u>(shared(Logger) delegate() <i>logCreator</i>, LogConfig <i>logConfig</i> = LogConfig(null,cast(Level)1,null,null));

</big></dt>

<dd>Initializes the logging infrastructure.

<br><br>

This function must be called ounce before calling any of the logging functions.

<br><br>

<b>Params:</b><br>

<table><tr><td>shared(Logger) delegate() <i>logCreator</i></td>

<td>Delegate which creates the Logger used by the module.</td></tr>

<tr><td>LogConfig <i>logConfig</i></td>

<td>Module configuration object.</td></tr>

</table><br>

<b>See Also:</b><br>

LogConfig<br><br>

</dd>

<dt><big>void <u>logf</u>(string file = __FILE__, int line = __LINE__, T...)(Level <i>level</i>, lazy T <i>args</i>);

</big></dt>

<dd>Logs a formatted message.

<br><br>

Logs a formatted message if level is of higher or equal severity as that specified in the LogConfig object passed to initializeLogging.

<br><br>

The first parameter in <i>args</i> will be used as the format string. See <b><u>std.format.formattedWrite</u></b> for a description of the format string.<br><br>

</dd>

<dt><big>void <u>log</u>(string file = __FILE__, int line = __LINE__, T...)(Level <i>level</i>, lazy T <i>args</i>);

</big></dt>

<dd>Logs a message

<br><br>

Logs a message if <i>level</i> is of higher or equal severity as that specified in the <b><u>LogConfig</u></b> object passed to <b><u>initializeLogging</u></b>.<br><br>

</dd>

<dt><big>void <u>vlogf</u>(string file = __FILE__, int line = __LINE__, T...)(uint <i>level</i>, lazy T <i>args</i>);

</big></dt>

<dd>Logs a formatted verbose message

<br><br>

Logs a formatted verbose message if the file and level matches one of the entries specified in the vLogConfigs property of the LogConfig object passed to initializeLogging.

<br><br>

The first parameter in <i>args</i> will be used as the format string. See <b><u>std.format.formattedWrite</u></b> for a description of the format string.<br><br>

</dd>

<dt><big>void <u>vlog</u>(string file = __FILE__, int line = __LINE__, T...)(uint <i>level</i>, lazy T <i>args</i>);

</big></dt>

<dd>Logs a verbose message

<br><br>

Logs a verbose message if the <b>file</b> and <i>level</i> matches one of the entries specified in the <b><u>vLogConfigs</u></b> property of the <b><u>LogConfig</u></b> object passed to <b><u>initializeLogging</u></b>.<br><br>

</dd>

<dt><big>struct <u>LogConfig</u>;

</big></dt>

<dd>Configuration struct for the module.

<br><br>

This object must be used to configure the logging module at initialization.  All the properties are optional and can be use to configure the framework's behavior.<br><br>

<dl><dt><big>void <u>level</u>(Level <u>level</u>);

</big></dt>

<dd>Level to use for logging.

<br><br>

The logging framework will only log messages with a severity greater than or equal to the value of this property.<br><br>

</dd>

<dt><big>void <u>vLogConfigs</u>(VLogConfig[] <u>vLogConfigs</u>);

</big></dt>

<dd>Verbose logging configuration.

<br><br>

Messages logged by using the template function vlog or vlogf will be filtered by comparing against each VLogConfig until a match is found. If no match is found the verbose message will not get logged.

<br><br>

<b>See Also:</b><br>

VLogConfig<br><br>

</dd>

<dt><big>void <u>fatalHandler</u>(void function() <u>fatalHandler</u>);

</big></dt>

<dd>Function pointer for handling log message with a severity of fatal.

<br><br>

This function will be called by the thread trying to log a fatal message by using <b><u>log</u></b> or <b><u>logf</u></b>. The function <i><u>fatalHandler</u></i> should not return; otherwise the framework will assert(<b>false</b>).<br><br>

</dd>

</dl>

</dd>

<dt><big>struct <u>VLogConfig</u>;

</big></dt>

<dd>Structure for configuring verbose logging.

<br><br>

This structure is used to control verbose logging on a per module basis. A verbose message with level <i>x</i> will get logged at severity level Level.info if there is a <u>VLogConfig</u> entry that matches to the source file and the verbose level of that entry is greater than or equal to <i>x</i>.<br><br>

<dl><dt><big>static VLogConfig[] <u>create</u>(string <i>config</i>);

</big></dt>

<dd>Creates an array of VLogConfig based on a configuration string.

<br><br>

The format of the configuration string is as follow "[pattern]=[level],...", where [pattern] may contain any character allowed in a file name and [level] must be convertible to an positive integer (greater than or equal to zero). If [pattern] contains a '*' then it must be at the start or the end. If [pattern] ends with a '*' then it will match any source file name that starts with the rest of [pattern]. If [pattern] starts with a '*' then it will match any source file name that ends with a the rest of [pattern].

<br><br>

For every <b>[pattern]</b>=<b>[level]</b> in the configuration string a <b><u>VLogConfig</u></b> will be created and included in the returned array.<br><br>

</dd>

</dl>

</dd>

<dt><big>abstract interface <u>Logger</u>;

</big></dt>

<dd>Extension point for the module.<br><br>

<dl><dt><big>abstract void <u>log</u>(Level <i>level</i>, string <i>msg</i>);

</big></dt>

<dd>Logs a message.

<br><br>

The method is called by the logging module whenever it decides that a message should be logged. It is recommend that the implementation of this method doesn't perform any filtering based on level since at this point all configured filters were applied.

<br><br>

The method is allow to return immediately without persisting the message.<br><br>

</dd>

<dt><big>abstract void <u>flush</u>();

</big></dt>

<dd>Flushes pending log operations.

<br><br>

The method is called by the logging framework whenever it requires that the persistence of all previous log messages. For example the method is called when the client logs a fatal message.

<br><br>

The method must not return until all pending log operations complete.<br><br>

</dd>

</dl>

</dd>

<dt><big>class <u>ActorLogger</u>: std.logging.Logger;

</big></dt>

<dd>Implements an actor based logging backend.

<br><br>

Log messages are sent to a logging thread which is responsible for persisting log messages. Messages of a given severity will be written in the log file of that severity and in the log files of lower severity. The file names of the log files created will follow the following pattern "<b>[name]</b>.log.<b>[level]</b>.<b>[time]</b>". The string <b>[name]</b> is the parameter <i>name</i> passed to <b><u>getCreator</u></b>. The string <b>[time]</b> is the time when the logger was created. The string <b>[level]</b> is the severity of the log file. A file for severity level 'x' will contain all log messages of greater or equal severity.<br><br>

<dl><dt><big>static shared(Logger) delegate() <u>getCreator</u>(string <i>name</i>);

</big></dt>

<dd>Returns a delegate for creating an ActorLogger.

<br><br>

The method will always return a different delegate but a given delegate will always return the same ActorLogger.

<br><br>

<b>Params:</b><br>

<table><tr><td>string <i>name</i></td>

<td>Name to use when creating log files</td></tr>

</table><br>

</dd>

</dl>

</dd>

</dl>

        <hr><small>Page generated by <a href="http://www.digitalmars.com/d/2.0/ddoc.html">Ddoc</a>. </small>

        </body></html>