<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Falcon Feathers - The Standard Modules Reference.</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Module Logging support </h1>
<p class="faldoc_brief">Multithread enabled logging facility. </p>
<p class="faldoc_text"><p class="faldoc_text"> The <b>logging</b> module offers a very advanced facility for logging application messages to various device. </p>
<p class="faldoc_text">It is based on a Area/Channel architecture. </p>
<p class="faldoc_text"> The <a href="./class_LogArea.html">LogArea</a> class provides a logical subdivision of the semantic meaning of a log entry; sending a log to a certain area means that the entry has as certain meaning and function in the application architecture. For example, an application can have "security", "trace" and "status" areas; security area is meant to log informations and errors concerning security policy operations (login, logout, password change and so on). The status area may be dedicated to log internal operation status, as, for example failures in opening a database, performed queries or amount of records changed. The trace area may be specifically dedicated to debug or deep audit. </p>
<p class="faldoc_text">Channels are physical or logical device managers, receiving log requests and delivering them on final media, rendered as their internal rules dictate. </p>
<p class="faldoc_text">The user application posts a log entry to an area, and the area dispatches the entry to all the channels that are registered with. Channels can be registered with multiple areas, and they can be dynamically added to new areas or removed from areas they are currently connected to. </p>
<p class="faldoc_text">Each message it's associated with a "level", also called severity, which determines how important the log entry is. Channels can be configured to perform log operations only to messages having at least a minimum level, that is, severe at least as a certain level. Lower level entries are ignored by the channel. </p>
<p class="faldoc_text"> The current logger module provides one default area, called <a href="./object_GeneralLog.html">GeneralLog</a>, and three log channel classes: </p>
<ul>
<li><a href="./class_LogChannelStream.html">LogChannelStream</a>- writes entries on a Falcon stream separately opened. </li><li><a href="./class_LogChannelSyslog.html">LogChannelSyslog</a>- sends entries to the system log facility. On POSIX systems, logs are sent to the Syslog daemon, while on MS-Windows systems they are sent to the Event Logger. </li><li><a href="./class_LogChannelFiles.html">LogChannelFiles</a>- Writes entries to a local file, and swaps or rotates the log file on need. </li>
</ul>
<a name="feather_logging_performance"><h2 class="faldoc_section">Performance considerations </h2></a>
<p class="faldoc_text">The logger module is thought to perform the final part of the log operations in the most efficient way possible. Each channel performs the final log rendering and the dispatching on the underlying media on a separate thread, so the operation of generating a log for a certain channel is virtually non-blocking and relatively fast. </p>
<p class="faldoc_text">Log operations involving fixed parameters are nearly no-ops, as in the following example: </p>
<pre class="faldoc_code">
glog( 2000, "A very low priority level, unlikely to be ever logged" )
</pre>
<p class="faldoc_text"> Although there is a cost in calling the <a href="./functions.html#glog">glog</a> function (logging on the GenericLog area), a modern computer can perform such calls in the order of about five millions per second. </p>
<p class="faldoc_text">However, consider the nature of falcon as a Virtual Machine interpreted scripting language. Creating a complete log message may be an heavy operation by itself; for example: </p>
<pre class="faldoc_code">
rendered = ""
for person in visitors
rendered += person
formiddle: rendered += ", "
end
GenericLog.log( LOGI, "Today we had " + visitors.len()
+ " visitors, named " + rendered )
</pre>
<p class="faldoc_text">In this case, creating the "rendered" log-friendly representation of the visitors is quite slow, and so it's creating the log entry in the log() call. </p>
<p class="faldoc_text">If there isn't any channel registered with the GenericLog area, the message will be discarded, but the heaviest part of the job has already be done, and in waste. </p>
<p class="faldoc_text">In case logs are heavy and frequent, it is useful to wrap log generation of the most intensive entries in runtime checks, or better, compile time directives that prevent calling logs when the application knows they are actually not wanted in the current context. </p>
<p class="faldoc_text"> The <a href="./class_LogArea.html#minlog">LogArea.minlog</a> method returns the minimum log level that is accepted by a registered channel (the <a href="./functions.html#gminlog">gminlog</a> function operates on the GeneralLog area), providing a simple way to prevent logging useless data in runtime: </p>
<pre class="faldoc_code">
// want debug?
if LOGD <= gminlog()
// prepare an heavy log...
glogd( "Debug heavy log: " + ... )
end
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Log levels appares in inverse order of severity; so LOGF (fatal) is a level numerically less than LOGD (debug). </p>
<a name="feather_logging_service"><h2 class="faldoc_section">Service model </h2></a>
<p class="faldoc_text">Falcon logging module is exposed to embedding application as a "service". This means that embedding applications using the Falcon engine can dynamically load the logging module and access the same functionalities available to Falcon scripts directly from a C++ SDK interface. </p>
<p class="faldoc_text">Actually, LogChannel class hierarchy is directly visible in the scripts; so embedding application could create log areas or ever log channels pointing back to them, or sharing channels with the scripts to write joint logs (maybe from different areas). </p>
<a name="feather_logging_extending"><h2 class="faldoc_section">Extending classes. </h2></a>
<p class="faldoc_text"> All the classes in this module are highly reflective, and operate on the inner C++ classes for performance reason. Because of this, overloading a LogChannel class and overloading its <b>log</b> method won't cause the LogArea to call back the new log method provided by the script; the underlying C++ log method will still be called. </p>
<p class="faldoc_text">However, it is legal to extend the LogChannel classes; the overloaded log method can be used directly by the script even if it will be ignored by LogArea instances. </p>
</p>
<h2 class="faldoc_title">Classes</h2>
<table class="faldoc_list">
<tr><td class="faldoc_funcname"><a href="./class_LogArea.html">LogArea</a></td><td class="faldoc_funcbrief">Collection of log channels. </td></tr>
<tr><td class="faldoc_funcname"><a href="./class_LogChannel.html">LogChannel</a></td><td class="faldoc_funcbrief">Abstract class receiving log requests from log areas. </td></tr>
<tr><td class="faldoc_funcname"><a href="./class_LogChannelFiles.html">LogChannelFiles</a></td><td class="faldoc_funcbrief">Log channel sending logs to a set of (possibly) rotating local files. </td></tr>
<tr><td class="faldoc_funcname"><a href="./class_LogChannelStream.html">LogChannelStream</a></td><td class="faldoc_funcbrief">Logs on an open stream. </td></tr>
<tr><td class="faldoc_funcname"><a href="./class_LogChannelSyslog.html">LogChannelSyslog</a></td><td class="faldoc_funcbrief">Logs on the local system logger facility. </td></tr>
</table>
<h2 class="faldoc_title">All functions</h2>
<table class="faldoc_list">
<tr><td class="faldoc_funcname"><a href="./functions.html#glog">glog</a></td><td class="faldoc_funcbrief">Shortcut to log on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#glogd">glogd</a></td><td class="faldoc_funcbrief">Shortcut to log a debug message on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#gloge">gloge</a></td><td class="faldoc_funcbrief">Shortcut to log an error on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#glogf">glogf</a></td><td class="faldoc_funcbrief">Shortcut to log a fatal error on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#glogi">glogi</a></td><td class="faldoc_funcbrief">Shortcut to log an information message on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#glogw">glogw</a></td><td class="faldoc_funcbrief">Shortcut to log a warning on the generic area. </td></tr>
<tr><td class="faldoc_funcname"><a href="./functions.html#gminlog">gminlog</a></td><td class="faldoc_funcbrief">Determines what is the minimum log severity active on the GeneircLog area. </td></tr>
</table>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
