n-auto-logger

an opinionated enhancer to log function calls in the operation/action model

using n-logger by default, can be set to any logger instance

• Install
• Usage
  • log an Action
  • log an Operation
  • auto log level
  • mute logger fields
  • customise logger instance
  • requestId
• Gotcha
  • reserved fields
  • ignored fields
  • error auto parse
  • log auto trim
  • mute logger in test
• Licence

Install

npm install @financial-times/n-auto-logger

Usage

log an Action

automatically log the start, success/failure state with necessary metadata including function name as action, it can be applied to both individual action function or an action function bundle.

import { logAction, tagService, compose } from '@financial-times/n-auto-logger';

const result = logAction(someFunction)({...params, meta}); // action function

export default compose(
 tagService('service-name'), // optional
 logAction,
)({ 
 methodA, 
 methodB, 
 methodC 
}); // action function bundle

more details on action function

log an Operation

automatically log the start, success/failure state with necessary metadata including function name as operation, it can be applied to both individual operation function or an operation function bundle.

import { logOperation, errorToHanlder, compose } from '@financial-times/n-auto-logger';

const operationFunction = (meta, req, res) => {}; // operation function
const someMiddleware = compose(
 errorToHandler, 
 logOperation
)(operationFunction);

export default compose(
 errorToHandler, 
 logOperation
)({ 
 operationFunctionA, 
 operationFuncitonB 
}); // operation function bundle

more details on operation function

auto log level

set auto log level in .env with 3 options: verbose(default) | concise | error.

AUTO_LOG_LEVEL=concise

• verbose would log every stage(start, success/failure) of operation and action
• concise would log success/failure of operation and only failure of action
• error would log only failure of operation and action

You can override the ENV_VAR with a flag value as well if you would like to switch log level in production for debugging.

mute logger fields

set key names of fields to be muted in .env to reduce log for development or filter fields in production.

LOGGER_MUTE_FIELDS=transactionId, userId

customise logger instance

import { setupLoggerInstance } from '@financial-times/n-auto-logger';
import winston from 'winston'; // you can use any instance as long as it has .info, .warn, .error method

setupLoggerInstance(winston); // set the logger instance before using the enhancer

requestId

use the requestIdMiddleware to ensure the logs are easy to thread when debugging, and this would work well with n-api-factory to pass it to up stream services.

import { requestIdMiddleware } from '@financial-times/n-auto-logger';

// you might want to exclude `__*` path from log
app.use(/^\/(?!_{2}).*$/, [
 // use it before any other middleware to be logged
 requestIdMiddleware,
 //...other middlewares
]);

Gotcha

reserved fields

n-auto-logger will append values to following reserved fields automatically, the values would be overriden by the key value of the same name in your args/params/meta or error object, be cautious not to override them unintentionally.

| fields | default | convention used in | |-----------|------------------------------------------------------------------------------------|------------------------| | operation | operationFunction.name | n-auto-logger/metrics | | action | actionFunction.name | n-auto-logger/metrics | | service | tagService('service-name') | n-auto-metrics | | result | 'success''failure' | n-auto-logger | | category | 'FETCH_RESPONSE_ERROR''FETCH_NETWORK_ERROR''NODE_SYSTEM_ERROR''CUSTOM_ERROR' | n-auto-metrics/n-error | | type | specify the unique error type for debugging and error handling | n-auto-metrics/n-error | | status | recorded for service action call failure | n-error/n-api-factory | | stack | error stack trace | n-error |

ignored fields

user, handler, _locals fields from error or meta object would not be logged by default.

sensitive personal data could be put in meta.user and would not be logged

const meta = { ...meta, user: { id, email } };

UI but not debugger facing data could be put in error.user and would not be logged e.g. app error status (> API call error status), user message (> error message from API for debugging)

throw nError({ status, message }).extend({ user: { status, message } });

.handler field would not be logged, as it is only useful for error handler

throw nError({ status: 404 }).extend({ handler: 'REDIRECT_TO_INDEX' });

_locals field would not be logged as it is verbose and not relevant to debug

// in case you didn't clone the error object in error handler
function(err, req, res, next) {
  const e = {...err}; // clone the error object to avoid mutate the input
  res.render('template', e); // res.render is not a pure function, it would assign _locals to e
}

error auto parse

n-auto-logger would parse different forms of the following error objects to logger-suitable format automatically(detail), while it still logs plain object and string message.

• Fetch Response Error content-type:application/json,text/plain,text/html
• Fetch (Network) Error
• Node native Error objects
• Custom objects extends native Error object
• NError

log auto trim

n-auto-logger would trim any empty fields and method fields in the input meta or error objects automatically to concise log (detail), you shouldn't be concerned about passing excessive meta fields or extend Error object with methods.

mute logger in test

stub the logger instance instead of the whole module

import logger from '@financial-times/n-auto-logger'; // the underlying logger instance (`n-logger`)

// sinon sandbox
sandbox.stub(logger);

// jest
logger.info = jest.fn();
logger.warn = jest.fn();
logger.error = jest.fn();

Licence

MIT