Description

Logging Facility

Author

Kon Lovett

Usage

(require-extension logging)

Download

logging.egg

Requires

Documentation

A logging API for Chicken.

This is a work in progress.

Objects

Logbook

The definition of a stream of log text messages.

Slot Concepts
ID Symbol key for this log.
PATHNAME A local filesystem pathname, #f, or URI (only 'mailto' & 'file' recognized).
SOURCES Who can write to this log.
ENTRY Default entry for log.
LEVEL Lowest priority level for this log.
ECHOS Logs to copy all writes.
ALTERNATES When a log operation fails for this log try these logs.
KEEP-OPEN? Do not implicitly close this log.
IMMEDIATE-OPEN? Open this log upon construction or load.
OPERATIONS Access procedures for this log.
ASYNCHRONOUS? Perform log operations for this log in a separate thread?
ASYNCHRONOUS-ERROR Procedure to handle log operation errors for this log in asynchronous operation.
Entry

A log message specification.

Slot Concepts
ID Symbol key for this entry.
INDENT Indentation level for this entry.
LEVEL The priority level for this entry.
FIELDS The message decoration specifier for this entry.
Source

The identity of the agent generating a log message.

Slot Concepts
ID Symbol key for this source.
NAME Printable identity of this source.
Level

The importance of the log message.

Slot Concepts
ID Symbol key for this level.
PRIORITY Priority for this level, in (most-negative-fixnum most-positive-fixnum).
NAME Printable identity of this level.
Field

Log message decorator.

Slot Concepts
ID Symbol key for this level.
VALUE The decoration specification.

Any Scheme object can be a field value, and the string representation is used. However, some objects are interpreted.

procedure: THUNK

Invokes the procedure and uses the result as the field value.

record: FIELD

The value of the field object.

macro: SYMBOL

If a field identifier in the catalog then the catalog item is the value. Otherwise the string symbol representation.

macro: (quote SYMBOL)

The symbol string representation. For use with symbols which identify cataloged fields.

macro: (? TEST-FIELD [FIELD ...])

Conditional. Should TEST-FIELD yield the null string then the entire conditional is considered null. Otherwise yields TEST-FIELD FIELD ....

Operations

The procedures to perform port open, close and write.

Slot Concepts
OPEN (-> pathname errors port); doesn't actually need to be a port, just something understood by the CLOSE and WRITE procedures.
CLOSE (-> port errors boolean)
WRITE (-> port string errors boolean)

Built-in Objects

Logbook Identifiers
console A log for the console, with entry 'message'.
system A log for syslog, with entry 'system-message'.
error A log for stderr with entry 'message'.
message A log with the pathname "./message.log" and entry 'message'.

Entry Identifiers
message An entry with fields "(timestamp " " (? source " ") (? level " "))" .
system-message An entry with fields "((? source " ") (? level " "))" .

Source Identifiers
all A source with a null name.

Ordered by priority:

Level Identifiers
off A level with a null name and the highest possible priority.
fatal A level with a FATAL name.
emergency A level with a EMERGENCY name.
alert A level with a ALERT name.
critical A level with a CRITICAL name.
error A level with a ERROR name.
warning A level with a WARNING name.
notice A level with a NOTICE name.
information A level with a INFORMATION name.
debug A level with a DEBUG name.
trace A level with a TRACE name.
all A level with a null name and the lowest possible priority.

Field Identifiers
pid A field with the process id value.
hostname A field with the hostname value.
timestamp A field with a timestamp value.
source A field with the source value.
level A field with the level value.

Log State Operations

procedure: (open-logbook LOG)

Open the LOG.

procedure: (close-logbook LOG)

Close the LOG.

procedure: (logbook-level LOG)

Returns the LOG level.

procedure: (set-logbook-level! LOG LEVEL)

Changes the LOG level to LEVEL.

procedure: (logbook-level-mask LOG)

Returns the LOG level mask.

procedure: (set-logbook-level-mask! LOG [LEVEL ...])

Changes the LOG level mask to LEVEL ....

Log Write Operations

Explicit arguments always take priority, then object slots, and finally defaults. For example, an explict INDENT has priority over an ENTRY indent.

Log write attempts are verified by the SOURCE.

The OPEN? argument specifies if a log should be temporarily opened for just the write.

Log writes are performed when the LEVEL is at or above the LOG level. The LOG mask can be used to further restrict the valid levels.

The LOG, ENTRY, LEVEL, and SOURCE arguments below can be symbols (catalog identifiers), or objects of the stated type.

procedure: (log-string [LOG] STRING [#:source] [#:level] [#:echos] [#:alternates] [#:open? #t] [#:asynchronous? #f] [#:asynchronous-error])

Logs the undecorated STRING.

procedure: (log-message [LOG] STRING [#:entry] [#:indent 0] [#:source] [#:level] [#:echos] [#:alternates] [#:open? #t] [#:asynchronous? #f] [#:asynchronous-error] [FIELD ...])

Logs the STRING decorated by FIELD ....

procedure: (log-format [LOG] FORMAT-STRING [#:entry] [#:indent 0] [#:source] [#:level] [#:fields] [#:echos] [#:alternates] [#:open? #t] [#:asynchronous? #f] [#:asynchronous-error] [FORMAT-ARGUMENT ...])

Logs the FORMAT-ARGUMENT ... formatted by the (current-logbook-format-procedure) and FORMAT-STRING, decorated by FIELDS.

procedure: (%log-string LOG STRING [ECHOS [ALTERNATES [OPEN? [ASYNCHRONOUS? [ASYNCHRONOUS-ERROR]]]]])

Performs no argument checking. Logs the STRING.

Log Message Construction

procedure: (make-log-string [LOG] [#:entry] [#:indent] [#:source] [#:level] [#:fields] [STRING ...])

Returns the STRING ... decorated by FIELDS.

procedure: (%make-log-string LOG INDENT SOURCE LEVEL FIELD-LIST [STRING ...])

Performs no argument checking. Returns the decorated STRING ....

procedure: (make-log-mail-string LOG STRING)

Returns three values - a list of to addresses, a from address, and a string for the rest of the mail message.

The values are only meaningful for a mailto uri log.

Parameters

parameter: (current-logbook-format-procedure [FORMAT-PROCEDURE])

Sets or gets the format procedure to use for formatting log messages.

parameter: (current-logbook-indent-amount [FIXNUM])

Gets or sets the number of spaces for an indent.

parameter: (default-asynchronous-error [(-> condition undefined)])

Gets or sets the procedure to call with an exception condition raised during asynchronous logging.

parameter: (default-logbook [LOG-OBJECT-OR-ID])

Gets or sets the default log.

parameter: (default-logbook-directory [STRING])

Gets or sets the default directory for a log file.

parameter: (default-logbook-extension [STRING])

Gets or sets the default extension for a log file.

parameter: (default-logbook-entries [ATOMIC-OR-LIST-OF ENTRY-OBJECT-OR-ID])

Gets or sets the default entries for a log.

parameter: (default-logbook-sources [ATOMIC-OR-LIST-OF SOURCE-OBJECT-OR-ID])

Gets or sets the default sources for a log.

parameter: (default-logbook-entry [ENTRY-OBJECT-OR-ID])

Gets or sets the default entry for a log.

parameter: (default-logbook-source [SOURCE-OBJECT-OR-ID])

Gets or sets the default source for a log.

parameter: (default-logbook-level [LEVEL-OBJECT-OR-ID])

Gets or sets the default level for a log.

parameter: (default-logbook-fields [ATOMIC-OR-LIST-OF FIELD-OBJECT-OR-ID])

Gets or sets the default fields for a log.

parameter: (default-logbook-echos [ATOMIC-OR-LIST-OF LOG-OBJECT-OR-ID])

Gets or sets the default echo logs for a log.

parameter: (default-logbook-alternates [ATOMIC-OR-LIST-OF LOG-OBJECT-OR-ID])

Gets or sets the default alternate logs for a log.

parameter: (default-entry-level [ATOMIC-OR-LIST-OF LEVEL-OBJECT-OR-ID])

Gets or sets the default level for an entry.

parameter: (default-entry-fields [ATOMIC-OR-LIST-OF FIELD-OBJECT-OR-ID])

Gets or sets the default fields for an entry.

parameter: (default-logbook-catalog [PATHNAME])

Gets or sets the log catalog file pathname.

parameter: (default-mail-authority [(#f SMTP-HOST SMTP-PORT])

Gets or sets the mail uri scheme default smtp authority.

procedure: (logbook-uri-scheme-handler SCHEME [(-> LOG STRING ERRORS BOOLEAN)])

Gets or sets the uri SCHEME handler.

Object Construction

The LOG, ENTRY, LEVEL, and SOURCE arguments below maybe symbols (catalog identifiers), or actual objects of the stated type.

Any missing components of the PATHNAME argument below will be supplied from the defaults and the ID.

procedure: (make-logbook-pathanme FILENAME [#:dir] [#:ext])

Returns a pathname, with parameter defaults for the DIR and EXT arguments.

procedure: (make-logbook-source ID [NAME])

Returns a source object.

procedure: (make-logbook-level ID [PRIORITY] [NAME])

Returns a level object.

procedure: (make-logbook-field ID [VALUE])

Returns a field object.

procedure: (make-logbook-entry ID [#:indent 0] [#:level] [FIELD ...])

Returns an entry object.

procedure: (clone-logbook-entry ENTRY ID [#:indent 0] [#:level] [FIELD ...])

Returns an entry object, copied from ENTRY, with slot overrides.

procedure: (make-logbook ID [#:pathname] [#:sources] [#:entry] [#:level] [#:echos] [#:alternates] [#:keep-open? #f] [#:immediate-open? #f] [#:operations] [#:asynchronous? #f] [#:asynchronous-error])

Returns a log object.

procedure: (clone-logbook LOG ID [#:pathname] [#:sources] [#:entry] [#:level] [#:echos] [#:alternates] [#:keep-open? #f] [#:immediate-open? #f] [#:operations] [#:asynchronous? #f] [#:asynchronous-error])

Returns an log object, copied from LOG, with slot overrides.

procedure: (new-logbook-source ID [NAME])

Returns a source object added to the catalog.

procedure: (new-logbook-level ID [NAME])

Returns a level object added to the catalog.

procedure: (new-logbook-field ID [VALUE])

Returns a field object added to the catalog.

procedure: (new-logbook-entry ID [#:indent 0] [#:level] [FIELD ...])

Returns an entry object added to the catalog.

procedure: (clone-new-logbook-entry ENTRY ID [#:indent 0] [#:level] [FIELD ...])

Returns an entry object, copied from ENTRY, with slot overrides, added to the catalog.

procedure: (new-logbook ID [#:pathname] [#:sources] [#:entry] [#:level] [#:echos] [#:alternates] [#:keep-open? #f] [#:immediate-open? #f] [#:operations] [#:asynchronous? #f] [#:asynchronous-error])

Returns a log object added to the catalog.

procedure: (clone-new-logbook LOG ID [#:pathname] [#:sources] [#:entry] [#:level] [#:echos] [#:alternates] [#:keep-open? #f] [#:immediate-open? #f] [#:operations] [#:asynchronous? #f] [#:asynchronous-error])

Returns an log object, copied from LOG, with slot overrides, added to the catalog.

procedure: (make-logbook-operations OPEN CLOSE WRITE)

Returns an operations object.

Catalog Operations

Usage

(require-extension logging-objects)
Catalog Reference

The arguments below maybe symbols (catalog identifiers), or actual objects of the stated type.

procedure: (logbook-source SOURCE)

Returns the corresponding object from the catalog or #f.

procedure: (logbook-field FIELD)

Returns the corresponding object from the catalog or #f.

procedure: (logbook-level LEVEL)

Returns the corresponding object from the catalog or #f.

procedure: (logbook-entry ENTRY)

Returns the corresponding object from the catalog or #f.

procedure: (logbook LOG)

Returns the corresponding object from the catalog or #f.

Catalog Insertion

The arguments below must be actual objects of the stated type.

procedure: (logbook-source-add! SOURCE)

Adds the object to the catalog. Error when identifier in use.

procedure: (logbook-field-add! FIELD)

Adds the object to the catalog. Error when identifier in use.

procedure: (logbook-level-add! LEVEL)

Adds the object to the catalog. Error when identifier in use.

procedure: (logbook-entry-add! ENTRY)

Adds the object to the catalog. Error when identifier in use.

procedure: (logbook-add! LOG)

Adds the object to the catalog. Error when identifier in use.

Catalog Deletion

The arguments below maybe symbols (catalog identifiers), or actual objects of the stated type.

procedure: (logbook-source-delete! SOURCE)

Removes the object from the catalog.

procedure: (logbook-field-delete! FIELD)

Removes the object from the catalog.

procedure: (logbook-level-delete! LEVEL)

Removes the object from the catalog.

procedure: (logbook-entry-delete! ENTRY)

Removes the object from the catalog.

procedure: (logbook-delete! LOG)

Removes the object from the catalog.

File Operations

Usage

(require-extension logging-files)
procedure: (logbook-file-archive LOG)

Compress the specified LOG file.

Log archive files have the extension "[0-9]+.gz".

procedure: (logbook-file-delete LOG)

Delete the specified LOG file.

procedure: (logbook-file-purge LOG)

Delete all file associate with the specified LOG.

procedure: (logbook-file-rotate LOG)

Compress the specified LOG file and delete the original.

procedure: (logbook-catalog-load [PATHNAME (default-logbook-catalog)])

Replace the existing catalog with the contents of the saved catalog file.

procedure: (logbook-catalog-merge [PATHNAME (default-logbook-catalog)])

Merge the contents of the saved catalog file with the existing catalog. Error when attempting to replace an existing item.

procedure: (logbook-catalog-store [PATHNAME (default-logbook-catalog)])

Store the existing catalog as the contents of the catalog file.

Issues

Poor documentation.

Many options with complicated argument processing.

No Windows support for syslog.

No override of file permissions.

No abstractions for distributed logging.

Incomplete testing.

Version

License

Copyright (c) 2006, Kon Lovett.  All rights reserved.

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 ASIS, 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.