Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

log5scm

Outdated egg!
log5scm

Introduction

A logging library based on the ideas of CL's log5

Repository

https://github.com/certainty/chicken_log5sm

Examples

(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"))

Documentation

[parameter] default-logical-connective

As the name suggests this is the connective that is assumed, if you do not explicitly specify it in the category-specification.

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

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) " "))

Predefined outputs

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)

[parameter] default-output-format

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).

Contexts

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")))

Logging

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:

LOG5SCM_IGNORE_CATEGORIES='(debug)'

Authors

David Krentzlin with the kind help of Moritz Heidkamp

License

 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.