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:descriptionThe 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-listacceptor @@ -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-listacceptor </clix:lambda-list> - clix:returnshandler-selector + clix:returnsrequest-dispatcher </clix:returns> </clix:listed-accessor>
@@ -600,11 +605,10 @@ clix:refACCEPTOR</clix:ref> object and a LispWorks socket handle or a usocket socket stream object in clix:argsocket</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:refPROCESS-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-listlog-level format-string + clix:lkwrest + </clix:lkw> format-arguments + </clix:lambda-list> + clix:returnsresult + </clix:returns> + clix:descriptionConvenience 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:descriptionWhether Lisp errors in request handlers should be logged. + </clix:description> + </clix:special-variable> + + <clix:special-variable name='*log-lisp-warnings-p*'> + clix:descriptionWhether Lisp warnings in request handlers should be logged. + </clix:description> + </clix:special-variable> + + <clix:special-variable name='*lisp-errors-log-level*'> + clix:descriptionLog 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:descriptionLog 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:descriptionThe current ACCEPTOR object. - </clix:description> - </clix:special-variable> - <clix:special-variable name='*access-log-pathname*'> - clix:descriptionA 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:descriptionA list of return codes the server should not treat as an error - see *HANDLE-HTTP-ERRORS-P*. @@ -1202,28 +1281,7 @@ clix:descriptionThe external format used to compute the REQUEST object. </clix:description> </clix:special-variable> - <clix:special-variable name='*lisp-errors-log-level*'> - clix:descriptionLog level for Lisp errors. - </clix:description> - </clix:special-variable> - <clix:special-variable name='*lisp-warnings-log-level*'> - clix:descriptionLog level for Lisp warnings. - </clix:description> - </clix:special-variable> - <clix:special-variable name='*log-lisp-errors-p*'> - clix:descriptionWhether Lisp errors should be logged. - </clix:description> - </clix:special-variable> - <clix:special-variable name='*log-lisp-warnings-p*'> - clix:descriptionWhether Lisp warnings should be logged. - </clix:description> - </clix:special-variable> - <clix:special-variable name='*message-log-pathname*'> - clix:descriptionA 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:descriptionA 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-listlog-level format-string - clix:lkwrest - </clix:lkw> format-arguments - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionConvenience 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-listpathspec </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-listrequest + </clix:lambda-list> + clix:returnsnil + </clix:returns> + clix:description +This function is called by clix:refPROCESS-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:refPROCESS-CONNECTION</clix:ref> is called once per +connection and loops in case of a persistent connection +while clix:refPROCESS-REQUEST</clix:ref> is called anew for each +request. +<p> +Like clix:refPROCESS-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