websh/quickref/logging.html (159 lines of code) (raw):

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Logging</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Websh Reference 3.6.0b5"><link rel="up" href="index.html" title="Websh Reference 3.6.0b5"><link rel="prev" href="response_data_handling.html" title="Response data handling"><link rel="next" href="context_handling.html" title="Context handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Logging</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="response_data_handling.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="context_handling.html">Next</a></td></tr></table><hr></div><div class="section" title="Logging"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="logging"></a>Logging</h2></div></div></div><p style="width:90%"> Logging consists of two parts. <span style="font-family:monospace"><span class="command"><strong>web::log</strong></span></span> issues a logging message, while <span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> determine where to send a message. Websh uses a two-step filtering. First, Websh determines whether it should handle a message, or not, using the levels configured with <span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span>. Then, Websh determines which message is to be sent where, using the the additional filters and destinations configured with <span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span>. There is no logging per default. Setting levels with <span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> is mandatory. </p><p style="width:90%"> A filter consists of a tag and a level, separated by a ".". The tag is free text. Typically, it is the name of the application, say "foo". Example: "ws3.debug". Levels are, in order: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><div style="margin-bottom:6">alert</div></li><li class="listitem"><div style="margin-bottom:6">error</div></li><li class="listitem"><div style="margin-bottom:6">warning</div></li><li class="listitem"><div style="margin-bottom:6">info</div></li><li class="listitem"><div style="margin-bottom:6">debug</div></li></ul></div><p style="width:90%"> </p><div class="section" title="web::logdest"><div class="titlepage"><div><div><h3 class="title"><a name="web::logdest"></a><span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> <em class="replaceable"><code>subcommand</code></em> ?<em class="replaceable"><code>options</code></em>? <em class="replaceable"><code>args</code></em></span></div><p style="width:90%"> Subcommands are: <tt>add</tt>, <tt>delete</tt>, <tt>names</tt>, and <tt>levels</tt>. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> <tt>add</tt> ?<span class="optional"><tt><em class="replaceable"><code>options</code></em></tt></span>? <tt><em class="replaceable"><code>level</code></em></tt> <tt><em class="replaceable"><code>plugin</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>plugin-specific options</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Options are: <tt>-maxchar n</tt>, and <tt>-format "format string"</tt>. <code class="literal">-maxchar n</code> truncates the message to a maximum of <code class="literal">n</code> characters. </div><div style="margin-bottom:6"> The format string consists of time format specifications for <code class="function">strftime()</code> plus: <code class="literal">$p</code> (process id), <code class="literal">$t</code> (thread id), <code class="literal">$l</code> (log level), <code class="literal">$n</code> (numerical log level), <code class="literal">$f</code> (log facility), <code class="literal">$m</code> (the message), and <code class="literal">$$</code> (dollar sign). </div><div style="margin-bottom:6"> Default format: <code class="literal">"%x %X [\$p] \$f.\$l: \$m\n"</code> </div><div style="margin-bottom:6"> Known plug-ins are: <tt>file</tt>, <tt>syslog</tt> (Unix only), <tt>command</tt>, <tt>channel</tt>, and <tt>apache</tt> (mod_websh only). <span class="emphasis"><em>Note</em></span>: plug-ins may have indiviudal options (such as <tt>-unbuffered</tt>), see documentation below. </div><div style="margin-bottom:6"> <pre style="background:#bbffbb ; width:75%" class="programlisting"> web::logdest add -maxchar 25 -format "%x %X \$l \$m\n" *.-debug command logTest</pre> </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> <tt>delete</tt> ?<span class="optional"><tt><em class="replaceable"><code>name</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Removes destination <tt>name</tt> from list, or removes all destinations if <tt>name</tt> is omitted. (The special case <code class="literal">-requests</code> to delete all destinations except the one defined from within <span style="font-family:monospace"><span class="command"><strong>web::initializer</strong></span></span> code is only used internally.) </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> <tt><em class="replaceable"><code>names</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns a list of all destination ids that have been set. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> <tt><em class="replaceable"><code>levels</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Lists all destination ids and their actual log levels in a readable format </div></div></dd></dl></div></div><div class="section" title="web::loglevel"><div class="titlepage"><div><div><h3 class="title"><a name="web::loglevel"></a><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::loglevel</code></span> subcommand args</span></div><p style="width:90%"> Subcommands are: <tt>add</tt>, <tt>delete</tt>, <tt>names</tt>, and <tt>levels</tt>. Levels defined using <span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> act as a filter for log messages sent by Websh. Only messages that pass at least one level defined using this command are passed to the log destinations configured using <span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> </p><p style="width:90%"> </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> <tt>add</tt> <tt><em class="replaceable"><code>level</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Adds a level to the list. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> <tt>delete</tt> ?<span class="optional"><tt><em class="replaceable"><code>name</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Removes level <tt>name</tt> from list, or removes all levels if <tt>name</tt> is omitted. (The special case <code class="literal">-requests</code> to delete all levels except the one defined from within <span style="font-family:monospace"><span class="command"><strong>web::initializer</strong></span></span> code is only used internally.) </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> <tt><em class="replaceable"><code>names</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns a list of all level ids that have been set. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> <tt><em class="replaceable"><code>levels</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Lists all level ids and their actual log levels in a readable format. </div></div></dd></dl></div><p style="width:90%"> </p></div><div class="section" title="web::log"><div class="titlepage"><div><div><h3 class="title"><a name="web::log"></a><span style="font-family:monospace"><span class="command"><strong>web::log</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::log</code></span> <em class="replaceable"><code>level</code></em> <em class="replaceable"><code>msg</code></em></span></div><p style="width:90%"> Issues a log message. It is possible, should the user so desire, to have the <span style="font-family:monospace"><span class="command"><strong>web::log</strong></span></span> run <span style="font-family:monospace"><span class="command"><strong>subst</strong></span></span> on its arguments. This behaviour is turned off by default, and can be turned on by doing: </p><pre style="background:#bbffbb ; width:75%" class="programlisting">web::config logsubst 1</pre><p style="width:90%">. </p></div><div class="section" title="Log plug-ins"><div class="titlepage"><div><div><h3 class="title"><a name="log_plug-ins"></a>Log plug-ins</h3></div></div></div><div class="section" title="File"><div class="titlepage"><div><div><h4 class="title"><a name="file"></a>File</h4></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> add <em class="replaceable"><code>destination</code></em>.-<em class="replaceable"><code>level</code></em> file ?<em class="replaceable"><code>options</code></em>? <em class="replaceable"><code>filename</code></em></span></div><p style="width:90%"> Option is: <tt>-unbuffered</tt> </p><p style="width:90%"> Log messages are sent to the file <tt>filename</tt>, which is opened in append mode at the time of this call and stays open until this destination is deleted. This is either at the end of the request (mod_websh) or when the interpreter is deleted. </p><p style="width:90%"> The file opened using the permissions configured with <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>. Default: 0644. </p></div><div class="section" title="Syslog"><div class="titlepage"><div><div><h4 class="title"><a name="syslog"></a>Syslog</h4></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> add *.-debug syslog ?<em class="replaceable"><code>level</code></em>?</span></div><p style="width:90%"> See the man page for syslog for levels on your system. Typical: 10. Available under Unix only. </p></div><div class="section" title="Command"><div class="titlepage"><div><div><h4 class="title"><a name="command"></a>Command</h4></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> add *.-debug command <em class="replaceable"><code>cmdName</code></em></span></div><p style="width:90%"> </p><p style="width:90%"> The log message is sent to a Tcl command taking the message as an argument. E.g. </p><pre style="background:#bbffbb ; width:75%" class="programlisting"> % proc logCommand {msg} { puts "---- here comes the message ----" puts -nonewline $msg puts "----- that was the message -----" } % % web::loglevel add *.-debug loglevel0 % web::logdest add *.-debug command logCommand logdest0 % web::log debug "a log message" ---- here comes the message ---- 10/28/05 13:44:26 [20596] user.debug: a log message ----- that was the message ----- % </pre><p style="width:90%"> </p></div><div class="section" title="Channel"><div class="titlepage"><div><div><h4 class="title"><a name="channel"></a>Channel</h4></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> add *.-debug channel ?<em class="replaceable"><code>options</code></em>? <em class="replaceable"><code>channel</code></em></span></div><p style="width:90%"> Option is: <tt>-unbuffered</tt> </p><p style="width:90%"> Writes the message to the Tcl channel <tt>channel</tt>. </p></div><div class="section" title="Apache"><div class="titlepage"><div><div><h4 class="title"><a name="apache"></a>Apache</h4></div></div></div><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::logdest</code></span> add *.-debug apache </span></div><p style="width:90%"> Sends the message to the Apache ErrorLog file. Available within mod_websh only. </p></div><div class="section"><div class="titlepage"></div><div class="example"><a name="id2739068"></a><p class="title"><b>Example�11.�<span style="font-family:monospace"><span class="command">web::log</span></span>, <span style="font-family:monospace"><span class="command">web::loglevel</span></span>, and <span style="font-family:monospace"><span class="command">web::logdest</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> % web::loglevel add *.-debug loglevel0 % web::logdest add *.-debug channel stdout logdest0 % web::log info {Websh is cool} 03/01/00 00:00:00 [111] user.info: Websh is cool % web::logdest delete % web::logdest add -format "--&gt; \$m\n" *.-debug channel stdout logdest0 % web::log info {Websh is cool} --&gt; Websh is cool % web::logdest delete % web::logdest add -maxchar 5 *.-debug channel stdout % web::log info {Websh is cool} 03/01/00 00:00:00 [111] user.info: Websh % </pre></div></div><br class="example-break"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="response_data_handling.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="context_handling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Response data handling�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Context handling</td></tr></table></div></body></html>