Module: nmodule/js/rc/log/Log


new (require("nmodule/js/rc/log/Log"))()

Class for logging messages throughout Niagara JS apps. Do not instantiate
this class directly: rather use the getLogger() function.

Logs support SLF4J-style parameterization. See example.

See:
Examples

Supports SLF4J-style format anchors.

return Log.getLogger('my.package.name')
  .then(function (log) {
    return log.log(Log.Level.INFO, 'foo was {} and bar was {}', 'foo', 'bar');
  });
  

Supports a trailing Error argument.

doSomethingAsync()
  .catch(function (err) {
    return Log.logMessage('my.package.name', Log.Level.SEVERE,
      '{} rejected with error', 'doSomethingAsync', err);
  });

Has convenience methods for behaving like the console.

define(['nmodule/js/rc/log/Log'], function (console) {
  //Note that all of these create and return Promises behind the scenes.
  //The log name will be browser.console.
  console.log('this logs at', 'FINE', 'level');
  console.info('this logs at', 'INFO', 'level');
  console.warn('this logs at', 'WARNING', 'level');
  console.error('this logs at', 'SEVERE', 'level');
});

Classes

Level

Methods


<static> error()

Logs a message to the browser.console log at SEVERE level.
This matches a browser's console.error API.

Returns:
Type
Promise
Example
Log.error('this', 'is', 'an', 'error', 'message');

<static> getLogger(name)

Resolve a Log instance with the given name.

Parameters:
Name Type Description
name string

name for the log to retrieve. Calling getLogger()
twice for the same name will resolve the same Log instance.

Returns:
Type
Promise.<module:nmodule/js/rc/log/Log>

<static> info()

Logs a message to the browser.console log at INFO level.
This matches a browser's console.info API.

Returns:
Type
Promise
Example
Log.info('this', 'is', 'an', 'info', 'message');

<static> log()

Logs a message to the browser.console log at FINE level.
This matches a browser's console.log API.

Returns:
Type
Promise
Example
Log.log('this', 'is', 'a', 'fine', 'message');

<static> logMessage(name, level, msg [, args])

Convenience method to stop you from having to resolve the Log.getLogger()
promise every time you wish to log a message. This will combine the lookup
and log into one step.

Note that you cannot perform an isLoggable() check with this method, so
if your log message is expensive to generate, you may want to fully resolve
the logger first.

Parameters:
Name Type Argument Description
name string
level module:nmodule/js/rc/log/Log.Level
msg String

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

Returns:

promise to be resolved when the message has been logged

Type
Promise

<static> warn()

Logs a message to the browser.console log at WARNING level.
This matches a browser's console.warn API.

Returns:
Type
Promise
Example
Log.warn('this', 'is', 'a', 'warning', 'message');

addHandler(handler)

Add a new handler to this Log. The same handler instance cannot be added
to the same log more than once.

Parameters:
Name Type Description
handler module:nmodule/js/rc/log/Log~Handler

config(msg [, args])

Logs the given message with level CONFIG.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

fine(msg [, args])

Logs the given message with level FINE.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

finer(msg [, args])

Logs the given message with level FINER.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

finest(msg [, args])

Logs the given message with level FINEST.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

getLevel()

Get the level configured for this log.

Returns:
Type
module:nmodule/js/rc/log/Log.Level

getName()

Get the log's name.

Returns:
Type
string

info(msg [, args])

Logs the given message with level INFO.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

isLoggable(level)

Return true if a log message at the given log level will actually be logged
by this logger. Use this to improve performance if a log message would be
expensive to create.

Parameters:
Name Type Description
level module:nmodule/js/rc/log/Log.Level | string
Returns:
Type
boolean

log(level, msg [, args])

Log the given message, giving all Handlers attached to this Log a chance
to publish it.

Parameters:
Name Type Argument Description
level module:nmodule/js/rc/log/Log.Level | string
msg String

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

Returns:

promise to be resolved when all handlers are finished
publishing

Type
Promise

setLevel(level)

Sets the logging level configured on this Log instance.

Parameters:
Name Type Description
level module:nmodule/js/rc/log/Log.Level

severe(msg [, args])

Logs the given message with level SEVERE.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

warning(msg [, args])

Logs the given message with level WARNING.

Parameters:
Name Type Argument Description
msg string

log message

args * <optional>
<repeatable>

additional arguments to use for parameterization

See:
Returns:
Type
Promise

Type Definitions


Handler

Responsible for actually publishing a log message to some destination
(console, baja.outln, logfile, etc).

Type:
  • Object
Properties:
Name Type Description
publish module:nmodule/js/rc/log/Log~PublishCallback

implements
how log messages will be handled


PublishCallback(name, level, msg)

When adding a custom Handler, implement the publish function to define
how log messages will be handled.

Parameters:
Name Type Description
name string

log name

level module:nmodule/js/rc/log/Log.Level

log level

msg string

an already fully-formatted log message.

Returns:
Type
Promise