[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
BKNR Commits
bknr at bknr.net
Wed Feb 18 20:28:27 UTC 2009
Revision: 4281
Author: edi
URL: http://bknr.net/trac/changeset/4281
Document logging
U trunk/thirdparty/hunchentoot/acceptor.lisp
U trunk/thirdparty/hunchentoot/doc/index.xml
U trunk/thirdparty/hunchentoot/log.lisp
U trunk/thirdparty/hunchentoot/request.lisp
U trunk/thirdparty/hunchentoot/specials.lisp
Modified: trunk/thirdparty/hunchentoot/acceptor.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/acceptor.lisp 2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/acceptor.lisp 2009-02-18 20:28:27 UTC (rev 4281)
@@ -139,9 +139,9 @@
:accessor acceptor-message-logger
:documentation "Designator for a function to call
to log messages by the acceptor. It must accept a severity level for
-the message, which will be one of :NOTICE, :INFO, or :WARNING, a
-format string and an arbitary number of formatting arguments. This
-slot defaults to a function which writes to the file determined by
+the message, which will be one of :ERROR, :INFO, or :WARNING, a format
+string and an arbitary number of formatting arguments. This slot
+defaults to a function which writes to the file determined by
*MESSAGE-LOG-PATHNAME* \(unless that value is NIL).
If the value of this slot is NIL, message logging is turned off for
Modified: trunk/thirdparty/hunchentoot/doc/index.xml
===================================================================
--- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-18 20:28:27 UTC (rev 4281)
@@ -384,6 +384,11 @@
</clix:description>
</clix:function>
+ <clix:special-variable name='*acceptor*'>
+ <clix:description>The current ACCEPTOR object in the context of a request.
+ </clix:description>
+ </clix:special-variable>
+
<clix:readers generic='true'>
<clix:listed-reader name='acceptor-address'>
<clix:lambda-list>acceptor
@@ -450,10 +455,10 @@
</clix:returns>
</clix:listed-accessor>
- <clix:listed-accessor name='acceptor-handler-selector'>
+ <clix:listed-accessor name='acceptor-request-dispatcher'>
<clix:lambda-list>acceptor
</clix:lambda-list>
- <clix:returns>handler-selector
+ <clix:returns>request-dispatcher
</clix:returns>
</clix:listed-accessor>
@@ -600,11 +605,10 @@
<clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket handle or a usocket socket
stream object in <clix:arg>socket</clix:arg>. It reads the request headers, sets up the
<a href="#requests">request</a> and <a href="#replies">reply</a>
-objects, and hands over to (the unexported
-function) <code>PROCESS-REQUEST</code> which selects and calls a
-handler for the request and sends its reply to the client. This is
-done in a loop until the stream has to be closed or until a connection
-timeout occurs.
+objects, and hands over to <clix:ref>PROCESS-REQUEST</clix:ref> which
+selects and calls a handler for the request and sends its reply to the
+client. This is done in a loop until the stream has to be closed or
+until a connection timeout occurs.
<p>
It is probably not a good idea to re-implement this method until you
@@ -1102,6 +1106,90 @@
</clix:subchapter>
<clix:subchapter name="logging" title="Logging">
+
+By default, Hunchentoot logs accesses and errors to two separate files
+in the file system, but <em>only</em> if the special variables
+<clix:ref>*MESSAGE-LOG-PATHNAME*</clix:ref> and <clix:ref>*ACCESS-LOG-PATHNAME*</clix:ref> are set accordingly.
+Access logging is done in a format similar to what
+the Apache web server can write so that logfile analysis using
+standard tools is possible. Errors during request processing are
+logged to a separate file.
+<p>
+The standard logging mechanism is deliberately simple and slow. The
+log files are opened for each log entry and closed again after
+writing, and access to them is protected by a global lock. If you
+want more sophisticated logging, use
+the <a href="#acceptor-access-logger"><code>:access-logger</code></a>
+and <a href="#acceptor-message-logger"><code>:message-logger</code></a>
+initargs of the acceptor class to establish your own logging
+functions. See the docstrings of the corresponding slots for more
+information.
+</p>
+<p>
+Errors happening within a <a href="#handlers">handler</a> which are
+not caught by the handler itself are handled by Hunchentoot by logging
+them to the log file.
+</p>
+
+ <clix:function name='log-message'>
+ <clix:lambda-list>log-level format-string
+ <clix:lkw>rest
+ </clix:lkw> format-arguments
+ </clix:lambda-list>
+ <clix:returns>result
+ </clix:returns>
+ <clix:description>Convenience function which calls the message
+logger of the current acceptor (if there is one) with the same
+arguments it accepts. Returns <code>NIL</code> if there is no message
+logger or whatever the message logger returns.
+<p>
+This is the function which Hunchentoot itself uses to log errors it
+catches during request processing.
+</p>
+ </clix:description>
+ </clix:function>
+
+ <clix:special-variable name='*message-log-pathname*'>
+ <clix:description>
+A designator for the pathname of the message log file used by the
+<a href="#logging">default message logger</a>. The initial value is <code>NIL</code> which
+means that <em>nothing</em> will be logged!
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*access-log-pathname*'>
+ <clix:description>
+A designator for the pathname of the access log file used by the
+<a href="#logging">default access logger</a>. The initial value is <code>NIL</code> which
+means that <em>nothing</em> will be logged!
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*log-lisp-errors-p*'>
+ <clix:description>Whether Lisp errors in request handlers should be logged.
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*log-lisp-warnings-p*'>
+ <clix:description>Whether Lisp warnings in request handlers should be logged.
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*lisp-errors-log-level*'>
+ <clix:description>Log level for Lisp errors. Should be one
+of <code>:ERROR</code> (the default), <code>:WARNING</code>,
+or <code>:INFO</code>.
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*lisp-warnings-log-level*'>
+ <clix:description>Log level for Lisp warnings.
+Should be one of <code>:ERROR</code>, <code>:WARNING</code>
+(the default), or <code>:INFO</code>.
+ </clix:description>
+ </clix:special-variable>
+
+
</clix:subchapter>
<clix:subchapter name="conditions" title="Conditions">
@@ -1113,16 +1201,7 @@
</clix:chapter>
<clix:chapter name='dict' title='The HUNCHENTOOT dictionary'>
- <clix:special-variable name='*acceptor*'>
- <clix:description>The current ACCEPTOR object.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*access-log-pathname*'>
- <clix:description>A designator for the pathname of the access log file used by the
-LOG-ACCESS-TO-FILE function. The initial value is NIL which means
-that nothingq will be logged.
- </clix:description>
- </clix:special-variable>
+
<clix:special-variable name='*approved-return-codes*'>
<clix:description>A list of return codes the server should not treat as an error -
see *HANDLE-HTTP-ERRORS-P*.
@@ -1202,28 +1281,7 @@
<clix:description>The external format used to compute the REQUEST object.
</clix:description>
</clix:special-variable>
- <clix:special-variable name='*lisp-errors-log-level*'>
- <clix:description>Log level for Lisp errors.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*lisp-warnings-log-level*'>
- <clix:description>Log level for Lisp warnings.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*log-lisp-errors-p*'>
- <clix:description>Whether Lisp errors should be logged.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*log-lisp-warnings-p*'>
- <clix:description>Whether Lisp warnings should be logged.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*message-log-pathname*'>
- <clix:description>A designator for the pathname of the message log file used by the
-LOG-MESSAGE-TO-FILE function. The initial value is NIL which means
-that nothing will be logged.
- </clix:description>
- </clix:special-variable>
+
<clix:special-variable name='*methods-for-post-parameters*'>
<clix:description>A list of the request method types (as keywords) for which
Hunchentoot will try to compute POST-PARAMETERS.
@@ -2018,17 +2076,6 @@
</clix:condition>
- <clix:function name='log-message'>
- <clix:lambda-list>log-level format-string
- <clix:lkw>rest
- </clix:lkw> format-arguments
- </clix:lambda-list>
- <clix:returns>result
- </clix:returns>
- <clix:description>Convenience function which calls the message logger of the current
-acceptor (if there is one) with the same arguments it accepts.
- </clix:description>
- </clix:function>
<clix:function name='mime-type'>
<clix:lambda-list>pathspec
</clix:lambda-list>
@@ -2548,6 +2595,33 @@
name doesn't exist, it is created.
</clix:description>
</clix:function>
+
+
+ <clix:function generic='true' name='process-request'>
+ <clix:lambda-list>request
+ </clix:lambda-list>
+ <clix:returns>nil
+ </clix:returns>
+ <clix:description>
+This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
+after the incoming headers have been read. It selects and calls a
+handler and sends the output of this handler to the client. It also
+sets up simple error handling for the request handler. Note
+that <clix:ref>PROCESS-CONNECTION</clix:ref> is called once per
+connection and loops in case of a persistent connection
+while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew for each
+request.
+<p>
+Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this might be a good
+place to introduce around methods which bind special variables or do
+other interesting things.
+</p>
+<p>
+The return value of this function is ignored.
+</p>
+ </clix:description>
+ </clix:function>
+
</clix:chapter>
<clix:chapter name="testing" title="Testing">
Modified: trunk/thirdparty/hunchentoot/log.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/log.lisp 2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/log.lisp 2009-02-18 20:28:27 UTC (rev 4281)
@@ -30,6 +30,11 @@
(in-package :hunchentoot)
(defmacro with-log-file ((stream-var pathname lock) &body body)
+ "Helper macro which executes BODY only if PATHNAME \(which is
+evaluated) is not NIL. In this case, the file designated by PATHNAME
+is opened for writing \(appending) and created if it doesn't exist.
+STREAM-VAR is then bound to a flexi stream which can be used to write
+characters to the file in UTF-8 format."
(with-unique-names (binary-stream)
(with-rebinding (pathname)
`(when ,pathname
@@ -77,7 +82,13 @@
(defun log-message (log-level format-string &rest format-arguments)
"Convenience function which calls the message logger of the current
-acceptor \(if there is one) with the same arguments it accepts."
+acceptor \(if there is one) with the same arguments it accepts.
+
+Returns NIL if there is no message logger or whatever the message
+logger returns.
+
+This is the function which Hunchentoot itself uses to log errors it
+catches during request processing."
(when-let (message-logger (acceptor-message-logger *acceptor*))
(apply message-logger log-level format-string format-arguments)))
Modified: trunk/thirdparty/hunchentoot/request.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/request.lisp 2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/request.lisp 2009-02-18 20:28:27 UTC (rev 4281)
@@ -99,10 +99,10 @@
(:documentation "This function is called by PROCESS-CONNECTION after
the incoming headers have been read. It selects and calls a handler
and sends the output of this handler to the client using START-OUTPUT.
-It also sets up simple error handling for the actual request handler.
-Note that PROCESS-CONNECTION is called once per connection and loops
-in case of a persistent connection while PROCESS-REQUEST is called
-anew for each request.
+It also sets up simple error handling for the request handler. Note
+that PROCESS-CONNECTION is called once per connection and loops in
+case of a persistent connection while PROCESS-REQUEST is called anew
+for each request.
Like PROCESS-CONNECTION, this might be a good place to introduce
around methods which bind special variables or do other interesting
Modified: trunk/thirdparty/hunchentoot/specials.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/specials.lisp 2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/specials.lisp 2009-02-18 20:28:27 UTC (rev 4281)
@@ -194,19 +194,21 @@
purposes.")
(defvar *show-lisp-errors-p* nil
- "Whether Lisp errors should be shown in HTML output.")
+ "Whether Lisp errors in request handlers should be shown in HTML output.")
(defvar *log-lisp-errors-p* t
- "Whether Lisp errors should be logged.")
+ "Whether Lisp errors in request handlers should be logged.")
(defvar *log-lisp-warnings-p* t
- "Whether Lisp warnings should be logged.")
+ "Whether Lisp warnings in request handlers should be logged.")
(defvar *lisp-errors-log-level* :error
- "Log level for Lisp errors.")
+ "Log level for Lisp errors. Should be one of :ERROR \(the default),
+:WARNING, or :INFO.")
(defvar *lisp-warnings-log-level* :warning
- "Log level for Lisp warnings.")
+ "Log level for Lisp warnings. Should be one of :ERROR, :WARNING
+\(the default), or :INFO.")
(defvar *message-log-pathname* nil
"A designator for the pathname of the message log file used by the
@@ -216,7 +218,7 @@
(defvar *access-log-pathname* nil
"A designator for the pathname of the access log file used by the
LOG-ACCESS-TO-FILE function. The initial value is NIL which means
-that nothingq will be logged.")
+that nothing will be logged.")
(defvar *message-log-lock* (make-lock "global-message-log-lock")
"A global lock to prevent concurrent access to the log file
More information about the Bknr-cvs
mailing list