Logger

Loggers are named entities, sometimes shared, sometimes specific to a particular portion of code. The names are generally hierarchical in nature, using dot notation (with '.') to separate each named section. For example, a typical name might be something like "mail.send.writer"

import tango.util.log.Log;format

auto log = Log.lookup ("mail.send.writer");

log.info  ("an informational message");
log.error ("an exception message: {}", exception.toString);

etc ...

It is considered good form to pass a logger instance as a function or class-ctor argument, or to assign a new logger instance during static class construction. For example: if it were considered appropriate to have one logger instance per class, each might be constructed like so:

private Logger log;

static this()
{
    log = Log.lookup (nameOfThisClassOrStructOrModule);
}

Messages passed to a Logger are assumed to be either self-contained or configured with "{}" notation a la Layout & Stdout:

log.warn ("temperature is {} degrees!", 101);

Note that an internal workspace is used to format the message, which is limited to 2048 bytes. Use "{.256}" truncation notation to limit the size of individual message components. You can also use your own formatting buffer:

log.buffer (new char[](4096));

log.warn ("a very long warning: {}", someLongWarning);

Or you can use explicit formatting:

char[4096] buf = void;

log.warn (log.format (buf, "a very long warning: {}", someLongWarning));

To avoid overhead when constructing argument passed to formatted messages, you should check to see whether a logger is active or not:

if (log.enabled (log.Warn))
    log.warn ("temperature is {} degrees!", complexFunction());

The above will be handled implicitly by the logging system when macros are added to the language (used to be handled implicitly via lazy delegates, but usage of those turned out to be awkward).

tango.log closely follows both the API and the behaviour as documented at the official Log4J site, where you'll find a good tutorial. Those pages are hosted over <A HREF="http://logging.apache.org/log4j/docs/documentation.html">here</A>.

class Logger : ILogger {

alias Trace = Level.Trace;

alias Info = Level.Info;

alias Warn = Level.Warn;

alias Error = Level.Error;

alias Fatal = Level.Fatal;

alias opCall = append;

interface Context;

bool enabled(Level level);

bool trace();

void trace(const(char[]) fmt, ...);

bool info();

void info(const(char[]) fmt, ...);

bool warn();

void warn(const(char[]) fmt, ...);

bool error();

void error(const(char[]) fmt, ...);

bool fatal();

void fatal(const(char[]) fmt, ...);

const(char)[] name [@property getter];

Level level();

Logger level(Level l);

Logger level(Level level, bool propagate);

bool additive [@property getter];

bool additive [@property setter];

Logger add(Appender another);

Logger clear();

char[] buffer [@property getter];

char[] buffer [@property setter];

TimeSpan runtime [@property getter];

Logger append(Level level, const(char[]) exp);

char[] format(char[] buffer, const(char[]) formatStr, ...);

Logger format(Level level, const(char[]) fmt, TypeInfo[] types, ArgList args);

}

Members

Aliases

Error alias Error = Level.Error: Undocumented in source.
Fatal alias Fatal = Level.Fatal: Undocumented in source.
Info alias Info = Level.Info: Undocumented in source.
Trace alias Trace = Level.Trace: Undocumented in source.
Warn alias Warn = Level.Warn: Undocumented in source.
opCall alias opCall = append: Undocumented in source.

Functions

add Logger add(Appender another): Add (another) appender to this logger. Appenders are each invoked for log events as they are produced. At most, one instance of each appender will be invoked.
append Logger append(Level level, const(char[]) exp): Send a message to this logger via its appender list.
clear Logger clear(): Remove all appenders from this Logger
enabled bool enabled(Level level): Is this logger enabed for the specified Level?
error bool error(): Is error enabled?
error void error(const(char[]) fmt, ...): Append an error message
fatal bool fatal(): Is fatal enabled?
fatal void fatal(const(char[]) fmt, ...): Append a fatal message
format char[] format(char[] buffer, const(char[]) formatStr, ...): Return a formatted string from the given arguments
format Logger format(Level level, const(char[]) fmt, TypeInfo[] types, ArgList args): Format and emit text from the given arguments
info bool info(): Is info enabled?
info void info(const(char[]) fmt, ...): Append an info message
level Level level(): Return the Level this logger is set to
level Logger level(Level l): Set the current level for this logger (and only this logger).
level Logger level(Level level, bool propagate): Set the current level for this logger, and (optionally) all of its descendents.
trace bool trace(): Is trace enabled?
trace void trace(const(char[]) fmt, ...): Append a trace message
warn bool warn(): Is warn enabled?
warn void warn(const(char[]) fmt, ...): Append a warning message

Interfaces

Context interface Context: Context for a hierarchy, used for customizing behaviour of log hierarchies. You can use this to implement dynamic log-levels, based upon filtering or some other mechanism

Properties

additive bool additive [@property getter]: Is this logger additive? That is, should we walk ancestors looking for more appenders?
additive bool additive [@property setter]: Set the additive status of this logger. See bool additive().
buffer char[] buffer [@property getter]: Get the current formatting buffer (null if none).
buffer char[] buffer [@property setter]: Set the current formatting buffer.
name const(char)[] name [@property getter]: Return the name of this Logger (sans the appended dot).
runtime TimeSpan runtime [@property getter]: Get time since this application started

Inherited Members

From ILogger

Level enum Level: Undocumented in source.
enabled Level enabled [@property setter]: Is this logger enabed for the specified Level?
trace void trace(const(char[]) fmt, ...): Append a trace message
info void info(const(char[]) fmt, ...): Append an info message
warn void warn(const(char[]) fmt, ...): Append a warning message
error void error(const(char[]) fmt, ...): Append an error message
fatal void fatal(const(char[]) fmt, ...): Append a fatal message
name const(char)[] name [@property getter]: Return the name of this ILogger (sans the appended dot).
level Level level [@property getter]: Return the Level this logger is set to
level Level level [@property setter]: Set the current level for this logger (and only this logger).
additive bool additive [@property getter]: Is this logger additive? That is, should we walk ancestors looking for more appenders?
additive bool additive [@property setter]: Set the additive status of this logger. See isAdditive().
append ILogger append(Level level, const(char[]) exp): Send a message to this logger via its appender list.