You are looking at historical revision 29709 of this page. It may differ significantly from its current revision.
A logging library based on the ideas of CL's log5
(use log5scm syslog) (define-category info) (define-category debug) (define-category warn) (define-category warn+ (or info debug warn)) (define-category controller) (define-category model) (define-category app (or controller model)) (define-output model-out "model-out") (define-output controller-out "controller-out") (define-output app-out "app-out") ;;start port senders (start-sender model-sender (port-sender (current-error-port)) (output (model-out message)) (category model)) (start-sender controller-sender (port-sender (current-error-port)) (output (controller-out message)) (category controller)) (start-sender app-sender (port-sender (current-error-port)) (category app)) ;; a sender that matches any category (start-sender catchall-sender (port-sender (current-output-port)) (category *)) ;;additionally send every warning to syslog (start-sender syslog-warn (syslog-sender "test" opt/pid facility/local0 prio/warning) (category warn)) (with-context "Testcontext" (log-for (model warn) "just a ~A" "Test") (with-context "Nested Context" (log-for (app) "nother Test")) (log-for (app) "Final test"))
As the name suggests this is the connective that is assumed, if you do not explicitly specify it in the category-specification.
Categories are just a way to organize your log messages. You may arrange as many and as complex categories as you wish. They're, as the name suggests, a way to express buckets for log-messages. Those buckets may later be bound to senders and thus enable the program to put messages at the right places[syntax] (define-category category-spec)
Syntax to define categories. You can define simple and complex categories.
(define-category info) (define-category debug) (define-category warn) (define-category warn+ (or info debug warn))[procedure] (dump-categories)
Print all currently known categories to (current-output-port).
Senders are basically filtered sinks for messages. Any message that comes in, will be analyzed against the category-specification and only if a match is found the message is send to its destination. Furthermore senders decide where the output goes. The most commonly used senders will be port-senders. But you could as well send messages to syslog or to a port or via email or whatever. You're free to define a custom sender-type and use it for logging.[syntax] (start-sender name sender-constructor (category category-spec) [(output output-spec)])
Create and register a sender for the given categories. This sender will only react on matching categories.
- name: A name to identify this sender
- sender-constructor: One of the available constructors, see sender-constructors
- category-spec: A specification of the categories to match in order for the sender to be applied
- output-spec: A specification of the output-formatter. See outputs for details
;;start a port-sender for the category 'model' that outputs the data as "category message" (start-sender model-sender (port-sender (current-output-port)) (output (category message)) (category model))
;;start a port-sender that matches any category (start-sender catchall-sender (port-sender (current-output-port)) (category *))[procedure] (dump-senders)
Print the list of all known senders to current-output-port.
Sender constructors[procedure] (port-sender port-or-path #!key (lazy #f))
Creates a sender that outputs to a port. If port-or-path is a port, all data will be send to this port. If port-or-path is a string, it is considered a path to a file. The file will be opened and all messages will be send to this file. If lazy is set to true and port-or-path is a file-name, the sender will delay the opening of the file until it is actually needed, because a matching log-for statement is issued.[procedure] (syslog-sender ident options facility prio)
Creates a syslog-sender. All messages will be send to syslog with the given parameters. See also syslog.[procedure] (structured-sender function)
This sender is used in structurend logging. Structured logging means that objects are than mere strings are logged. This sender accepts a function of one argument (the logged data). The function is invoked whenever the category spec of the sender matches. Be careful to only use this sender with structured output.
(define-category struct) ;;structured logging (start-sender struct-sender (structured-sender (lambda (data) (print data))) (output (<structured)) (category struct))
Outputs are just a way to format your message. Technically an output is a procedure that returns a string. Multiple outputs can be combined into a list of outputs that are processed in order when a message is generated[syntax] (define-output name code)
Register an output with the given name. The output will be generated by evaluating code. During the evaluation of code the following parameters will be bound.
- current-message The content of the message
- current-category The category specification
As a convention output names start with a <.
(define-output <test-output (string-join (shuffle (string-split (current-message) " ") random) " "))
There are some outputs predefined that can be used inside output-specifications
- <message': the current message
- <category: the current category
- <context: the current context formatted as "Contextname > "
- <structured: this is just identity (it's used in structured logging)
This is the output-specification that is used by default when a sender is invoked. It is a list of outputs and defaults to (<context <category <message).
Sometimes it is useful to have a context which logging occurs in. For example if a subsystem logs it might want to execute those log statements inside its own context.[procedure] (push-context ctx)
Adds ctx to the current stack of contexts. This makes ctx the active context.[procedure] (pop-context)
Removes the most recently push context from the stack of contexts.[procedure] (call-with-context ctx thunk)
Sets the current context to ctx and invokes thunk. When thunk finishes it restores the previous context.[syntax] (with-context ctx code)
This syntax is a convenient wrapper around call-with-context, that adds a slightly less verbose interface.
(with-context "Test" (log-for (app) "This is executed withing Test-CTX") (with-context "Nested" (log-for (app) "This is executed in a nested Context")))
The actual logging is done using the log-for syntax.[syntax] (log-for spec fmt . args)
This form will invoke the logging machinery. It will find the senders that match the given spec, and send the message to all senders that have a matching category-specification.
(log-for (model warn) "just a ~A" "Test")
Disable logging-overhead for compiled programs
Sometimes you want to log messages only in development mode and don't want the overhead in production. This is mostly the case for expensive reporting like Benchmarking or some form of accumulated output.
If you set the LOG5SCM_IGNORE_CATEGORIES envrionment variable during compilation, all log-for statements that match this expression will essentially expand to (void).
This way you can disable for example debug messages like so:
Copyright (c) 2010 David Krentzlin Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.