cycle-logger

Provides logging capabilities to cycle.js applications.

Installation

npm i cycle-logger2 --save

Scripts

NOTE: Make sure you've installed all dependencies using npm install first.

To generate documentation: npm run doc. This will create documentation in the build/docs folder.

To run unit tests: npm test

API

Loggers

Create new Logger instances or filter logging events by Logger name or logging level.

Kind: global class

• Loggers
  • static
    • .Levels : enum
    • .get(name) ⇒ Logger
    • .asObservable() ⇒ LoggerObservable
  • inner
    • ~Levels : Object

Loggers.Levels : enum

An enumeration of logging levels that users can subscribe to. In order: ALL < TRACE < DEBUG < INFO < WARN < ERROR < NONE

Kind: static enum property of Loggers
Example

logger.on(Logger.Levels.WARN, function warningOccurred(msg) { ... });
logger.on(Logger.Levels.ERROR, function errorOccurred(msg) { ... });

Loggers.get(name) ⇒ Logger

Retrieves the specified Logger instance, creating one if necessary.

Kind: static method of Loggers
Returns: Logger - The Logger instance with the specified name.
Throws:

• Error A name must be specified.

Param	Type	Description
name	String	The name of the Logger instance to create/retrieve.

Example

Loggers.get('my.logger').warn('some warning message');

Loggers.asObservable() ⇒ LoggerObservable

Returns a LoggerObservable instance that can be filtered by Logger name or built-in log level.

Kind: static method of Loggers
Example

Loggers.asObservable()
  .byMinLevel(Loggers.Levels.WARN)
  .byName('my.logger')
  .subscribe(...);

Loggers~Levels : Object

The available logging levels. In order: ALL < TRACE < DEBUG < INFO < WARN < ERROR < NONE

Kind: inner typedef of Loggers
Properties

Name	Type	Description
ALL	String
TRACE	String	Extremely detailed information, like object dumps.
DEBUG	String	Detailed information on your program's execution flow.
INFO	String	Interesting lifecycle events.
WARN	String	Use of deprecated APIs, 'almost' errors, and other undesirable or unexpected events.
ERROR	String	Runtime errors and unexpected conditions.
NONE	String

Logger

Provides methods to log information at various levels.

Kind: global class

• Logger
  • .name : String
  • .trace(msg, args) ⇒ Logger
  • .debug(msg, args) ⇒ Logger
  • .info(msg, args) ⇒ Logger
  • .warn(msg, args) ⇒ Logger
  • .error(msg, args) ⇒ Logger

logger.name : String

The unique name of the Logger instance.

Kind: instance property of Logger
Read only: true

logger.trace(msg, args) ⇒ Logger

Outputs trace information to any registered listeners.

Kind: instance method of Logger
Returns: Logger - The Logger instance, for chaining.

Param	Type	Description
msg	String	The message string or object to log.
args	*	The arguments to substitute into the message string. See node's util.format method for more information on formatting.

logger.debug(msg, args) ⇒ Logger

Outputs debug information to any registered listeners.

Kind: instance method of Logger
Returns: Logger - The Logger instance, for chaining.

Param	Type	Description
msg	String	The message string or object to log.
args	*	The arguments to substitute into the message string. See node's util.format method for more information on formatting.

logger.info(msg, args) ⇒ Logger

Outputs non-error information to any registered listeners.

Kind: instance method of Logger
Returns: Logger - The Logger instance, for chaining.

Param	Type	Description
msg	String	The message string or object to log.
args	*	The arguments to substitute into the message string. See node's util.format method for more information on formatting.

logger.warn(msg, args) ⇒ Logger

Outputs warnings to any registered listeners.

Kind: instance method of Logger
Returns: Logger - The Logger instance, for chaining.

Param	Type	Description
msg	String	The message string or object to log.
args	*	The arguments to substitute into the message string. See node's util.format method for more information on formatting.

logger.error(msg, args) ⇒ Logger

Outputs error information to any registered listeners.

Kind: instance method of Logger
Returns: Logger - The Logger instance, for chaining.

Param	Type	Description
msg	String	The message string or object to log.
args	*	The arguments to substitute into the message string. See node's util.format method for more information on formatting.

LoggerObservable

Kind: global class
Inherits: Observable

• LoggerObservable
  • new LoggerObservable()
  • .byName(name) ⇒ Observable.<LoggingEvent>
  • .byMinLevel(level) ⇒ Observable.<LoggingEvent>
  • .byLevels(levels) ⇒ Observable.<LoggingEvent>

new LoggerObservable()

Provides operators for filtering logging events.

Example

Loggers.asObservable()
  .byName('log name')
  .map(event => event.message)
  .subscribe(msg => file.writeln(msg));

LoggerObservable.byName(name) ⇒ Observable.<LoggingEvent>

Kind: static method of LoggerObservable

Param	Type	Description
name	String | RegExp	The string or regular expression to use to match against Logger names in LoggingEvents.

Example

Loggers.asObservable()
  .byName('log name')
  .map(event => event.message)
  .subscribe(msg => file.writeln(msg));

LoggerObservable.byMinLevel(level) ⇒ Observable.<LoggingEvent>

Kind: static method of LoggerObservable
Throws:

• The specified level is invalid.

Param	Type	Description
level	Levels	The minimum level to filter LoggingEvents. Any events at or above this level will be included in the resulting observable.

Example

Loggers.asObservable()
  .byMinLevel(Loggers.Levels.WARN)
  .subscribe(event => file.writeln(`${event.logger}: ${event.message}`));

LoggerObservable.byLevels(levels) ⇒ Observable.<LoggingEvent>

Kind: static method of LoggerObservable
Throws:

• The specified level is invalid.

Param	Type	Description
levels	Array.<Levels>	One or more levels to filter LoggingEvents by.

Example

Loggers.asObservable()
  .byLevels(Loggers.Levels.INFO, Loggers.Levels.ERROR)
  .map(event => event.message)
  .subscribe(msg => file.writeln(msg));

LoggingEvent

Represents a single logged entry.

Kind: global class

• LoggingEvent
  • .level : Levels
  • .logger : String
  • .message : String
  • .datetime : Number
  • .toString([fmt]) ⇒ String

loggingEvent.level : Levels

The level the event was logged at.

Kind: instance property of LoggingEvent

loggingEvent.logger : String

The name of the Logger instance that recorded this event.

Kind: instance property of LoggingEvent

loggingEvent.message : String

The message logged.

Kind: instance property of LoggingEvent

loggingEvent.datetime : Number

The epoch time (number of milliseconds since 1/1/1970 UTC).

Kind: instance property of LoggingEvent

loggingEvent.toString([fmt]) ⇒ String

Converts the LoggingEvent instance to a formatted string. You can provide

Kind: instance method of LoggingEvent
Returns: String - A formatted string.

Param	Type	Default	Description
[fmt]	String	'%datetime% %level [%logger%]: %message%'	The string containing the tokens you wish to replace with the instance values.

Example

// using built-in formatting:
Loggers.asObservable()
  .subscribe(event => file.writeln(event.toString()));

Example

// using custom formatting:
let format = '[%datetime] %level%: %message%';
Loggers.asObservable()
  .byName('my.logger')
  .subscribe(event => file.writeln(event.toString(format)));