js

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

Log level object,
or the name of it as a string
msg String

log message
args * <optional>
<repeatable>

additional arguments to use for parameterization. If
the final argument is an Error, it will be logged by itself.
Returns:

promise to be resolved when all handlers are finished
publishing

Type
Promise
Example
const name = promptForName();
log.log(Level.FINE, 'Hello, {}!', name);

try {
  doSomething();
} catch (err) {
  log.log('SEVERE', 'An error occurred at {}', new Date(), err);
}

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

time(id [, level] [, msg] [, args])

Starts timing a particular operation.

Parameters:
Name Type Argument Default Description
id string

a "unique" ID to describe this operation.
level module:nmodule/js/rc/log/Log.Level | string <optional>
 INFO

Log level
object, or the name of it as a string
msg string <optional>

a message to log. If omitted, will simply log the ID
args * <optional>
<repeatable>

additional arguments to format the message
Throws:

if ID not provided

Type
Error
Returns:

a ticket that may be passed to timeEnd

Type
number

timeEnd( [id] [, msg] [, args])

Stops timing a particular operation.

Parameters:
Name Type Argument Default Description
id string | number <optional>

the ID passed to time() (if duplicates are
found, this will stop the least recently started timer). Or, pass the exact
ticket returned from time(). If omitted, this call will be a no-op (this
makes it safe to wrap time() calls in isLoggable checks).
msg string <optional>
 "id: {}ms"

a message to log. For format arguments,
the number of milliseconds elapsed is always the last.
args * <optional>
<repeatable>

any additional arguments to use to format the message

  • remember elapsed time will always be added

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