Source Code

Defines a platform-neutral API for writing log messages.

Important! By default, no log writer function is registered, and so nothing is logged. Read on to learn how to properly configure logging for your application

Adding logging to your module

Log messages are written to a Logger. A canonical Logger instance for a package or module may be obtained by calling logger.

Logger log = logger(`module hello`);

The methods Logger.fatal(), Logger.error(), Logger.warn(), Logger.info(), Logger.debug(), and Logger.trace() write log messages with various priorities.

log.debug("trying to do something");
try {
    doSomething();
}
catch (e) {
    log.error("something bad happened", e);
}

For log messages with interpolated expressions, these methods accept an anonymous function.

log.debug(()=>"trying to do ``something``");
try {
    do(something);
}
catch (e) {
    log.error(()=>"badness happened doing ``something``", e);
}

Configuring logging for your application

If your module is going to be part of a larger application then the above is the only thing you need to know to add logging. But given the fact that this logging module does not actually define any infrastructure for log message output, your application must at some point during startup register a LogWriter function by calling addLogWriter() and passing it a log writer function. For example:

addLogWriter(writeSimpleLog);

writeSimpleLog() is a trivial log writer function that logs information to standard out and warnings and errors to standard error. Your program will almost certainly need to define its own log writer function that appends to a file, or whatever.

It's easy to customize the output by writing your own LogWriter. For example, we can use ceylon.time and ceylon.locale to obtain a nicely formatter time and date:

import ceylon.logging { ... }
import ceylon.time { now }
import ceylon.locale { systemLocale }

...

addLogWriter {
    void log(Priority p, Category c, String m, Throwable? t) {
        value print 
                = p <= info 
                then process.write
                else process.writeError;
        value instant = now();
        value formats = systemLocale.formats;
        value date = 
                formats.shortFormatDate(instant.date());
        value time = 
                formats.mediumFormatTime(instant.time());
        print("[``date`` at ``time``] ``p.string``: ``m``");
        print(operatingSystem.newline);
        if (exists t) {
            printStackTrace(t, print);
        }
    }
};

Or, to log to a file, using ceylon.file:

import ceylon.logging { ... }
import ceylon.file { ... }

File file;
switch (resource = parsePath("log.txt").resource)
case (is ExistingResource) {
    assert (is File resource);
    file = resource;
}
case (is Nil) {
    file = resource.createFile();
}

addLogWriter {
    void log(Priority p, Category c, String m, Throwable? t) {
        try (appender = file.Appender()) {
            appender.writeLine("[``system.milliseconds``] ``p.string``: ``m``");
            if (exists t) {
                printStackTrace(t, appender.write);
            }
        }
    }
};

By default, only log messages with priority at least info are sent to the LogWriter functions. To change the minimum priority, assign to defaultPriority.

defaultPriority = debug;

Alternatively, we can assign an explicit priority to a specific Logger by assigning to Logger.priority.

logger(`module hello`).priority = debug;

For integration with other logging libraries, it is possible to completely replace the logger function with a custom function for producing Loggers.

logger = (Category category)
    => JDKLoggerImpl(JDKLogger.getLogger(category.qualifiedName));
Packages
ceylon.logging
Dependencies
ceylon.collection1.3.3
Aliases
CategorySource Codeshared Category=> Module|Package

A topic to which a log message relates.

LogWriterSource Codeshared LogWriter=> Anything(Priority, Category, String, Throwable?)

A function capable of outputting log messages. LogWriters are registered with the logging system by calling addLogWriter().

Values
debugSource Codeshared debug debug

An event that is only interesting when debugging the program.

defaultPrioritySource Codeshared variable Priority defaultPriority

The default Priority for newly created Loggers. This priority is inherited by all other loggers which do not have a priority explicitly assigned to Logger.priority.

errorSource Codeshared error error

An error, often causing the program to abandon its current work.

fatalSource Codeshared fatal fatal

A serious failure, usually leading to program termination.

infoSource Codeshared info info

An important event in the program lifecycle.

loggerSource Codeshared variable Logger(Category) logger

Function to obtain a canonical Logger for the given Category. For each Category, there is at most one instance of Logger.

Assigning a new function of type Logger(Category) to logger allows the program to specify a custom strategy for Logger instantiation.

traceSource Codeshared trace trace

An event that is only interesting when the programmer is pulling out hair while debugging the program.

warnSource Codeshared warn warn

A warning, usually indicating that the program can continue with its current work.

Functions
addLogWriterSource Codeshared void addLogWriter(LogWriter log)

Register a new log writer function with the logging system. Log messages are directed to all registered LogWriters.

writeSimpleLogSource Codeshared void writeSimpleLog(Priority priority, Category category, String message, Throwable? throwable)

A trivial LogWriter that prints messages with priority:

The format of the message is:

[milliseconds] PRIORITY message

This log writer function must be registered explicitly by calling:

addLogWriter(writeSimpleLog);
Interfaces
LoggerSource Codeshared Logger

An object that sends log messages relating to a particular topic. A Logger instance for a Category may be obtained by invoking logger.

Logger log = logger(`module org.hibernate`);

Each Logger has a priority. Log messages with a priority lower than the current priority of the Logger will not be sent.

log.priority = warn;
log.info("hello"); //not sent
log.error("sos"); //sent
Classes
PrioritySource Codeshared abstract Priority

The importance of a log message. Prioritys have a total order running from most important to least important.

debugSource Codeshared debug

An event that is only interesting when debugging the program.

errorSource Codeshared error

An error, often causing the program to abandon its current work.

fatalSource Codeshared fatal

A serious failure, usually leading to program termination.

infoSource Codeshared info

An important event in the program lifecycle.

traceSource Codeshared trace

An event that is only interesting when the programmer is pulling out hair while debugging the program.

warnSource Codeshared warn

A warning, usually indicating that the program can continue with its current work.