API.md

Classes

LogEntryOverride

A class for providing a way to quickly mutate the produced LogEntry during a single Log.xyz() call.

For example, say you want to add a field to a log entry after you call Log.error(ex) called errorNote. You do this by creating a LogEntryOverride instance and passing it as part of the Log.error() call as shown here...

    const override = new Log.LogEntryOverride({
        errorNote: 'This was an error.',
    });
    Log.error(ex,override);

Before the LogEntry is sent off to be written, the items passed into Log.xyz() will get scanned for overrides and those overrides merged intot he LogEntry. Then the resulting LogEntry will get sent to be written.

AwesomeLog

AwesomeLog is a singleton object returned when you const Log = require("@awesomeeng/awesome-log"). From it you can initialize and start your log service and then begin writing log messages out. Please see our extensive documentation for usage details.

LogLevel

Class for holding LogLevel names and their associated needs.

See our Log Levels documentation for more detials.

Interfaces

AbstractLogFormatter

Constructor for a Log Formatter.

It is important to note that this constructor is never called by you, but is instead called by AwesomeLog when the start() command is issued.

Your class must call this as shown here:

class MyFormatter extends AbstractLogFormatter {
     constructor(options) {
       super(options);
   ... your initialization code ...
 }

}

Failure to not do the super constructor will result in errors.

You should put any kind of initialization of your formatter in this constructor.

AbstractLogWriter

Constructor for a Log Writer.

It is important to note that this constructor is never called by you, but is instead called by AwesomeLog when the start() command is issued.

Your class must call this as shown here:

class MyWriter extends AbstractLogWriter {
     constructor(options) {
       super(options);
   ... your initialization code ...
 }

}

Failure to not do the super constructor will result in errors.

You should put any kind of initialization of your writer in this constructor.

AbstractLogFormatter

Constructor for a Log Formatter.

It is important to note that this constructor is never called by you, but is instead called by AwesomeLog when the start() command is issued.

Your class must call this as shown here:

class MyFormatter extends AbstractLogFormatter {
	 constructor(options) {
	   super(options);

	   ... your initialization code ...
	 }
}

Failure to not do the super constructor will result in errors.

You should put any kind of initialization of your formatter in this constructor.

Kind: global interface
See: Log Writer documentation for more details.

Param	Type
options	Object

• AbstractLogFormatter
  • .options ⇒ Object
  • .format(logentry) ⇒ Object

---

abstractLogFormatter.options ⇒ Object

Returns the options passed into the constructor.

Kind: instance property of AbstractLogFormatter

---

abstractLogFormatter.format(logentry) ⇒ Object

Called when a logentry needs to be formatted. The underlying writer will call this for each log message it needs to write out.

Kind: instance method of AbstractLogFormatter

Param	Type
logentry	Object

---

AbstractLogWriter

Constructor for a Log Writer.

It is important to note that this constructor is never called by you, but is instead called by AwesomeLog when the start() command is issued.

Your class must call this as shown here:

class MyWriter extends AbstractLogWriter {
	 constructor(options) {
	   super(options);

	   ... your initialization code ...
	 }
}

Failure to not do the super constructor will result in errors.

You should put any kind of initialization of your writer in this constructor.

Kind: global interface
See: Log Writer documentation for more details.

Param	Type
options	Object

• AbstractLogWriter
  • .options ⇒ Object
  • .write(message, logentry) ⇒ void
  • .flush() ⇒ void
  • .close() ⇒ void

---

abstractLogWriter.options ⇒ Object

Returns the Writer option passed in.

Kind: instance property of AbstractLogWriter

---

abstractLogWriter.write(message, logentry) ⇒ void

Expected to be overloaded in the implementing sub-class, this is called when a log message is to be written out by the writer. Log messages received at this point have already been checked as to if they are an allowed level and are already formatted as per the defined formatter.

The message parameter is the formatted message, returned from calling format(logentry).

The logentry parameter is the unformated log details.

Kind: instance method of AbstractLogWriter

Param	Type
message	*
logentry	Object

---

abstractLogWriter.flush() ⇒ void

Called to ensure that the writer has written all message out.

Kind: instance method of AbstractLogWriter

---

abstractLogWriter.close() ⇒ void

Called when the writer is closing and should be cleaned up. No Log messages will be received after this call has been made.

Kind: instance method of AbstractLogWriter

---

LogEntryOverride

A class for providing a way to quickly mutate the produced LogEntry during a single Log.xyz() call.

For example, say you want to add a field to a log entry after you call Log.error(ex) called errorNote. You do this by creating a LogEntryOverride instance and passing it as part of the Log.error() call as shown here...

	const override = new Log.LogEntryOverride({
		errorNote: 'This was an error.',
	});
	Log.error(ex,override);

Before the LogEntry is sent off to be written, the items passed into Log.xyz() will get scanned for overrides and those overrides merged intot he LogEntry. Then the resulting LogEntry will get sent to be written.

Kind: global class

---

AwesomeLog

AwesomeLog is a singleton object returned when you const Log = require("@awesomeeng/awesome-log"). From it you can initialize and start your log service and then begin writing log messages out. Please see our extensive documentation for usage details.

Kind: global class

• AwesomeLog
  • .LogEntryOverride ⇒ Class.<LogEntryOverride>
  • .AbstractLogWriter ⇒ Class.<AbstractLogWriter>
  • .AbstractLogFormatter ⇒ Class.<AbstractLogFormatter>
  • .initialized ⇒ boolean
  • .running ⇒ boolean
  • .config ⇒ Object
  • .history ⇒ Array
  • .historySizeLimit ⇒ number
  • .levels ⇒ Array.<LogLevel>
  • .levelNames ⇒ Array.<string>
  • .defineWriter(name, filename) ⇒ void
  • .defineFormatter(name, filename) ⇒ void
  • .init(config) ⇒ void
  • .start() ⇒ void
  • .stop() ⇒ void
  • .pause() ⇒ void
  • .resume() ⇒ void
  • .clearHistory() ⇒ AwesomeLog
  • .getLevel(level) ⇒ LogLevel
  • .log(level, text, ...args) ⇒ AwesomeLog
  • .captureSubProcess(subprocess) ⇒ AwesomeLog
  • .releaseSubProcess(subprocess) ⇒ AwesomeLog
  • .unrequire()

---

awesomeLog.LogEntryOverride ⇒ Class.<LogEntryOverride>

Returns the LogEntryOverride class for use mutating LogEntry objects after a call to Log.xyz().

Kind: instance property of AwesomeLog

---

awesomeLog.AbstractLogWriter ⇒ Class.<AbstractLogWriter>

Returns the AbstractLogWriter class for use in creating custom Log Writers.

Kind: instance property of AwesomeLog

---

awesomeLog.AbstractLogFormatter ⇒ Class.<AbstractLogFormatter>

Returns the AbstractLogFormatter class for use in creating custom Log Formatters.

Kind: instance property of AwesomeLog

---

awesomeLog.initialized ⇒ boolean

Returns true if Log.init() has been called.

Kind: instance property of AwesomeLog

---

awesomeLog.running ⇒ boolean

Returns true if Log.start() has been called.

Kind: instance property of AwesomeLog

---

awesomeLog.config ⇒ Object

Returns the configuration used by init(). This is a merge of the default configuration and the configuration passed into init().

Kind: instance property of AwesomeLog

---

awesomeLog.history ⇒ Array

Returns an array of the last N (defined by historySizeLimit) log messages.

Kind: instance property of AwesomeLog

---

awesomeLog.historySizeLimit ⇒ number

Returns the maximum number of history entries. This is set via init().

Kind: instance property of AwesomeLog

---

awesomeLog.levels ⇒ Array.<LogLevel>

Returns an array of LogLevel objects for the currently configured levels. Levels are configured via init().

Kind: instance property of AwesomeLog

---

awesomeLog.levelNames ⇒ Array.<string>

Returns an array of strings containing the level names, as taken from the LogLevel objects. Levels are configured via init().

Kind: instance property of AwesomeLog

---

awesomeLog.defineWriter(name, filename) ⇒ void

Map a new Log Writer to a specific filename, for usage in configuring AwesomeLog. The filename given must export a class that extends AbstractLogWriter.

Kind: instance method of AwesomeLog

Param	Type
name	string
filename	string

---

awesomeLog.defineFormatter(name, filename) ⇒ void

Map a new Log Formatter to a specific filename, for usage in configuring AwesomeLog. The filename given must export a class that extends AbstractLogFormatter.

Kind: instance method of AwesomeLog

Param	Type
name	string
filename	string

---

awesomeLog.init(config) ⇒ void

Initializes AwesomeLog for usage. This should be called very early in your application, in the entry point if possible.

You may only initialize if AwesomeLog is not running, which is done by calling start(), so do this before start().

This method takes an optional configuration object. This configuration object is merged with the default configuration to produce the overall configuration. Below is the default configuration values:

config = {
  buffering: false,
  separate: true,
  noDebugger: true,
  history: true,
  historySizeLimit: 100,
  historyFormatter: "default",
  historyFormatterOptions: {},
  levels: "access,error,warn,info,debug",
  disableLoggingNotices: false, // true if this is a child process
  loggingNoticesLevel: "info",
  fields: "timestamp,pid,system,level,text,args",
  writers: [],
  backlogSizeLimit: 1000,
  disableSubProcesses: false,
  scopeMap: null,
  scopeCatchAll: "info"
}

If no writers are provided, a default Console Writer is added to the configuration.

config.writers = [{
 type:  "default", // "subprocess" if this is a child process
 levels: "*",
 formatter: default", // "subprocess" if this is a child process
 options: {}
}];

Initialization is responsible for taking the config.levels parameters, transforming it into LogLevel objects, and ensuring that the log shortcut methods are created. See also @see ./docs/LogLevels.md

Kind: instance method of AwesomeLog

Param	Type
config	Object | null

---

awesomeLog.start() ⇒ void

Starts AwesomeLog running and outputting log messages. This should be called very early in your application, in the entry point if possible.

start() is responsible for initializing the writers.

If any backlog messages exist when start() is called, they will be written via the writers after they are started.

start() returns a promise, which allows it to be awaited using async/await. It is okay not to await for start to complete. AwesomeLog will still capture any log writes in its backlog and write them when start() is complete.

Kind: instance method of AwesomeLog

---

awesomeLog.stop() ⇒ void

Stops AwesomeLog running. Once stopped AwesomeLog can be reconfigured via another init() call.

stop() returns a promise, which allows it to be awaited using async/await. Generally it is okay to not await for stop() to complete.

Kind: instance method of AwesomeLog

---

awesomeLog.pause() ⇒ void

Puts AwesomeLog into a paused state which prevents any log messages from being written by the writers. Log messages received while paused are stored in the backlog and will be written when AwesomeLog is resumed.

Kind: instance method of AwesomeLog

---

awesomeLog.resume() ⇒ void

Exits the paused state and writes out any backlog messages.

Kind: instance method of AwesomeLog

---

awesomeLog.clearHistory() ⇒ AwesomeLog

Clears the stored history contents.

Kind: instance method of AwesomeLog

---

awesomeLog.getLevel(level) ⇒ LogLevel

For any given level string, return the associated LogLevel object.

Kind: instance method of AwesomeLog

Param	Type
level	string | LogLevel

---

awesomeLog.log(level, text, ...args) ⇒ AwesomeLog

Log a single messages.

log() is called by all other shortcut log methods.

Kind: instance method of AwesomeLog

Param	Type
level	string | LogLevel | LogEntry
text	string
...args	*

---

awesomeLog.captureSubProcess(subprocess) ⇒ AwesomeLog

Used when you create a new child process/cluster/worker thread if you intend AwesomeLog to be used in the process/cluster/worker and want the log information consolidated into a single AwesomeLog stream.

Kind: instance method of AwesomeLog
See: ./docs/ChildProcess.md

Param	Type
subprocess	ChildProcess.ChildProcess | Cluster.Worker | WorkerThread.Worker

---

awesomeLog.releaseSubProcess(subprocess) ⇒ AwesomeLog

Stops capturing a process/cluster/worker log messages.

Kind: instance method of AwesomeLog
See: ./docs/ChildProcess.md

Param	Type
subprocess	ChildProcess.ChildProcess | Cluster.Worker | WorkerThread.Worker

---

awesomeLog.unrequire()

Removes awesomelog global instace. used mostly in testing.

Kind: instance method of AwesomeLog

---

LogLevel

Class for holding LogLevel names and their associated needs.

See our Log Levels documentation for more detials.

Kind: global class

• LogLevel
  • new LogLevel(name)
  • .name ⇒ string
  • .toJSON() ⇒ string

---

new LogLevel(name)

Param	Type
name	string

---

logLevel.name ⇒ string

Return the LogLevel name, as a string. All upper case.

Kind: instance property of LogLevel

---

logLevel.toJSON() ⇒ string

Returns the LogLevel object as JSON string, which is just the name.

Kind: instance method of LogLevel

---