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 ocean.util.log.Logger;

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:

module myapp.util.Transmogrifier;

private Logger log;

static this()
{
    log = Log.lookup("myapp.util.Transmogrifier");
}

Messages passed to a Logger are assumed to be either self-contained or configured with "{}" notation a la ocean.text.convert.Formatter:

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));

If argument construction has some overhead which you'd like to avoid, you can check to see whether a logger is active or not:

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

The ocean.util.log package 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: http://logging.apache.org/log4j/docs/documentation.html

final

class Logger : ILogger {

alias Trace = Level.Trace;

alias Info = Level.Info;

alias Warn = Level.Warn;

alias Error = Level.Error;

alias Fatal = Level.Fatal;

bool collect_stats;

this(HierarchyT!(Logger) host, istring name);

bool enabled(Level level);

void trace(cstring fmt, Args args);

void info(cstring fmt, Args args);

void warn(cstring fmt, Args args);

void error(cstring fmt, Args args);

void fatal(cstring fmt, Args args);

cstring name();

Level level();

Logger level(Level l);

Logger level(Level level, bool propagate);

bool additive();

Logger additive(bool enabled);

Logger add(Appender another);

Logger clear();

mstring buffer();

Logger buffer(mstring buf);

void collectStats(bool value, bool propagate);

TimeSpan runtime();

Logger append(Level level, cstring exp);

alias opCall = append;

void format(Level level, cstring fmt, Args args);

bool isChildOf(istring candidate);

bool isCloserAncestor(Logger other);

}

Constructors

this this(HierarchyT!(Logger) host, istring name): Construct a LoggerInstance with the specified name for the given hierarchy. By default, logger instances are additive and are set to emit all events.

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: Emit a textual log message from the given string

Functions

add Logger add(Appender another): Add (another) appender to this logger.
additive bool additive(): Is this logger additive configured as additive ?
additive Logger additive(bool enabled): Set the additive status of this logger. See bool additive().
append Logger append(Level level, cstring exp): Emit a textual log message from the given string
buffer mstring buffer()
buffer Logger buffer(mstring buf): Set the current formatting buffer.
clear Logger clear(): Remove all appenders from this Logger
collectStats void collectStats(bool value, bool propagate): Toggles the stats collecting for this logger and optionally for all its descendants.
enabled bool enabled(Level level): Is this logger enabled for the specified Level?
error void error(cstring fmt, Args args): Append a message with a severity of Level.Error.
fatal void fatal(cstring fmt, Args args): Append a message with a severity of Level.Fatal.
format void format(Level level, cstring fmt, Args args): Format and emit a textual log message from the given arguments
info void info(cstring fmt, Args args): Append a message with a severity of Level.Info.
isChildOf bool isChildOf(istring candidate): See if the provided Logger name is a parent of this one.
isCloserAncestor bool isCloserAncestor(Logger other): See if the provided Logger is a better match as a parent of this one.
level Level level()
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 descendants.
name cstring name()
runtime TimeSpan runtime()
trace void trace(cstring fmt, Args args): Append a message with a severity of Level.Trace.
warn void warn(cstring fmt, Args args): Append a message with a severity of Level.Warn.

Variables

collect_stats bool collect_stats;: Indicator if the log emits should be counted towards global stats.
level_ Level level_;: Level at which this Logger is configured
next Logger next;: Next logger in the list, maintained by Hierarchy
parent Logger parent;: Parent of this logger (maintained by Hierarchy)

Inherited Members

From ILogger

Level enum Level: Defines the level at which a message can be logged
convert Level convert(cstring name, Level def): Return the enum value associated with name, or a default value
convert istring convert(Level level): Return the name associated with level
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
enabled bool enabled(Level level)
name cstring name()
level Level level()
level ILogger level(Level l): Set the current Level for this logger (and only this logger).
additive bool additive()
additive ILogger additive(bool enabled): Set the additive status of this logger
append ILogger append(Level level, cstring exp): Send a message to this logger.

Logger

Constructors

Members

Aliases

Functions

Variables

Inherited Members

From ILogger

Meta

Source