log

An interface for logging purposes. At least for permanent logging this should always be used in favor of console.log and friends, as it is cross browser secure and allows attaching multiple channels where messages can be routed to (i.e. to send them to a server process for persistence). If available, messages will be logged to the browser's console using a builtin console channel.

When requiring laxar, an instance of the Logger type is available as laxar.log.

Contents

Types

• level
• BLACKBOX
• Logger
  • Logger#create
  • Logger#log
  • Logger#trace
  • Logger#debug
  • Logger#info
  • Logger#warn
  • Logger#error
  • Logger#fatal
  • Logger#addLogChannel
  • Logger#removeLogChannel
  • Logger#addTag
  • Logger#setTag
  • Logger#removeTag
  • Logger#gatherTags
  • Logger#setLogThreshold

Types

level

By default available log levels, sorted by increasing log level:

• TRACE (level 100)
• DEBUG (level 200)
• INFO (level 300)
• WARN (level 400)
• ERROR (level 500)
• FATAL (level 600)

BLACKBOX

Pass this as an additional replacement parameter to a log-method to blackbox your logging call. Blackboxed callers are ignored when logging the source information (file, line). (#322)

Logger

Logger#create()

Creates and returns a new logger instance. Intended for testing purposes only.

Returns

Logger#log( level, message, replacementArguments )

Logs a message. A message may contain placeholders in the form [#] where # resembles the index within the list of replacements. replacements are incrementally counted starting at 0. If the log level is below the configured log threshold, the message is simply discarded.

It is recommended not to use this method directly, but instead one of the short cut methods for the according log level.

Parameters

Logger#trace( message, replacements )

Logs a message in log level TRACE. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#debug( message, replacements )

Logs a message in log level DEBUG. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#info( message, replacements )

Logs a message in log level INFO. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#warn( message, replacements )

Logs a message in log level WARN. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#error( message, replacements )

Logs a message in log level ERROR. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#fatal( message, replacements )

Logs a message in log level FATAL. See Logger#log for further information.

Important note: This method is only available, if no custom log levels were defined via configuration or custom log levels include this method as well.

Parameters

Logger#addLogChannel( channel )

Adds a new channel to forward log messages to. A channel is called synchronously for every log message and can do whatever necessary to handle the message according to its task. Note that blocking or performance critical actions within a channel should always take place asynchronously to prevent from blocking the application. Ideally a web worker is used for heavier background tasks.

Each message is an object having the following properties:

• id: the unique, ascending id of the log message
• level: the log level of the message in string representation
• text: the actual message that was logged
• replacements: the raw list of replacements passed along the message
• time: JavaScript Date instance when the message was logged
• tags: A map of all log tags currently set for the logger
• sourceInfo: if supported, a map containing file, line and char where the logging took place

Parameters

Logger#removeLogChannel( channel )

Removes a log channel and thus stops sending further messages to it.

Parameters

Logger#addTag( tag, value )

Adds a value for a log tag. If a tag is already known, the value is appended to the existing one using a ; as separator. Note that no formatting of the value takes place and a non-string value will just have its appropriate toString method called.

Log tags can be used to mark a set of log messages with a value giving further information on the current logging context. For example laxar sets a tag 'INST' with a unique-like identifier for the current browser client. If then for example log messages are persisted on a server, messages belonging to the same client can be accumulated.

Parameters

Logger#setTag( tag, value )

Sets a value for a log tag. If a tag is already known, the value is overwritten by the given one. Note that no formatting of the value takes place and a non-string value will just have its appropriate toString method called. For further information on log tags, see Logger#addTag.

Parameters

Logger#removeTag( tag )

Removes a log tag. For further information on log tags, see Logger#addTag.

Parameters

Logger#gatherTags()

Returns a map of all tags. If there are multiple values for the same tag, their values are concatenated using a ; as separator. For further information on log tags, see Logger#addTag.

Returns

Logger#setLogThreshold( threshold )

Sets the threshold for log messages. Log messages with a lower level will be discarded upon logging.

Parameters