4.15. Logging

log is a useful system-wide logging mechanism. You can find it in the system category of globals.

4.15.1. How to log

There are a number of useful messages in the logging category of log which allow you to simply and cleanly log messages. For example:

log warn: 'This is a warning.'

You can log with one of five levels found at log levels. These are, in order of severity, debug, info, warn, error, fatal.

You can also tag log entries, for example:

log fatal: 'The server has caught fire' For: 'webserver'

By default, entries of either error or fatal severity which aren’t tagged are logged to stderr in the form:

[Thu Oct 23 16:25:07 2014] error -- Something went wrong!

4.15.2. How logging works

The helper methods shown above constuct a log entry and hand it to the log dispatcher. The dispatcher has a number of handlers, each is given a chance to handle the log entry. The handlers can choose which entries to act on. Example handlers are in log prototypeHandlers.

When making a handler, please keep in mind that the log entry’s message is expected to be something which understands value, returning an object (or itself) which understands asString. If you do not need to resolve the message by sending it value please don’t; that way logs can be sent blocks which are only resolved if necessary; eg:

log debug: ['We have reached: ', somethingComplicatedToCalculate]

will not slow down your code if no log handler is interested in handling debuggers.

If your handler breaks the logging process you can restart it by:

log dispatcher hup