From: Justin Wind Date: Mon, 29 May 2023 18:08:55 +0000 (-0700) Subject: update documentation X-Git-Tag: v2.0.1~1 X-Git-Url: https://git.squeep.com/?a=commitdiff_plain;h=5f6029bc6c75708175ade99f6c44beb1d0e2817a;p=squeep-logger-json-console update documentation --- diff --git a/README.md b/README.md index 9188471..d517752 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,26 @@ A simple logger class, which mostly just structures messages, data, and some met Supports basic scrubbing of well-defined sensitive fields, and an extensible set of JSON replacer functions for common objects. -If provided with an asyncLocalStorage instance, it expects a stored object which will be spread over the resulting logged json, taking precedence. +If provided with an asyncLocalStorage instance, it expects a stored object which will be spread over the resulting logged JSON. -Intended to be specific to Squeep Framework Applications, this module has opinions. +Intended to be specific to Squeep Framework Applications, this module has some opinions. ## API -Expects these arguments in any log call: - -- `scope` - e.g. file:method -- `message` - text -- `data` - object -- any additional arguments are included as an array, but not scrubbed +- `new Logger(options, commonObject, asyncLocalStorage, backend)` + - `commonObject` will be merged into every log + - `asyncLocalStorage`, if provided, should store an object, which will also be merged into log + - `backend` is `console` by default, but may be anything implementing the same log-level functions + +- `error(scope, message, data, ...)` + - `scope` - identifies source of message, e.g. 'class:method' + - `message` - text to be logged + - `data` - object to be logged, can be scrubbed of sensitive fields, and will be serialized with provided replacers + - any additional arguments are included as an array +- `warn(scope, message, data, ...)` +- `info(scope, message, data, ...)` +- `log(scope, message, data, ...)` +- `debug(scope, message, data, ...)` ## JSON Replacers @@ -27,11 +35,11 @@ Includes replacers for these objects: - http.OutgoingMessage - http.ServerResponse -Custom replacers may be inserted into the logger instance's `jsonReplacers` array. +Additional replacers may be inserted into the logger instance's `jsonReplacers` array. ## Data Sanitizers -Custom sanitizers may be inserted into the logger instance's `dataSanitizers` array. +Sanitizers may be inserted into the logger instance's `dataSanitizers` array. ## Example diff --git a/lib/data-sanitizers.js b/lib/data-sanitizers.js index e4d0f3c..bf04950 100644 --- a/lib/data-sanitizers.js +++ b/lib/data-sanitizers.js @@ -1,25 +1,32 @@ 'use strict'; /** - * Here are some sanitizers to replace data fields before logging. - * Well, really, this just documents the expected format. + * Sanitizers replace data fields before logging. + * None are bundled, but here is an example of one. */ /** - * template for sanitizers + * Example sanitizer function. + * Sanitizers are called initially with `sanitize` false, to only determine + * whether the data object will be changed. If so, the sanitizer is then + * called again with `sanitize` true, but provided with a clone of the + * original data to update, to avoid leaking any applied changes back to the + * application. * @param {Object} data * @param {Boolean} sanitize - * @returns {Boolean} + * @returns {Boolean} whether sanitizer is applicable to data */ /* istanbul ignore next */ function _sanitizer(data, sanitize = true) { let unclean = false; - if (undefined) { // eslint-disable-line no-constant-condition + const sensitiveFieldLength = data?.sensitiveField?.length; + if (sensitiveFieldLength) { unclean = true; - } - if (unclean && sanitize) { - data; + + if (sanitize) { + data.sensitiveField = '*'.repeat(sensitiveFieldLength); + } } return unclean; diff --git a/package.json b/package.json index 87af158..05b6981 100644 --- a/package.json +++ b/package.json @@ -4,10 +4,10 @@ "engines": { "node": ">=14" }, - "description": "A simple logger which spews JSON to stdout; intended for use in Squeep Framework Applications.", + "description": "A simple logger which spews formatted data and metadata as JSON to stdout; intended for use in Squeep Framework Applications.", "main": "index.js", "scripts": { - "coverage": "nyc npm test", + "coverage": "nyc --clean npm test", "coverage-check": "nyc check-coverage", "eslint": "eslint *.js lib", "test": "mocha --recursive" @@ -18,7 +18,8 @@ }, "keywords": [ "json", - "log" + "log", + "structured logging" ], "author": "Justin Wind ", "license": "ISC",