Bunyan stream that can be used to forward any bunyan messages to helix log.
Sends log messages to the coralogix logging service.
You can customize the host, application and subsystem per log message by specifying the appropriate fields.
Can be used as a base class/helper for implementing loggers.
This will first apply the filter, drop the message if the level is too low or if the filter returned undefined and will then call the subclass provided this._logImpl function for final processing.
This also wraps the entire logging logic into a promise enabled/async error handler that will log any errors using the rootLogger.
Can be used as a base class/helper for implementing loggers that require a formatter.
Will do the same processing as LoggerBase and in addition call
the formatter before invoking _logImpl.
Logger that is especially designed to be used in node.js
Print's to stderr; Marks errors, warns & debug messages
with a colored [ERROR]/... prefix.
Formatter MUST produce strings. Default formatter is messageFormatConsole.
Simple logger that forwards all messages to the underlying loggers.
This maintains an es6 map called loggers. Consumers of this API are explicitly permitted to mutate this map or replace it all together in order to add, remove or alter logger.
Logger specifically designed for logging to unix file descriptors.
This logger is synchronous: It uses blocking syscalls and thus guarantees that all data is written even if process.exit() is called immediately after logging. For normal files this is not a problem as linux will never block when writing to files, for sockets, pipes and ttys this might block the process for a considerable time.
Formatter MUST produce strings. Default formatter is messageFormatTechnical.
Logs messages to an in-memory buffer.
Formatter can be anything; default just logs the messages as-is.
Can be used as a base class/helper for implementing logging interfaces.
This will make sure that all the required fields are set to their default value, apply the filter, drop the message if the level is too low or if the filter returned undefined and will then forward the message to the logger configured.
This also wraps the entire logging logic into a promise enabled/async error handler that will log any errors using the rootLogger.
The fields interface provides the ability to conveniently specify both a message and custom fields to the underlying logger.
Special wrapper that should be used to protect secret values.
Effectively this tries to hide the actual payload so that the secret has to be explicitly extracted before using it.
const mySecret = new Secret(42); // Create a secret
mySecret.value; // => 42; extract the value
mySecret.value = 64; // assign a new valueThe secret can only be accessed through the .secret property in order to make sure that the access is not accidental; the secret property cannot be iterated over and the secret will not be leaked when converted to json or when printed.
Winston transport that forwards any winston log messages to the specified helix-log logger.
const winston = require('winston');
const { WinstonTransportInterface } = require('helix-log');
const myWinsonLogger = W.createLogger({
transports: [new WinstonTransportInterface()]
});
// Will log 'Hello World' to the rootLogger with the fields:
// {category: 'testing'}.
myWinsonLogger.info('Hello World', category: 'testing');The logger all other loggers attach to.
Must always contain a logger named 'default'; it is very much recommended that the default logger always be a console logger; this can serve as a good fallback in case other loggers fail.
Trait used to serialize json objects to json. See jsonifyForLog.
ObjectRemove the default fields emitted by buyan.
These fields are added by bunyan by default but are often not of
much interest (like name, bunyanLevel, or v) or can be easily added
again later for data based loggers where this information might be
valuable (e.g. hostname, pid).
Use like this:
numberThis can be used to convert a string log level into it's numeric equivalent. More pressing log levels have lower numbers.
MessageSupplies default values for all the required fields in log messages.
You may pass this a message that is just a string (as opposed to the usually required array of message components). The message will then automatically be wrapped in an array.
Wrapper around inspect that is extremely robust against errors during inspection.
Specifically designed to handle errors in toString() functions and custom inspect functions.
If any error is encountered a less informative string than a full
inspect is returned and the error is logged using err().
stringTurns the message field into a string.
MessageFormatter | stringSimple message format: Serializes the message and prefixes it with the log level.
This is used by the MemLogger by default for instance, because it is relatively easy to test with and contains no extra info.
MessageFormatter | stringMessage format that includes extra information; prefixes each message with the time stamp and the log level.
This is used by FileLogger by default for instance because if you work with many log files you need that sort of info.
MessageFormatter | stringMessage format with coloring/formatting escape codes
Designed for use in terminals.
MessageFormatter | ObjectUse jsonifyForLog to turn the fields into something that can be converted to json.
MessageFormatter | ObjectMessage format that produces & serialize json.
Really just an alias for JSON.stringify(messageFormatJson(fields)).
LoggerHelper function that creates a derived logger that is derived from a given logger, merging
the given options. All the properties are shallow copied to the new logger With the exception of
the defaultFields, where the defaultFields object itself is shallow-copied. Thus allowing to
extend the default fields.
MessageHelper to wrap any block of code and handle it's async & sync exceptions.
This will catch any exceptions/promise rejections and log them using the rootLogger.
Log just a message to the rootLogger using the SimpleInterface.
Alias for new SimpleInterface().log(...msg).
This is not a drop in replacement for console.log, since this
does not support string interpolation using %O/%f/..., but should
cover most use cases.
ObjectMessage format used for comparing logs in tests.
Pretty much just messageFormatJson, but removes the time stamp because that is hard to compare since it is different each time...
If other highly variable fields are added in the future (e.g. id = uuidgen()) these shall be removed too.
stringRecord the log files with debug granularity while the given function is running.
While the logger is recording, all other loggers are disabled. If this is not your desired behaviour, you can use the MemLogger manually.
Assert that a piece of code produces a specific set of log messages.
stringAsync variant of recordLogs.
Note that using this is a bit dangerous as other async procedures may also emit log messages while this procedure is running
Async variant of assertLogs
Note that using this is a bit dangerous as other async procedures may also emit logs while this async procedure is running.
*jsonify the given data using the JsonifyForLog trait.
Takes any javascript object and produces an object tree that only contains json compatible objects (objects, arrays, numbers, bools, strings and such).
This is a no-op if the input is already json compatible.
Note that this is specifically designed to serialize data for structured logging. This is NOT suitable for proper serialization of json; specifically this may loose information in cases where that makes sense.
Features a default converter for any exception/subclass of Error.
*Most loggers take a message with log(), encode it and write it to some
external resource.
E.g. most Loggers (like ConsoleLogger, FileLogger, ...) write to a text oriented resource, so the message needs to be converted to text. This is what the formatter is for.
Not all Loggers require text; some are field oriented (working with json compatible data), others like the MemLogger can handle arbitrary javascript objects, but still provide an optional formatter (in this case defaulted to the identity function – doing nothing) in case the user explicitly wishes to perform formatting.
Internally helix log passe these messages around.
Messages are just plain objects with some conventions regarding their fields:
Loggers are used to write log message.
These receive a message via their log() method and forward the message to some external resource or other loggers in the case of MultiLogger.
Loggers MUST provide a log(message) method accepting log messages.
Loggers SHOULD provide a constructor that can accept options as
the last argument new MyLogger(..args, { ...options });
Loggers MAY support any arguments or options in addition to the ones described here.
Loggers SHOULD NOT throw exceptions; instead they should log an error.
Loggers MUST use the optional fields & named options described in this interface either as specified here, or not at all.
Loggers SHOULD provide a named constructor option 'level' and associated field that can be used to limit logging to messages to those with a sufficiently high log level.
Loggers SHOULD provide a named constructor option 'filter' and associated field
that can be used to transform messages arbitrarily. This option should default to
the identity() function from ferrum. If the filter returns undefined
the message MUST be discarded.
Loggers SHOULD provide a named constructor option 'defaultFields'; if they do support the property they MUST perform a shallow merge/setdefault into the message AFTER applying the filters.
If loggers send messages to some external resource not supporting the Message format, they SHOULD also provide an option 'formatter' and associated field that is used to produce the external format. This formatter SHOULD be set to a sane default.
Helix-log provides some built-in formatters e.g. for plain text, json and for consoles supporting ANSI escape sequences.
Helix-Log LoggingInterfaces take messages as defined by some external interface, convert them to the internal Message format and forward them to a logger.
Some use cases include:
info("My", "Message") and info.fields("My", "Message", { cutsom: "fields" })
interfaces.LoggingInterfaces SHOULD provide a constructor that can accept options as
the last argument new MyInterface(..args, { ...options });
LoggingInterfaces MAY support any arguments or options in addition to the ones described here.a
LoggingInterfaces MUST use the optional fields & named options described in this LoggingInterface either as specified here, or not at all.
LoggingInterfaces SHOULD NOT throw exceptions; instead they should log errors using the global logger.
LoggingInterfaces SHOULD provide a named constructor option/field 'logger' that indicates which destination logs are sent to. This option SHOULD default to the rootLogger.
LoggingInterfaces SHOULD provide a named constructor option 'level' and associated field that can be used to limit logging to messages to those with a sufficiently high log level.
LoggingInterfaces SHOULD provide a named constructor option 'filter' and associated field
that can be used to transform messages arbitrarily. This option should default to
the identity() function from ferrum. If the filter returns undefined
the message MUST be discarded.
LoggingInterfaces SHOULD provide a named constructor option 'defaultFields'; if they do support the property they MUST perform a shallow merge/setdefault into the message AFTER applying the filters.
Logger](#Logger)
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
### logger.flush()
Flush the internal buffer.
Implementations of this SHOULD try to flush the underlying log sink if possible.
The returned promise SHOULD only fulfill if the flushing was done (best effort).
Note that implementations SHOULD use best effort to avoid buffering or the need for flushing.
However, there might be cases where this is not possible, for example when sending log messages
over the network.
**Kind**: instance method of [Logger](#Logger)
## LoggingInterface
Helix-Log LoggingInterfaces take messages as defined by some external interface,
convert them to the internal Message format and forward them to a logger.
Some use cases include:
- Providing a Console.log/warn/error compatible interface
- Providing winston or bunyan compatible logging API
- Providing a backend for forwarding bunyan or winston logs to helix log
- Receiving log messages over HTTP
- SimpleInterface and SimpleInterface are used to provide the
`info("My", "Message")` and `info.fields("My", "Message", { cutsom: "fields" })`
interfaces.
LoggingInterfaces SHOULD provide a constructor that can accept options as
the last argument `new MyInterface(..args, { ...options })`;
LoggingInterfaces MAY support any arguments or options in addition to the ones
described here.a
LoggingInterfaces MUST use the optional fields & named options described in this
LoggingInterface either as specified here, or not at all.
LoggingInterfaces SHOULD NOT throw exceptions; instead they should log errors using
the global logger.
LoggingInterfaces SHOULD provide a named constructor option/field 'logger' that indicates
which destination logs are sent to. This option SHOULD default to the rootLogger.
LoggingInterfaces SHOULD provide a named constructor option 'level' and associated field
that can be used to limit logging to messages to those with a sufficiently
high log level.
LoggingInterfaces SHOULD provide a named constructor option 'filter' and associated field
that can be used to transform messages arbitrarily. This option should default to
the `identity()` function from ferrum. If the filter returns `undefined`
the message MUST be discarded.
LoggingInterfaces SHOULD provide a named constructor option 'defaultFields'; if they do support
the property they MUST perform a shallow merge/setdefault into the message AFTER applying the
filters.
**Kind**: global interface
## The default constructor can be used to get the current point in time as a BigDate.
**Kind**: global class
**Implements**: Equals, Deepclone, Shallowclone
### new The default constructor can be used to get the current point in time as a BigDate.(Converts, Construct, Construct, ...Can)
A Date class capable of storing timestamps at arbitrary precisions that can
be used as a drop-in replacement for date.
When generating timestamps at quick succession `Date` will often yield the
same result:
```js
const assert = require('assert');
const a = new Date();
const b = new Date();
assert.strictEqual(a.toISOString(), b.toISOString())
```
This is often problematic. E.g. in the case of helix-log this can lead to log
messages being displayed out of order. Using `process.hrtime()` is not an option
either because it's time stamps are only really valid on the same process.
In order to remedy this problem, helix-log was created: It measures time at a very
high precision (nano seconds) while maintaining a reference to corordinated universal time
```js
const assert = require('assert');
const { BigDate } = require('@adobe/helixLog')
const a = new BigDate();
const b = new BigDate();
assert.notStrictEqual(a.toISOString(), b.toISOString());
```
# Precision in relation to Corordinated Universal Time
Mostly depends on how well synchronized the system clock is…usually between 20ms and 200ms.
This goes for both Date as well as BigDate, although BigDate can add up to 1ms of extra error.
# Precision in relation to Date
BigDate can add up to 1ms out of sync with Date.
When measuring comparing `BigDate.preciseTime()` and `Date.getTime()` you may
find differences of up to 2.5ms due to the imprecision of measurement.
# Precision in relation to hrtime()
Using BigDate::fromHrtime() you can convert hrtime timestamps to BigDate.
The conversion should be 1 to 1 (BigDate uses hrtime internally), but the
internal reference will be recalculated every time the clock jumps (e.g on
hibernation or when the administrator adjusts the time). This can lead to
fromHrtime interpreting timestamps vastly different before and after the jump.
# For benchmarking/measurement overhead
BigDate can be used for benchmarking and is better at it than Date and worse at it than hrtime.
Measuring the actual overhead proofed difficult, because results where vastly different
depending on how often hrtime was called.
| Worst | Cold | Hot | Best
-------- | ----- | ----- | ----- | -----
Hrtime | 10µs | 20µs | 1.5µs | 80ns
BigDate | 500µs | 80µs | 4µs | 250ns
Worst: First few invocations, bad luck
Cold: Typical first few invocations.
Hot: After tens to hundreds of invocations
Best: After millions of invocations
| Param | Type | Description |
| --- | --- | --- |
| Converts | Date \| BigDate | a Date to a BigDate or copies a BigDate |
| Construct | String | a BigDate from a string (like date, but supports arbitrary precision in the ISO 8601 String decimal places) |
| Construct | Number \| Big \| Bigint | a BigDate from the epoch value (unix time/number of milliseconds elapsed sinc 1970-01-01). Decimal places are honored and can be used to supply an epoch value of arbitrary precision. |
| ...Can | \* | be used to construct a BigDate from components (year, month, day, hours, minutes, seconds, milliseconds with decimal places) |
## BunyanStreamInterface
Bunyan stream that can be used to forward any bunyan messages
to helix log.
**Kind**: global class
**Implements**: [LoggingInterface](#LoggingInterface)
## CoralogixLogger
Sends log messages to the coralogix logging service.
You can customize the host, application and subsystem per log
message by specifying the appropriate fields.
**Kind**: global class
**Implements**: [Logger](#Logger)
* [CoralogixLogger](#CoralogixLogger)
* [new CoralogixLogger(apikey, app, subsystem)](#new_CoralogixLogger_new)
* [.apikey](#CoralogixLogger+apikey) : [Secret](#Secret)
* [.app](#CoralogixLogger+app) : string
* [.subsystem](#CoralogixLogger+subsystem) : string
* [.host](#CoralogixLogger+host) : string
* [.flush()](#CoralogixLogger+flush)
### new CoralogixLogger(apikey, app, subsystem)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| apikey | string \| [Secret](#Secret) | | – Your coralogix api key |
| app | string | | – Name of the app under which the log messages should be categorized |
| subsystem | string | | – Name of the subsystem under which |
| [opts.host] | string | "os.hostname()" | The hostname under which to categorize the messages |
| [opts.apiurl] | string | "'https://api.coralogix.com/api/v1/'" | where the coralogix api can be found; for testing; where the coralogix api can be found; for testing |
### coralogixLogger.apikey : [Secret](#Secret)
Name of the app under which the log messages should be categorized
**Kind**: instance property of [CoralogixLogger](#CoralogixLogger)
### coralogixLogger.app : string
Name of the app under which the log messages should be categorized
**Kind**: instance property of [CoralogixLogger](#CoralogixLogger)
### coralogixLogger.subsystem : string
Name of the subsystem under which the log messages should be categorized
**Kind**: instance property of [CoralogixLogger](#CoralogixLogger)
### coralogixLogger.host : string
The hostname under which to categorize the messages
**Kind**: instance property of [CoralogixLogger](#CoralogixLogger)
### coralogixLogger.flush()
Flush the internal buffer.
Implementations of this SHOULD try to flush the underlying log sink if possible.
The returned promise SHOULD only fulfill if the flushing was done (best effort).
Note that implementations SHOULD use best effort to avoid buffering or the need for flushing.
However, there might be cases where this is not possible, for example when sending log messages
over the network.
**Kind**: instance method of [CoralogixLogger](#CoralogixLogger)
**Implements**: [flush](#Logger+flush)
## LoggerBase
Can be used as a base class/helper for implementing loggers.
This will first apply the filter, drop the message if the level is
too low or if the filter returned undefined and will then call the
subclass provided this._logImpl function for final processing.
This also wraps the entire logging logic into a promise enabled/async
error handler that will log any errors using the rootLogger.
**Kind**: global class
* [LoggerBase](#LoggerBase)
* [new LoggerBase(opts)](#new_LoggerBase_new)
* [.level](#LoggerBase+level) : string
* [.filter](#LoggerBase+filter) : function
### new LoggerBase(opts)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| opts | Object | | – Optional, named parameters |
| [opts.level] | string | "'silly'" | The minimum log level to sent to loggly |
| [opts.filter] | function | identity | Will be given every log message to perform arbitrary transformations; must return either another valid message object or undefined (in which case the message will be dropped). |
**Example**
```
class MyConsoleLogger extends LoggerBase {
_logImpl(fields) {
console.log(fields);
}
}
```
### loggerBase.level : string
The minimum log level for messages to be printed.
Feel free to change to one of the available levels.
**Kind**: instance property of [LoggerBase](#LoggerBase)
### loggerBase.filter : function
Used to optionally transform all messages.
Takes a message and returns a transformed message
or undefined (in which case the message will be dropped).
**Kind**: instance property of [LoggerBase](#LoggerBase)
## FormattedLoggerBase
Can be used as a base class/helper for implementing loggers that
require a formatter.
Will do the same processing as `LoggerBase` and in addition call
the formatter before invoking _logImpl.
**Kind**: global class
* [FormattedLoggerBase](#FormattedLoggerBase)
* [new FormattedLoggerBase()](#new_FormattedLoggerBase_new)
* [.formatter](#FormattedLoggerBase+formatter) : [MessageFormatter](#MessageFormatter)
### new FormattedLoggerBase()
| Param | Type | Description |
| --- | --- | --- |
| [opts.formatter] | function | In addition to the filter, the formatter will be used to convert the message into a format compatible with the external resource. |
**Example**
```
class MyConsoleLogger extends FormattedLoggerBase {
_logImpl(payload, fields) {
console.log(`[${fields.level}]`, payload);
}
}
```
### formattedLoggerBase.formatter : [MessageFormatter](#MessageFormatter)
Formatter used to format all the messages.
Must yield an object suitable for the external resource
this logger writes to.
**Kind**: instance property of [FormattedLoggerBase](#FormattedLoggerBase)
## ConsoleLogger
Logger that is especially designed to be used in node.js
Print's to stderr; Marks errors, warns & debug messages
with a colored `[ERROR]`/... prefix.
Formatter MUST produce strings. Default formatter is messageFormatConsole.
**Kind**: global class
**Implements**: [Logger](#Logger)
* [ConsoleLogger](#ConsoleLogger)
* [new ConsoleLogger()](#new_ConsoleLogger_new)
* [.stream](#ConsoleLogger+stream) : Writable
### new ConsoleLogger()
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [opts.stream] | Writable | console._stderr | A writable stream to log to. |
### consoleLogger.stream : Writable
Writable stream to write log messages to. Usually console._stderr.
**Kind**: instance property of [ConsoleLogger](#ConsoleLogger)
## MultiLogger
Simple logger that forwards all messages to the underlying loggers.
This maintains an es6 map called loggers. Consumers of this API are
explicitly permitted to mutate this map or replace it all together in
order to add, remove or alter logger.
**Kind**: global class
**Implements**: [Logger](#Logger)
**Parameter**: Sequence<Loggers> loggers – The loggers to forward to.
### multiLogger.flush()
Flush the internal buffer.
Implementations of this SHOULD try to flush the underlying log sink if possible.
The returned promise SHOULD only fulfill if the flushing was done (best effort).
Note that implementations SHOULD use best effort to avoid buffering or the need for flushing.
However, there might be cases where this is not possible, for example when sending log messages
over the network.
**Kind**: instance method of [MultiLogger](#MultiLogger)
**Implements**: [flush](#Logger+flush)
## FileLogger
Logger specifically designed for logging to unix file descriptors.
This logger is synchronous: It uses blocking syscalls and thus guarantees
that all data is written even if process.exit() is called immediately after
logging.
For normal files this is not a problem as linux will never block when writing
to files, for sockets, pipes and ttys this might block the process for a considerable
time.
Formatter MUST produce strings. Default formatter is messageFormatTechnical.
**Kind**: global class
**Implements**: [Logger](#Logger)
* [FileLogger](#FileLogger)
* [new FileLogger(name)](#new_FileLogger_new)
* [.fd](#FileLogger+fd) : Integer
### new FileLogger(name)
| Param | Type | Description |
| --- | --- | --- |
| name | string \| Integer | The path of the file to log to OR the unix file descriptor to log to. |
### fileLogger.fd : Integer
The underlying operating system file descriptor.
**Kind**: instance property of [FileLogger](#FileLogger)
## MemLogger
Logs messages to an in-memory buffer.
Formatter can be anything; default just logs the messages as-is.
**Kind**: global class
**Implements**: [Logger](#Logger)
### memLogger.buf : Array
An array that holds all the messages logged thus far.
May be modified An array that holds all the messages logged thus far.
May be modified.
**Kind**: instance property of [MemLogger](#MemLogger)
## InterfaceBase
Can be used as a base class/helper for implementing logging interfaces.
This will make sure that all the required fields are set to their
default value, apply the filter, drop the message if the level is
too low or if the filter returned undefined and will then forward
the message to the logger configured.
This also wraps the entire logging logic into a promise enabled/async
error handler that will log any errors using the rootLogger.
**Kind**: global class
### new InterfaceBase(opts)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| opts | Object | | – Optional, named parameters |
| [opts.level] | string | "'silly'" | The minimum log level to sent to the logger |
| [opts.logger] | [Logger](#Logger) | rootLogger | The helix logger to use |
| [opts.filter] | function | identity | Will be given every log message to perform arbitrary transformations; must return either another valid message object or undefined (in which case the message will be dropped). |
| [opts.defaultFields] | object | | Additional log fields to add to every log message. |
**Example**
```
class MyTextInterface extends InterfaceBase {
logText(str) {
this._logImpl({ message: [str] });
}
};
const txt = new MyTextInterface({ logger: rootLogger });
txt.logText("Hello World");
```
## SimpleInterface
The fields interface provides the ability to conveniently
specify both a message and custom fields to the underlying logger.
**Kind**: global class
**Implements**: [LoggingInterface](#LoggingInterface)
### simpleInterface.fatal(...msg)
These methods are used to log just a message with no custom
fields to the underlying logger; similar to console.log.
This is not a drop in replacement for console.log, since this
does not support string interpolation using `%O/%f/...`, but should
cover most use cases.
**Kind**: instance method of [SimpleInterface](#SimpleInterface)
| Param | Type | Description |
| --- | --- | --- |
| ...msg | \* | The message to write |
## Secret
Special wrapper that should be used to protect secret values.
Effectively this tries to hide the actual payload so that the
secret has to be explicitly extracted before using it.
```
const mySecret = new Secret(42); // Create a secret
mySecret.value; // => 42; extract the value
mySecret.value = 64; // assign a new value
```
The secret can only be accessed through the .secret property
in order to make sure that the access is not accidental;
the secret property cannot be iterated over and the secret will
not be leaked when converted to json or when printed.
**Kind**: global class
## WinstonTransportInterface
Winston transport that forwards any winston log messages to
the specified helix-log logger.
```
const winston = require('winston');
const { WinstonTransportInterface } = require('helix-log');
const myWinsonLogger = W.createLogger({
transports: [new WinstonTransportInterface()]
});
// Will log 'Hello World' to the rootLogger with the fields:
// {category: 'testing'}.
myWinsonLogger.info('Hello World', category: 'testing');
```
**Kind**: global class
**Implements**: WinstonTransport, [LoggingInterface](#LoggingInterface)
### new WinstonTransportInterface(opts)
| Param | Type | Description |
| --- | --- | --- |
| opts | Object | – Options as specified by WinstonTransport AND by LoggingInterface; both sets of options are supported |
| opts.level | String | – This is the level as specified by WinstonTransport. If your winston instance uses custom log levels not supported by helix-log you can use the filter to map winston log levels to helix log ones. |
## rootLogger
The logger all other loggers attach to.
Must always contain a logger named 'default'; it is very much recommended
that the default logger always be a console logger; this can serve as a good
fallback in case other loggers fail.
**Kind**: global constant
**Example**
```js
// Change the default logger
rootLogger.loggers.set('default', new ConsoleLogger({level: 'debug'}));
```
You should not log to the root logger directly; instead use one of the
wrapper functions `log, fatal, err, warn, info, verbose, debug`; they
perform some additional
## JsonifyForLog
Trait used to serialize json objects to json. See jsonifyForLog.
**Kind**: global constant
## eraseBunyanDefaultFields(fields) ⇒ Object
Remove the default fields emitted by buyan.
These fields are added by bunyan by default but are often not of
much interest (like name, bunyanLevel, or `v`) or can be easily added
again later for data based loggers where this information might be
valuable (e.g. hostname, pid).
Use like this:
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | Object |
**Example**
```
const bunyan = require('bunyan');
const { BunyanStreamInterface, eraseBunyanDefaultFields } = require('helix-log');
const logger = bunyan.createLogger({name: 'helixLogger'});
logger.addStream(BunyanStreamInterface.createStream({
filter: eraseBunyanDefaultFields
}));
```
## numericLogLevel(name) ⇒ number
This can be used to convert a string log level into it's
numeric equivalent. More pressing log levels have lower numbers.
**Kind**: global function
**Returns**: number - The numeric log level
**Throws**:
- Error If the given log level name is invalid.
| Param | Type | Description |
| --- | --- | --- |
| name | string | Name of the log level |
## makeLogMessage([fields]) ⇒ [Message](#Message)
Supplies default values for all the required fields in log messages.
You may pass this a message that is just a string (as opposed to the
usually required array of message components). The message will then automatically
be wrapped in an array.
**Kind**: global function
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [fields] | Object | {} | User supplied field values; can overwrite any default values |
## tryInspect(what, opts)
Wrapper around inspect that is extremely robust against errors
during inspection.
Specifically designed to handle errors in toString() functions
and custom inspect functions.
If any error is encountered a less informative string than a full
inspect is returned and the error is logged using `err()`.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| what | \* | The object to inspect |
| opts | Object | Options will be passed through to inspect. Note that these may be ignored if there is an error during inspect(). |
## serializeMessage(msg, opts) ⇒ string
Turns the message field into a string.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| msg | Array.<\*> \| undefined | – Message components to serialize |
| opts | Object | – Parameters are forwarded to tryInspect() |
## messageFormatSimple(fields) ⇒ [MessageFormatter](#MessageFormatter) \| string
Simple message format: Serializes the message and prefixes it with
the log level.
This is used by the MemLogger by default for instance, because it is relatively
easy to test with and contains no extra info.
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
## messageFormatTechnical(fields) ⇒ [MessageFormatter](#MessageFormatter) \| string
Message format that includes extra information; prefixes each message
with the time stamp and the log level.
This is used by FileLogger by default for instance because if you
work with many log files you need that sort of info.
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
## messageFormatConsole(fields) ⇒ [MessageFormatter](#MessageFormatter) \| string
Message format with coloring/formatting escape codes
Designed for use in terminals.
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
## messageFormatJson(fields) ⇒ [MessageFormatter](#MessageFormatter) \| Object
Use jsonifyForLog to turn the fields into something that
can be converted to json.
**Kind**: global function
**Oaram**: [Message](#Message) message the log message
| Param | Type | Description |
| --- | --- | --- |
| fields | \* | additional log fields |
## messageFormatJsonString(fields) ⇒ [MessageFormatter](#MessageFormatter) \| Object
Message format that produces & serialize json.
Really just an alias for `JSON.stringify(messageFormatJson(fields))`.
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
## deriveLogger(logger, opts) ⇒ [Logger](#Logger)
Helper function that creates a derived logger that is derived from a given logger, merging
the given options. All the properties are shallow copied to the new logger With the exception of
the `defaultFields`, where the `defaultFields` object itself is shallow-copied. Thus allowing to
_extend_ the default fields.
**Kind**: global function
**Returns**: [Logger](#Logger) - A new logger with updated options.
| Param | Type | Description |
| --- | --- | --- |
| logger | [Logger](#Logger) | the logger to derive from. |
| opts | object | Options to merge with this logger |
## \_\_handleLoggingExceptions(fields, logger, code) ⇒ [Message](#Message)
Helper to wrap any block of code and handle it's async & sync exceptions.
This will catch any exceptions/promise rejections and log them using the rootLogger.
**Kind**: global function
**Access**: package
| Param | Type | Description |
| --- | --- | --- |
| fields | Object | Fields to set in any error message (usually indicates which logger was used) |
| logger | [Logger](#Logger) | the logger to wrap |
| code | function | The code to wrap |
## fatal(...msg)
Log just a message to the rootLogger using the SimpleInterface.
Alias for `new SimpleInterface().log(...msg)`.
This is not a drop in replacement for console.log, since this
does not support string interpolation using `%O/%f/...`, but should
cover most use cases.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| ...msg | \* | The message to write |
## messageFormatJsonStatic(fields) ⇒ Object
Message format used for comparing logs in tests.
Pretty much just messageFormatJson, but removes the time stamp
because that is hard to compare since it is different each time...
If other highly variable fields are added in the future (e.g. id = uuidgen())
these shall be removed too.
**Kind**: global function
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |
## recordLogs(opts, fn) ⇒ string
Record the log files with debug granularity while the given function is running.
While the logger is recording, all other loggers are disabled.
If this is not your desired behaviour, you can use the MemLogger
manually.
**Kind**: global function
**Returns**: string - The logs that where produced by the codee
| Param | Type | Description |
| --- | --- | --- |
| opts | Object | – optional first parameter; options passed to MemLogger |
| fn | function | The logs that this code emits will be recorded. |
**Example**
```
recordLogs(() => {
info('Hello World');
err('Nooo');
});
```
will return something like this:
```
[
{ level: 'info', message: 'Hello World', timestamp: '...' },
{ level: 'error', message: 'Noo', timestamp: '...' }
]
```
## assertLogs(opts, fn, logs)
Assert that a piece of code produces a specific set of log messages.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| opts | Object | – optional first parameter; options passed to MemLogger |
| fn | function | The logs that this code emits will be recorded. |
| logs | string | |
**Example**
```
const { assertLogs, info, err } = require('@adobe/helix-shared').log;
assertLogs(() => {
info('Hello World');
err('Nooo');
}, [
{ level: 'info', message: 'Hello World' },
{ level: 'error', message: 'Noo' }
]);
```
## recordAsyncLogs(opts, fn) ⇒ string
Async variant of recordLogs.
Note that using this is a bit dangerous as other async procedures
may also emit log messages while this procedure is running
**Kind**: global function
**Returns**: string - The logs that where produced by the code
| Param | Type | Description |
| --- | --- | --- |
| opts | Object | – optional first parameter; options passed to MemLogger |
| fn | function | The logs that this code emits will be recorded. |
## assertAsyncLogs(opts, fn, logs)
Async variant of assertLogs
Note that using this is a bit dangerous as other async procedures
may also emit logs while this async procedure is running.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| opts | Object | – optional first parameter; options passed to MemLogger |
| fn | function | The logs that this code emits will be recorded. |
| logs | string | |
## jsonifyForLog(what) ⇒ \*
jsonify the given data using the JsonifyForLog trait.
Takes any javascript object and produces an object tree
that only contains json compatible objects (objects, arrays,
numbers, bools, strings and such).
This is a no-op if the input is already json compatible.
Note that this is specifically designed to serialize data for structured
logging. This is NOT suitable for proper serialization of json; specifically
this may loose information in cases where that makes sense.
Features a default converter for any exception/subclass of Error.
**Kind**: global function
**Returns**: \* - Json compatible object
**Throws**:
- TraitNotImplemented If any object in the given object tree
can not be converted to json-compatible
| Param | Type | Description |
| --- | --- | --- |
| what | \* | The object to convert |
## MessageFormatter ⇒ \*
Most loggers take a message with `log()`, encode it and write it to some
external resource.
E.g. most Loggers (like ConsoleLogger, FileLogger, ...) write to a text
oriented resource, so the message needs to be converted to text. This is
what the formatter is for.
Not all Loggers require text; some are field oriented (working with json
compatible data), others like the MemLogger can handle arbitrary javascript
objects, but still provide an optional formatter (in this case defaulted to
the identity function – doing nothing) in case the user explicitly wishes
to perform formatting.
**Kind**: global typedef
**Returns**: \* - Whatever kind of type the Logger needs. Usually a string.
| Param | Type |
| --- | --- |
| fields | [Message](#Message) |