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)));