module:nmodule/js/rc/log/Log

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

Description:

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.

Source:

log/Log.js, line 98

See:

module:log

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

addHandler(handler)

Description:

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

Source:

log/Log.js, line 225

Parameters:

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

config(msg, …argsopt) → {Promise}

Description:

Logs the given message with level CONFIG.

Source:

log/Log.js, line 435

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

fine(msg, …argsopt) → {Promise}

Description:

Logs the given message with level FINE.

Source:

log/Log.js, line 446

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

finer(msg, …argsopt) → {Promise}

Description:

Logs the given message with level FINER.

Source:

log/Log.js, line 457

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

finest(msg, …argsopt) → {Promise}

Description:

Logs the given message with level FINEST.

Source:

log/Log.js, line 468

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

getLevel() → {module:nmodule/js/rc/log/Log.Level}

Description:

Get the level configured for this log.

Source:

log/Log.js, line 239

Returns:

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

getName() → {string}

Description:

Get the log's name.

Source:

log/Log.js, line 248

Returns:

Type: string

info(msg, …argsopt) → {Promise}

Description:

Logs the given message with level INFO.

Source:

log/Log.js, line 479

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

isLoggable(level) → {boolean}

Description:

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.

Source:

log/Log.js, line 259

Parameters:

Name	Type	Description
`level`	module:nmodule/js/rc/log/Log.Level \| string

Returns:

Type: boolean

log(level, msg, …argsopt) → {Promise}

Description:

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

Source:

log/Log.js, line 294

Example

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

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

Parameters:

Name	Type	Attributes	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

setLevel(level)

Description:

Sets the logging level configured on this Log instance.

Source:

log/Log.js, line 509

Parameters:

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

severe(msg, …argsopt) → {Promise}

Description:

Logs the given message with level SEVERE.

Source:

log/Log.js, line 490

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

time(id, levelopt, msgopt, …argsopt) → {number}

Description:

Starts timing a particular operation.

Source:

log/Log.js, line 334

Parameters:

Name	Type	Attributes	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(idopt, msgopt, …argsopt)

Description:

Stops timing a particular operation.

Source:

log/Log.js, line 360

Parameters:

Name Type Attributes Default Description

Name	Type	Attributes	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

id

string | number

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

"id: {}ms"

a message to log. For format arguments,
the number of milliseconds elapsed is always the last.

args

any additional arguments to use to format the message

remember elapsed time will always be added

warning(msg, …argsopt) → {Promise}

Description:

Logs the given message with level WARNING.

Source:

log/Log.js, line 501

See:

module:nmodule/js/rc/log/Log#log

Parameters:

Name	Type	Attributes	Description
`msg`	string		log message
`args`	*	<optional> <repeatable>	additional arguments to use for parameterization

Returns:

Type: Promise

(static) error() → {Promise}

Description:

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

Source:

log/Log.js, line 193

Example

Log.error('this', 'is', 'an', 'error', 'message');

Returns:

Type: Promise

(static) getLogger(name) → {Promise.<module:nmodule/js/rc/log/Log>}

Description:

Resolve a Log instance with the given name.

Source:

log/Log.js, line 204

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() → {Promise}

Description:

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

Source:

log/Log.js, line 169

Example

Log.info('this', 'is', 'an', 'info', 'message');

Returns:

Type: Promise

(static) log() → {Promise}

Description:

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

Source:

log/Log.js, line 157

Example

Log.log('this', 'is', 'a', 'fine', 'message');

Returns:

Type: Promise

(static) logMessage(name, level, msg, …argsopt) → {Promise}

Description:

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.

Source:

log/Log.js, line 141

Parameters:

Name	Type	Attributes	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() → {Promise}

Description:

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

Source:

log/Log.js, line 181

Example

Log.warn('this', 'is', 'a', 'warning', 'message');

Returns:

Type: Promise

Type Definitions

Handler

Description:

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

Source:

log/Log.js, line 42

Properties:

Name	Type	Description
`publish`	module:nmodule/js/rc/log/Log~PublishCallback	implements how log messages will be handled

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

Type:

Object

PublishCallback(name, level, msg) → {Promise}

Description:

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

Source:

log/Log.js, line 50

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