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
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); }
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 Logger
s.
logger = (Category category) => JDKLoggerImpl(JDKLogger.getLogger(category.qualifiedName));
Packages | |
ceylon.logging |
Dependencies | ||
ceylon.collection | 1.3.3 |
Aliases | |
Category | Source Codeshared Category=> Module|Package A topic to which a log message relates. See also logger , Logger.category |
LogWriter | Source Codeshared LogWriter=> Anything(Priority, Category, String, Throwable?) A function capable of outputting log messages. See also addLogWriter() |
Values | |
debug | Source Codeshared debug debug An event that is only interesting when debugging the program. |
defaultPriority | Source Codeshared variable Priority defaultPriority The default |
error | Source Codeshared error error An error, often causing the program to abandon its current work. |
fatal | Source Codeshared fatal fatal A serious failure, usually leading to program termination. |
info | Source Codeshared info info An important event in the program lifecycle. |
logger | Source Codeshared variable Logger(Category) logger |
trace | Source Codeshared trace trace An event that is only interesting when the programmer is pulling out hair while debugging the program. |
warn | Source Codeshared warn warn A warning, usually indicating that the program can continue with its current work. |
Functions | |
addLogWriter | Source Codeshared void addLogWriter(LogWriter log) Register a new log writer function with the logging
system. Log messages are directed to all registered
|
writeSimpleLog | Source 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:
This log writer function must be registered explicitly by calling: addLogWriter(writeSimpleLog); |
Interfaces | |
Logger | Source Codeshared Logger An object that sends log messages relating to a particular
topic. A Logger log = logger(`module org.hibernate`); Each log.priority = warn; log.info("hello"); //not sent log.error("sos"); //sent |
Classes | |
Priority | Source Codeshared abstract Priority The importance of a log message. |
debug | Source Codeshared debug An event that is only interesting when debugging the program. |
error | Source Codeshared error An error, often causing the program to abandon its current work. |
fatal | Source Codeshared fatal A serious failure, usually leading to program termination. |
info | Source Codeshared info An important event in the program lifecycle. |
trace | Source Codeshared trace An event that is only interesting when the programmer is pulling out hair while debugging the program. |
warn | Source Codeshared warn A warning, usually indicating that the program can continue with its current work. |