Bunyan stream that can be used to forward any bunyan messages\nto helix log.
\nSends log messages to the coralogix logging service.
\nYou can customize the host, application and subsystem per log\nmessage by specifying the appropriate fields.
\nCan be used as a base class/helper for implementing loggers.
\nThis will first apply the filter, drop the message if the level is\ntoo low or if the filter returned undefined and will then call the\nsubclass provided this._logImpl function for final processing.
\nThis also wraps the entire logging logic into a promise enabled/async\nerror handler that will log any errors using the rootLogger.
\nCan be used as a base class/helper for implementing loggers that\nrequire a formatter.
\nWill do the same processing as LoggerBase and in addition call\nthe formatter before invoking _logImpl.
Logger that is especially designed to be used in node.js\nPrint's to stderr; Marks errors, warns & debug messages\nwith a colored [ERROR]/... prefix.
Formatter MUST produce strings. Default formatter is messageFormatConsole.
\nSimple logger that forwards all messages to the underlying loggers.
\nThis maintains an es6 map called loggers. Consumers of this API are\nexplicitly permitted to mutate this map or replace it all together in\norder to add, remove or alter logger.
\nLogger specifically designed for logging to unix file descriptors.
\nThis logger is synchronous: It uses blocking syscalls and thus guarantees\nthat all data is written even if process.exit() is called immediately after\nlogging.\nFor normal files this is not a problem as linux will never block when writing\nto files, for sockets, pipes and ttys this might block the process for a considerable\ntime.
\nFormatter MUST produce strings. Default formatter is messageFormatTechnical.
\nLogs messages to an in-memory buffer.
\nFormatter can be anything; default just logs the messages as-is.
\nCan be used as a base class/helper for implementing logging interfaces.
\nThis will make sure that all the required fields are set to their\ndefault value, apply the filter, drop the message if the level is\ntoo low or if the filter returned undefined and will then forward\nthe message to the logger configured.
\nThis also wraps the entire logging logic into a promise enabled/async\nerror handler that will log any errors using the rootLogger.
\nThe fields interface provides the ability to conveniently\nspecify both a message and custom fields to the underlying logger.
\nSpecial wrapper that should be used to protect secret values.
\nEffectively this tries to hide the actual payload so that the\nsecret has to be explicitly extracted before using it.
\nconst mySecret = new Secret(42); // Create a secret\nmySecret.value; // => 42; extract the value\nmySecret.value = 64; // assign a new valueThe secret can only be accessed through the .secret property\nin order to make sure that the access is not accidental;\nthe secret property cannot be iterated over and the secret will\nnot be leaked when converted to json or when printed.
\nWinston transport that forwards any winston log messages to\nthe specified helix-log logger.
\nconst winston = require('winston');\nconst { WinstonTransportInterface } = require('helix-log');\n\nconst myWinsonLogger = W.createLogger({\n transports: [new WinstonTransportInterface()]\n});\n\n// Will log 'Hello World' to the rootLogger with the fields:\n// {category: 'testing'}.\nmyWinsonLogger.info('Hello World', category: 'testing');The logger all other loggers attach to.
\nMust always contain a logger named 'default'; it is very much recommended\nthat the default logger always be a console logger; this can serve as a good\nfallback in case other loggers fail.
\nTrait used to serialize json objects to json. See jsonifyForLog.
\nObjectRemove the default fields emitted by buyan.
\nThese fields are added by bunyan by default but are often not of\nmuch interest (like name, bunyanLevel, or v) or can be easily added\nagain later for data based loggers where this information might be\nvaluable (e.g. hostname, pid).
Use like this:
\nnumberThis can be used to convert a string log level into it's\nnumeric equivalent. More pressing log levels have lower numbers.
\nMessageSupplies default values for all the required fields in log messages.
\nYou may pass this a message that is just a string (as opposed to the\nusually required array of message components). The message will then automatically\nbe wrapped in an array.
\nWrapper around inspect that is extremely robust against errors\nduring inspection.
\nSpecifically designed to handle errors in toString() functions\nand custom inspect functions.
\nIf any error is encountered a less informative string than a full\ninspect is returned and the error is logged using err().
stringTurns the message field into a string.
\nMessageFormatter | stringSimple message format: Serializes the message and prefixes it with\nthe log level.
\nThis is used by the MemLogger by default for instance, because it is relatively\neasy to test with and contains no extra info.
\nMessageFormatter | stringMessage format that includes extra information; prefixes each message\nwith the time stamp and the log level.
\nThis is used by FileLogger by default for instance because if you\nwork with many log files you need that sort of info.
\nMessageFormatter | stringMessage format with coloring/formatting escape codes
\nDesigned for use in terminals.
\nMessageFormatter | ObjectUse jsonifyForLog to turn the fields into something that\ncan be converted to json.
\nMessageFormatter | ObjectMessage format that produces & serialize json.
\nReally just an alias for JSON.stringify(messageFormatJson(fields)).
LoggerHelper function that creates a derived logger that is derived from a given logger, merging\nthe given options. All the properties are shallow copied to the new logger With the exception of\nthe defaultFields, where the defaultFields object itself is shallow-copied. Thus allowing to\nextend the default fields.
MessageHelper to wrap any block of code and handle it's async & sync exceptions.
\nThis will catch any exceptions/promise rejections and log them using the rootLogger.
\nLog just a message to the rootLogger using the SimpleInterface.
\nAlias for new SimpleInterface().log(...msg).
This is not a drop in replacement for console.log, since this\ndoes not support string interpolation using %O/%f/..., but should\ncover most use cases.
ObjectMessage format used for comparing logs in tests.
\nPretty much just messageFormatJson, but removes the time stamp\nbecause that is hard to compare since it is different each time...
\nIf other highly variable fields are added in the future (e.g. id = uuidgen())\nthese shall be removed too.
\nstringRecord the log files with debug granularity while the given function is running.
\nWhile the logger is recording, all other loggers are disabled.\nIf this is not your desired behaviour, you can use the MemLogger\nmanually.
\nAssert that a piece of code produces a specific set of log messages.
\nstringAsync variant of recordLogs.
\nNote that using this is a bit dangerous as other async procedures\nmay also emit log messages while this procedure is running
\nAsync variant of assertLogs
\nNote that using this is a bit dangerous as other async procedures\nmay also emit logs while this async procedure is running.
\n*jsonify the given data using the JsonifyForLog trait.
\nTakes any javascript object and produces an object tree\nthat only contains json compatible objects (objects, arrays,\nnumbers, bools, strings and such).
\nThis is a no-op if the input is already json compatible.
\nNote that this is specifically designed to serialize data for structured\nlogging. This is NOT suitable for proper serialization of json; specifically\nthis may loose information in cases where that makes sense.
\nFeatures a default converter for any exception/subclass of Error.
\n*Most loggers take a message with log(), encode it and write it to some\nexternal resource.
E.g. most Loggers (like ConsoleLogger, FileLogger, ...) write to a text\noriented resource, so the message needs to be converted to text. This is\nwhat the formatter is for.
\nNot all Loggers require text; some are field oriented (working with json\ncompatible data), others like the MemLogger can handle arbitrary javascript\nobjects, but still provide an optional formatter (in this case defaulted to\nthe identity function – doing nothing) in case the user explicitly wishes\nto perform formatting.
\nInternally helix log passe these messages around.
\nMessages are just plain objects with some conventions\nregarding their fields:
\nLoggers are used to write log message.
\nThese receive a message via their log() method and forward\nthe message to some external resource or other loggers in\nthe case of MultiLogger.
\nLoggers MUST provide a log(message) method accepting log messages.
Loggers SHOULD provide a constructor that can accept options as\nthe last argument new MyLogger(..args, { ...options });
Loggers MAY support any arguments or options in addition to the ones\ndescribed here.
\nLoggers SHOULD NOT throw exceptions; instead they should log an error.
\nLoggers MUST use the optional fields & named options described in this\ninterface either as specified here, or not at all.
\nLoggers SHOULD provide a named constructor option 'level' and associated field\nthat can be used to limit logging to messages to those with a sufficiently\nhigh log level.
\nLoggers SHOULD provide a named constructor option 'filter' and associated field\nthat can be used to transform messages arbitrarily. This option should default to\nthe identity() function from ferrum. If the filter returns undefined\nthe message MUST be discarded.
Loggers SHOULD provide a named constructor option 'defaultFields'; if they do support the\nproperty they MUST perform a shallow merge/setdefault into the message AFTER applying the\nfilters.
\nIf loggers send messages to some external resource not supporting the Message\nformat, they SHOULD also provide an option 'formatter' and associated field\nthat is used to produce the external format. This formatter SHOULD be set\nto a sane default.
\nHelix-log provides some built-in formatters e.g. for plain text, json and\nfor consoles supporting ANSI escape sequences.
\nHelix-Log LoggingInterfaces take messages as defined by some external interface,\nconvert them to the internal Message format and forward them to a logger.
\nSome use cases include:
\ninfo("My", "Message") and info.fields("My", "Message", { cutsom: "fields" })\ninterfaces.LoggingInterfaces SHOULD provide a constructor that can accept options as\nthe last argument new MyInterface(..args, { ...options });
LoggingInterfaces MAY support any arguments or options in addition to the ones\ndescribed here.a
\nLoggingInterfaces MUST use the optional fields & named options described in this\nLoggingInterface either as specified here, or not at all.
\nLoggingInterfaces SHOULD NOT throw exceptions; instead they should log errors using\nthe global logger.
\nLoggingInterfaces SHOULD provide a named constructor option/field 'logger' that indicates\nwhich destination logs are sent to. This option SHOULD default to the rootLogger.
\nLoggingInterfaces SHOULD provide a named constructor option 'level' and associated field\nthat can be used to limit logging to messages to those with a sufficiently\nhigh log level.
\nLoggingInterfaces SHOULD provide a named constructor option 'filter' and associated field\nthat can be used to transform messages arbitrarily. This option should default to\nthe identity() function from ferrum. If the filter returns undefined\nthe message MUST be discarded.
LoggingInterfaces SHOULD provide a named constructor option 'defaultFields'; if they do support\nthe property they MUST perform a shallow merge/setdefault into the message AFTER applying the\nfilters.
\nLogger](#Logger) \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n### logger.flush()\nFlush the internal buffer.\n\nImplementations of this SHOULD try to flush the underlying log sink if possible.\nThe returned promise SHOULD only fulfill if the flushing was done (best effort).\n\nNote that implementations SHOULD use best effort to avoid buffering or the need for flushing.\nHowever, there might be cases where this is not possible, for example when sending log messages\nover the network.\n\n**Kind**: instance method of [Logger](#Logger) \n\n\n## LoggingInterface\nHelix-Log LoggingInterfaces take messages as defined by some external interface,\nconvert them to the internal Message format and forward them to a logger.\n\nSome use cases include:\n\n- Providing a Console.log/warn/error compatible interface\n- Providing winston or bunyan compatible logging API\n- Providing a backend for forwarding bunyan or winston logs to helix log\n- Receiving log messages over HTTP\n- SimpleInterface and SimpleInterface are used to provide the\n `info(\"My\", \"Message\")` and `info.fields(\"My\", \"Message\", { cutsom: \"fields\" })`\n interfaces.\n\nLoggingInterfaces SHOULD provide a constructor that can accept options as\nthe last argument `new MyInterface(..args, { ...options })`;\n\nLoggingInterfaces MAY support any arguments or options in addition to the ones\ndescribed here.a\n\nLoggingInterfaces MUST use the optional fields & named options described in this\nLoggingInterface either as specified here, or not at all.\n\nLoggingInterfaces SHOULD NOT throw exceptions; instead they should log errors using\nthe global logger.\n\nLoggingInterfaces SHOULD provide a named constructor option/field 'logger' that indicates\nwhich destination logs are sent to. This option SHOULD default to the rootLogger.\n\nLoggingInterfaces SHOULD provide a named constructor option 'level' and associated field\nthat can be used to limit logging to messages to those with a sufficiently\nhigh log level.\n\nLoggingInterfaces SHOULD provide a named constructor option 'filter' and associated field\nthat can be used to transform messages arbitrarily. This option should default to\nthe `identity()` function from ferrum. If the filter returns `undefined`\nthe message MUST be discarded.\n\nLoggingInterfaces SHOULD provide a named constructor option 'defaultFields'; if they do support\nthe property they MUST perform a shallow merge/setdefault into the message AFTER applying the\nfilters.\n\n**Kind**: global interface \n\n\n## The default constructor can be used to get the current point in time as a BigDate.\n**Kind**: global class \n**Implements**: Equals, Deepclone, Shallowclone \n\n\n### new The default constructor can be used to get the current point in time as a BigDate.(Converts, Construct, Construct, ...Can)\nA Date class capable of storing timestamps at arbitrary precisions that can\nbe used as a drop-in replacement for date.\n\nWhen generating timestamps at quick succession `Date` will often yield the\nsame result:\n\n```js\nconst assert = require('assert');\nconst a = new Date();\nconst b = new Date();\nassert.strictEqual(a.toISOString(), b.toISOString())\n```\n\nThis is often problematic. E.g. in the case of helix-log this can lead to log\nmessages being displayed out of order. Using `process.hrtime()` is not an option\neither because it's time stamps are only really valid on the same process.\n\nIn order to remedy this problem, helix-log was created: It measures time at a very\nhigh precision (nano seconds) while maintaining a reference to corordinated universal time\n\n```js\nconst assert = require('assert');\nconst { BigDate } = require('@adobe/helixLog')\nconst a = new BigDate();\nconst b = new BigDate();\nassert.notStrictEqual(a.toISOString(), b.toISOString());\n```\n\n# Precision in relation to Corordinated Universal Time\n\nMostly depends on how well synchronized the system clock is…usually between 20ms and 200ms.\nThis goes for both Date as well as BigDate, although BigDate can add up to 1ms of extra error.\n\n# Precision in relation to Date\n\nBigDate can add up to 1ms out of sync with Date.\n\nWhen measuring comparing `BigDate.preciseTime()` and `Date.getTime()` you may\nfind differences of up to 2.5ms due to the imprecision of measurement.\n\n# Precision in relation to hrtime()\n\nUsing BigDate::fromHrtime() you can convert hrtime timestamps to BigDate.\nThe conversion should be 1 to 1 (BigDate uses hrtime internally), but the\ninternal reference will be recalculated every time the clock jumps (e.g on\nhibernation or when the administrator adjusts the time). This can lead to\nfromHrtime interpreting timestamps vastly different before and after the jump.\n\n# For benchmarking/measurement overhead\n\nBigDate can be used for benchmarking and is better at it than Date and worse at it than hrtime.\n\nMeasuring the actual overhead proofed difficult, because results where vastly different\ndepending on how often hrtime was called.\n\n | Worst | Cold | Hot | Best\n-------- | ----- | ----- | ----- | -----\nHrtime | 10µs | 20µs | 1.5µs | 80ns\nBigDate | 500µs | 80µs | 4µs | 250ns\n\nWorst: First few invocations, bad luck\nCold: Typical first few invocations.\nHot: After tens to hundreds of invocations\nBest: After millions of invocations\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| Converts | Date \\| BigDate | a Date to a BigDate or copies a BigDate |\n| Construct | String | a BigDate from a string (like date, but supports arbitrary precision in the ISO 8601 String decimal places) |\n| 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. |\n| ...Can | \\* | be used to construct a BigDate from components (year, month, day, hours, minutes, seconds, milliseconds with decimal places) |\n\n\n\n## BunyanStreamInterface\nBunyan stream that can be used to forward any bunyan messages\nto helix log.\n\n**Kind**: global class \n**Implements**: [LoggingInterface](#LoggingInterface) \n\n\n## CoralogixLogger\nSends log messages to the coralogix logging service.\n\nYou can customize the host, application and subsystem per log\nmessage by specifying the appropriate fields.\n\n**Kind**: global class \n**Implements**: [Logger](#Logger) \n\n* [CoralogixLogger](#CoralogixLogger)\n * [new CoralogixLogger(apikey, app, subsystem)](#new_CoralogixLogger_new)\n * [.apikey](#CoralogixLogger+apikey) : [Secret](#Secret)\n * [.app](#CoralogixLogger+app) : string\n * [.subsystem](#CoralogixLogger+subsystem) : string\n * [.host](#CoralogixLogger+host) : string\n * [.flush()](#CoralogixLogger+flush)\n\n\n\n### new CoralogixLogger(apikey, app, subsystem)\n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| apikey | string \\| [Secret](#Secret) | | – Your coralogix api key |\n| app | string | | – Name of the app under which the log messages should be categorized |\n| subsystem | string | | – Name of the subsystem under which |\n| [opts.host] | string | "os.hostname()" | The hostname under which to categorize the messages |\n| [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 |\n\n\n\n### coralogixLogger.apikey : [Secret](#Secret)\nName of the app under which the log messages should be categorized\n\n**Kind**: instance property of [CoralogixLogger](#CoralogixLogger) \n\n\n### coralogixLogger.app : string\nName of the app under which the log messages should be categorized\n\n**Kind**: instance property of [CoralogixLogger](#CoralogixLogger) \n\n\n### coralogixLogger.subsystem : string\nName of the subsystem under which the log messages should be categorized\n\n**Kind**: instance property of [CoralogixLogger](#CoralogixLogger) \n\n\n### coralogixLogger.host : string\nThe hostname under which to categorize the messages\n\n**Kind**: instance property of [CoralogixLogger](#CoralogixLogger) \n\n\n### coralogixLogger.flush()\nFlush the internal buffer.\n\nImplementations of this SHOULD try to flush the underlying log sink if possible.\nThe returned promise SHOULD only fulfill if the flushing was done (best effort).\n\nNote that implementations SHOULD use best effort to avoid buffering or the need for flushing.\nHowever, there might be cases where this is not possible, for example when sending log messages\nover the network.\n\n**Kind**: instance method of [CoralogixLogger](#CoralogixLogger) \n**Implements**: [flush](#Logger+flush) \n\n\n## LoggerBase\nCan be used as a base class/helper for implementing loggers.\n\nThis will first apply the filter, drop the message if the level is\ntoo low or if the filter returned undefined and will then call the\nsubclass provided this._logImpl function for final processing.\n\nThis also wraps the entire logging logic into a promise enabled/async\nerror handler that will log any errors using the rootLogger.\n\n**Kind**: global class \n\n* [LoggerBase](#LoggerBase)\n * [new LoggerBase(opts)](#new_LoggerBase_new)\n * [.level](#LoggerBase+level) : string\n * [.filter](#LoggerBase+filter) : function\n\n\n\n### new LoggerBase(opts)\n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| opts | Object | | – Optional, named parameters |\n| [opts.level] | string | "'silly'" | The minimum log level to sent to loggly |\n| [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). |\n\n**Example** \n```\nclass MyConsoleLogger extends LoggerBase {\n _logImpl(fields) {\n console.log(fields);\n }\n}\n```\n\n\n### loggerBase.level : string\nThe minimum log level for messages to be printed.\nFeel free to change to one of the available levels.\n\n**Kind**: instance property of [LoggerBase](#LoggerBase) \n\n\n### loggerBase.filter : function\nUsed to optionally transform all messages.\nTakes a message and returns a transformed message\nor undefined (in which case the message will be dropped).\n\n**Kind**: instance property of [LoggerBase](#LoggerBase) \n\n\n## FormattedLoggerBase\nCan be used as a base class/helper for implementing loggers that\nrequire a formatter.\n\nWill do the same processing as `LoggerBase` and in addition call\nthe formatter before invoking _logImpl.\n\n**Kind**: global class \n\n* [FormattedLoggerBase](#FormattedLoggerBase)\n * [new FormattedLoggerBase()](#new_FormattedLoggerBase_new)\n * [.formatter](#FormattedLoggerBase+formatter) : [MessageFormatter](#MessageFormatter)\n\n\n\n### new FormattedLoggerBase()\n\n| Param | Type | Description |\n| --- | --- | --- |\n| [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. |\n\n**Example** \n```\nclass MyConsoleLogger extends FormattedLoggerBase {\n _logImpl(payload, fields) {\n console.log(`[${fields.level}]`, payload);\n }\n}\n```\n\n\n### formattedLoggerBase.formatter : [MessageFormatter](#MessageFormatter)\nFormatter used to format all the messages.\nMust yield an object suitable for the external resource\nthis logger writes to.\n\n**Kind**: instance property of [FormattedLoggerBase](#FormattedLoggerBase) \n\n\n## ConsoleLogger\nLogger that is especially designed to be used in node.js\nPrint's to stderr; Marks errors, warns & debug messages\nwith a colored `[ERROR]`/... prefix.\n\nFormatter MUST produce strings. Default formatter is messageFormatConsole.\n\n**Kind**: global class \n**Implements**: [Logger](#Logger) \n\n* [ConsoleLogger](#ConsoleLogger)\n * [new ConsoleLogger()](#new_ConsoleLogger_new)\n * [.stream](#ConsoleLogger+stream) : Writable\n\n\n\n### new ConsoleLogger()\n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| [opts.stream] | Writable | console._stderr | A writable stream to log to. |\n\n\n\n### consoleLogger.stream : Writable\nWritable stream to write log messages to. Usually console._stderr.\n\n**Kind**: instance property of [ConsoleLogger](#ConsoleLogger) \n\n\n## MultiLogger\nSimple logger that forwards all messages to the underlying loggers.\n\nThis maintains an es6 map called loggers. Consumers of this API are\nexplicitly permitted to mutate this map or replace it all together in\norder to add, remove or alter logger.\n\n**Kind**: global class \n**Implements**: [Logger](#Logger) \n**Parameter**: Sequence<Loggers> loggers – The loggers to forward to. \n\n\n### multiLogger.flush()\nFlush the internal buffer.\n\nImplementations of this SHOULD try to flush the underlying log sink if possible.\nThe returned promise SHOULD only fulfill if the flushing was done (best effort).\n\nNote that implementations SHOULD use best effort to avoid buffering or the need for flushing.\nHowever, there might be cases where this is not possible, for example when sending log messages\nover the network.\n\n**Kind**: instance method of [MultiLogger](#MultiLogger) \n**Implements**: [flush](#Logger+flush) \n\n\n## FileLogger\nLogger specifically designed for logging to unix file descriptors.\n\nThis logger is synchronous: It uses blocking syscalls and thus guarantees\nthat all data is written even if process.exit() is called immediately after\nlogging.\nFor normal files this is not a problem as linux will never block when writing\nto files, for sockets, pipes and ttys this might block the process for a considerable\ntime.\n\nFormatter MUST produce strings. Default formatter is messageFormatTechnical.\n\n**Kind**: global class \n**Implements**: [Logger](#Logger) \n\n* [FileLogger](#FileLogger)\n * [new FileLogger(name)](#new_FileLogger_new)\n * [.fd](#FileLogger+fd) : Integer\n\n\n\n### new FileLogger(name)\n\n| Param | Type | Description |\n| --- | --- | --- |\n| name | string \\| Integer | The path of the file to log to OR the unix file descriptor to log to. |\n\n\n\n### fileLogger.fd : Integer\nThe underlying operating system file descriptor.\n\n**Kind**: instance property of [FileLogger](#FileLogger) \n\n\n## MemLogger\nLogs messages to an in-memory buffer.\n\nFormatter can be anything; default just logs the messages as-is.\n\n**Kind**: global class \n**Implements**: [Logger](#Logger) \n\n\n### memLogger.buf : Array\nAn array that holds all the messages logged thus far.\nMay be modified An array that holds all the messages logged thus far.\nMay be modified.\n\n**Kind**: instance property of [MemLogger](#MemLogger) \n\n\n## InterfaceBase\nCan be used as a base class/helper for implementing logging interfaces.\n\nThis will make sure that all the required fields are set to their\ndefault value, apply the filter, drop the message if the level is\ntoo low or if the filter returned undefined and will then forward\nthe message to the logger configured.\n\nThis also wraps the entire logging logic into a promise enabled/async\nerror handler that will log any errors using the rootLogger.\n\n**Kind**: global class \n\n\n### new InterfaceBase(opts)\n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| opts | Object | | – Optional, named parameters |\n| [opts.level] | string | "'silly'" | The minimum log level to sent to the logger |\n| [opts.logger] | [Logger](#Logger) | rootLogger | The helix logger to use |\n| [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). |\n| [opts.defaultFields] | object | | Additional log fields to add to every log message. |\n\n**Example** \n```\nclass MyTextInterface extends InterfaceBase {\n logText(str) {\n this._logImpl({ message: [str] });\n }\n};\n\nconst txt = new MyTextInterface({ logger: rootLogger });\ntxt.logText(\"Hello World\");\n```\n\n\n## SimpleInterface\nThe fields interface provides the ability to conveniently\nspecify both a message and custom fields to the underlying logger.\n\n**Kind**: global class \n**Implements**: [LoggingInterface](#LoggingInterface) \n\n\n### simpleInterface.fatal(...msg)\nThese methods are used to log just a message with no custom\nfields to the underlying logger; similar to console.log.\n\nThis is not a drop in replacement for console.log, since this\ndoes not support string interpolation using `%O/%f/...`, but should\ncover most use cases.\n\n**Kind**: instance method of [SimpleInterface](#SimpleInterface) \n\n| Param | Type | Description |\n| --- | --- | --- |\n| ...msg | \\* | The message to write |\n\n\n\n## Secret\nSpecial wrapper that should be used to protect secret values.\n\nEffectively this tries to hide the actual payload so that the\nsecret has to be explicitly extracted before using it.\n\n```\nconst mySecret = new Secret(42); // Create a secret\nmySecret.value; // => 42; extract the value\nmySecret.value = 64; // assign a new value\n```\n\nThe secret can only be accessed through the .secret property\nin order to make sure that the access is not accidental;\nthe secret property cannot be iterated over and the secret will\nnot be leaked when converted to json or when printed.\n\n**Kind**: global class \n\n\n## WinstonTransportInterface\nWinston transport that forwards any winston log messages to\nthe specified helix-log logger.\n\n```\nconst winston = require('winston');\nconst { WinstonTransportInterface } = require('helix-log');\n\nconst myWinsonLogger = W.createLogger({\n transports: [new WinstonTransportInterface()]\n});\n\n// Will log 'Hello World' to the rootLogger with the fields:\n// {category: 'testing'}.\nmyWinsonLogger.info('Hello World', category: 'testing');\n```\n\n**Kind**: global class \n**Implements**: WinstonTransport, [LoggingInterface](#LoggingInterface) \n\n\n### new WinstonTransportInterface(opts)\n\n| Param | Type | Description |\n| --- | --- | --- |\n| opts | Object | – Options as specified by WinstonTransport AND by LoggingInterface; both sets of options are supported |\n| 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. |\n\n\n\n## rootLogger\nThe logger all other loggers attach to.\n\nMust always contain a logger named 'default'; it is very much recommended\nthat the default logger always be a console logger; this can serve as a good\nfallback in case other loggers fail.\n\n**Kind**: global constant \n**Example** \n```js\n// Change the default logger\nrootLogger.loggers.set('default', new ConsoleLogger({level: 'debug'}));\n```\n\nYou should not log to the root logger directly; instead use one of the\nwrapper functions `log, fatal, err, warn, info, verbose, debug`; they\nperform some additional\n\n\n## JsonifyForLog\nTrait used to serialize json objects to json. See jsonifyForLog.\n\n**Kind**: global constant \n\n\n## eraseBunyanDefaultFields(fields) ⇒ Object\nRemove the default fields emitted by buyan.\n\nThese fields are added by bunyan by default but are often not of\nmuch interest (like name, bunyanLevel, or `v`) or can be easily added\nagain later for data based loggers where this information might be\nvaluable (e.g. hostname, pid).\n\nUse like this:\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | Object | \n\n**Example** \n```\nconst bunyan = require('bunyan');\nconst { BunyanStreamInterface, eraseBunyanDefaultFields } = require('helix-log');\n\nconst logger = bunyan.createLogger({name: 'helixLogger'});\nlogger.addStream(BunyanStreamInterface.createStream({\n filter: eraseBunyanDefaultFields\n}));\n```\n\n\n## numericLogLevel(name) ⇒ number\nThis can be used to convert a string log level into it's\nnumeric equivalent. More pressing log levels have lower numbers.\n\n**Kind**: global function \n**Returns**: number - The numeric log level \n**Throws**:\n\n- Error If the given log level name is invalid.\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| name | string | Name of the log level |\n\n\n\n## makeLogMessage([fields]) ⇒ [Message](#Message)\nSupplies default values for all the required fields in log messages.\n\nYou may pass this a message that is just a string (as opposed to the\nusually required array of message components). The message will then automatically\nbe wrapped in an array.\n\n**Kind**: global function \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| [fields] | Object | {} | User supplied field values; can overwrite any default values |\n\n\n\n## tryInspect(what, opts)\nWrapper around inspect that is extremely robust against errors\nduring inspection.\n\nSpecifically designed to handle errors in toString() functions\nand custom inspect functions.\n\nIf any error is encountered a less informative string than a full\ninspect is returned and the error is logged using `err()`.\n\n**Kind**: global function \n\n| Param | Type | Description |\n| --- | --- | --- |\n| what | \\* | The object to inspect |\n| opts | Object | Options will be passed through to inspect. Note that these may be ignored if there is an error during inspect(). |\n\n\n\n## serializeMessage(msg, opts) ⇒ string\nTurns the message field into a string.\n\n**Kind**: global function \n\n| Param | Type | Description |\n| --- | --- | --- |\n| msg | Array.<\\*> \\| undefined | – Message components to serialize |\n| opts | Object | – Parameters are forwarded to tryInspect() |\n\n\n\n## messageFormatSimple(fields) ⇒ [MessageFormatter](#MessageFormatter) \\| string\nSimple message format: Serializes the message and prefixes it with\nthe log level.\n\nThis is used by the MemLogger by default for instance, because it is relatively\neasy to test with and contains no extra info.\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n## messageFormatTechnical(fields) ⇒ [MessageFormatter](#MessageFormatter) \\| string\nMessage format that includes extra information; prefixes each message\nwith the time stamp and the log level.\n\nThis is used by FileLogger by default for instance because if you\nwork with many log files you need that sort of info.\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n## messageFormatConsole(fields) ⇒ [MessageFormatter](#MessageFormatter) \\| string\nMessage format with coloring/formatting escape codes\n\nDesigned for use in terminals.\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n## messageFormatJson(fields) ⇒ [MessageFormatter](#MessageFormatter) \\| Object\nUse jsonifyForLog to turn the fields into something that\ncan be converted to json.\n\n**Kind**: global function \n**Oaram**: [Message](#Message) message the log message \n\n| Param | Type | Description |\n| --- | --- | --- |\n| fields | \\* | additional log fields |\n\n\n\n## messageFormatJsonString(fields) ⇒ [MessageFormatter](#MessageFormatter) \\| Object\nMessage format that produces & serialize json.\n\nReally just an alias for `JSON.stringify(messageFormatJson(fields))`.\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n## deriveLogger(logger, opts) ⇒ [Logger](#Logger)\nHelper function that creates a derived logger that is derived from a given logger, merging\nthe given options. All the properties are shallow copied to the new logger With the exception of\nthe `defaultFields`, where the `defaultFields` object itself is shallow-copied. Thus allowing to\n_extend_ the default fields.\n\n**Kind**: global function \n**Returns**: [Logger](#Logger) - A new logger with updated options. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| logger | [Logger](#Logger) | the logger to derive from. |\n| opts | object | Options to merge with this logger |\n\n\n\n## \\_\\_handleLoggingExceptions(fields, logger, code) ⇒ [Message](#Message)\nHelper to wrap any block of code and handle it's async & sync exceptions.\n\nThis will catch any exceptions/promise rejections and log them using the rootLogger.\n\n**Kind**: global function \n**Access**: package \n\n| Param | Type | Description |\n| --- | --- | --- |\n| fields | Object | Fields to set in any error message (usually indicates which logger was used) |\n| logger | [Logger](#Logger) | the logger to wrap |\n| code | function | The code to wrap |\n\n\n\n## fatal(...msg)\nLog just a message to the rootLogger using the SimpleInterface.\n\nAlias for `new SimpleInterface().log(...msg)`.\n\nThis is not a drop in replacement for console.log, since this\ndoes not support string interpolation using `%O/%f/...`, but should\ncover most use cases.\n\n**Kind**: global function \n\n| Param | Type | Description |\n| --- | --- | --- |\n| ...msg | \\* | The message to write |\n\n\n\n## messageFormatJsonStatic(fields) ⇒ Object\nMessage format used for comparing logs in tests.\n\nPretty much just messageFormatJson, but removes the time stamp\nbecause that is hard to compare since it is different each time...\n\nIf other highly variable fields are added in the future (e.g. id = uuidgen())\nthese shall be removed too.\n\n**Kind**: global function \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n\n\n## recordLogs(opts, fn) ⇒ string\nRecord the log files with debug granularity while the given function is running.\n\nWhile the logger is recording, all other loggers are disabled.\nIf this is not your desired behaviour, you can use the MemLogger\nmanually.\n\n**Kind**: global function \n**Returns**: string - The logs that where produced by the codee \n\n| Param | Type | Description |\n| --- | --- | --- |\n| opts | Object | – optional first parameter; options passed to MemLogger |\n| fn | function | The logs that this code emits will be recorded. |\n\n**Example** \n```\nrecordLogs(() => {\n info('Hello World');\n err('Nooo');\n});\n```\n\nwill return something like this:\n\n```\n[\n { level: 'info', message: 'Hello World', timestamp: '...' },\n { level: 'error', message: 'Noo', timestamp: '...' }\n]\n```\n\n\n## assertLogs(opts, fn, logs)\nAssert that a piece of code produces a specific set of log messages.\n\n**Kind**: global function \n\n| Param | Type | Description |\n| --- | --- | --- |\n| opts | Object | – optional first parameter; options passed to MemLogger |\n| fn | function | The logs that this code emits will be recorded. |\n| logs | string | |\n\n**Example** \n```\nconst { assertLogs, info, err } = require('@adobe/helix-shared').log;\n\nassertLogs(() => {\n info('Hello World');\n err('Nooo');\n}, [\n { level: 'info', message: 'Hello World' },\n { level: 'error', message: 'Noo' }\n]);\n```\n\n\n## recordAsyncLogs(opts, fn) ⇒ string\nAsync variant of recordLogs.\n\nNote that using this is a bit dangerous as other async procedures\nmay also emit log messages while this procedure is running\n\n**Kind**: global function \n**Returns**: string - The logs that where produced by the code \n\n| Param | Type | Description |\n| --- | --- | --- |\n| opts | Object | – optional first parameter; options passed to MemLogger |\n| fn | function | The logs that this code emits will be recorded. |\n\n\n\n## assertAsyncLogs(opts, fn, logs)\nAsync variant of assertLogs\n\nNote that using this is a bit dangerous as other async procedures\nmay also emit logs while this async procedure is running.\n\n**Kind**: global function \n\n| Param | Type | Description |\n| --- | --- | --- |\n| opts | Object | – optional first parameter; options passed to MemLogger |\n| fn | function | The logs that this code emits will be recorded. |\n| logs | string | |\n\n\n\n## jsonifyForLog(what) ⇒ \\*\njsonify the given data using the JsonifyForLog trait.\n\nTakes any javascript object and produces an object tree\nthat only contains json compatible objects (objects, arrays,\nnumbers, bools, strings and such).\n\nThis is a no-op if the input is already json compatible.\n\nNote that this is specifically designed to serialize data for structured\nlogging. This is NOT suitable for proper serialization of json; specifically\nthis may loose information in cases where that makes sense.\n\nFeatures a default converter for any exception/subclass of Error.\n\n**Kind**: global function \n**Returns**: \\* - Json compatible object \n**Throws**:\n\n- TraitNotImplemented If any object in the given object tree\n can not be converted to json-compatible\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| what | \\* | The object to convert |\n\n\n\n## MessageFormatter ⇒ \\*\nMost loggers take a message with `log()`, encode it and write it to some\nexternal resource.\n\nE.g. most Loggers (like ConsoleLogger, FileLogger, ...) write to a text\noriented resource, so the message needs to be converted to text. This is\nwhat the formatter is for.\n\nNot all Loggers require text; some are field oriented (working with json\ncompatible data), others like the MemLogger can handle arbitrary javascript\nobjects, but still provide an optional formatter (in this case defaulted to\nthe identity function – doing nothing) in case the user explicitly wishes\nto perform formatting.\n\n**Kind**: global typedef \n**Returns**: \\* - Whatever kind of type the Logger needs. Usually a string. \n\n| Param | Type |\n| --- | --- |\n| fields | [Message](#Message) | \n\n","readmeFilename":"README.md"}