git.squeep.com Git - squeep-logger-json-console/blob - README.md

   1 # @squeep/logger-json-console
   2
   3 A simple logger class, which mostly just structures messages, data, and some metadata as JSON and spews it, by default, to Console.
   4
   5 Supports basic scrubbing of well-defined sensitive fields, detection of circular references, and an extensible set of JSON replacer functions for common objects.
   6
   7 If provided with an asyncLocalStorage instance, it expects a stored object which will be spread over the resulting logged JSON.
   8
   9 Intended to be specific to Squeep Framework Applications, this module has some opinions.
  10
  11 ## API
  12
  13 - `new Logger(options, commonObject, asyncLocalStorage, backend)`
  14   - `commonObject` will be merged into every log
  15   - `asyncLocalStorage`, if provided, should store an object, which will also be merged into log
  16   - `backend` is `console` by default, but may be anything implementing the same log-level functions
  17
  18 - `error(scope, message, data, ...)`
  19   - `scope` - identifies source of message, e.g. 'class:method'
  20   - `message` - text to be logged
  21   - `data` - object to be logged, can be scrubbed of sensitive fields, and will be serialized with provided replacers
  22   - any additional arguments are included as an array
  23 - `warn(scope, message, data, ...)`
  24 - `info(scope, message, data, ...)`
  25 - `log(scope, message, data, ...)`
  26 - `debug(scope, message, data, ...)`
  27
  28 ## JSON Replacers
  29
  30 Includes replacers for these objects:
  31
  32 - Error
  33 - BigInt
  34 - http.IncomingMessage
  35 - http.OutgoingMessage
  36 - http.ServerResponse
  37
  38 Additional replacers may be inserted into the logger instance's `jsonReplacers` array.
  39
  40 ## Data Sanitizers
  41
  42 Sanitizers may be inserted into the logger instance's `dataSanitizers` array.
  43
  44 ## Example
  45
  46 ```javascript
  47 const http = require('node:http');
  48 const { AsyncLocalStorage } = require('node:async_hooks');
  49 const uuid = require('uuid');
  50 const Logger = require('@squeep/logger-json-console');
  51
  52 const loggerOptions = {
  53   ignoreBelowLevel: 'info',
  54 };
  55 const commonObject = {
  56   nodeIdentifier: uuid.v1(),
  57 };
  58 const asyncLocalStorage = new AsyncLocalStorage();
  59 const logger = new Logger(loggerOptions, commonObject, asyncLocalStorage);
  60
  61 const scope = 'exampleServer';
  62 http.createServer((req, res) => {
  63   asyncLocalStorage.run({ requestId: uuid.v1() }, () => {
  64     logger.debug(scope, 'start', { req, res });
  65     setImmediate(() => {
  66       res.end();
  67       logger.info(scope, 'finish', { req, res }, 'other stuff');
  68     });
  69   });
  70 }).listen(8088);
  71 ```
  72
  73 Results in messages such as this:
  74
  75 ```json
  76 {
  77   "nodeIdentifier": "64610280-fc17-11ed-a918-1dd19f027d43",
  78   "timestamp": "2023-05-26T22:48:17.995Z",
  79   "timestampMs": 1685141297995,
  80   "level": "info",
  81   "scope": "exampleServer",
  82   "message": "finish",
  83   "data": {
  84     "req": {
  85       "method": "GET",
  86       "url": "/",
  87       "httpVersion": "1.1",
  88       "headers": {
  89         "host": "localhost:8088",
  90         "user-agent": "curl/7.83.1",
  91         "accept": "*/*"
  92       },
  93       "trailers": {}
  94     },
  95     "res": {
  96       "statusCode": 200,
  97       "statusMessage": "OK",
  98       "headers": {}
  99     }
 100   },
 101   "other": [
 102     "other stuff"
 103   ],
 104   "requestId": "68233aa0-fc17-11ed-a918-1dd19f027d43"
 105 }
 106 ```