@bblabs/mindfulness

A simple interface for logging and metrics endpoints.

Install

npm install --save @bblabs/mindfulness

Logging usage

const Logger = require('@bblabs/mindfulness').Logger;

const logger = new Logger([
  // log to the console
  'console',

  // post to http://logging.example.com/
  {
    type: 'json_post',
    host: 'logging.example.com',
  }
]);

// e.g.:
//   console.log('Message', {payload: 123})
//   request('http://logging.example.com').post({
//     severity: 'log',
//     type: 'log',
//     message: 'Message',
//     info: { payload: 123}
//   })
logger.log('Message', {payload: 123});
logger.logWarn('Message', {payload: 123});
logger.logError('Message', {payload: 123});

// send the log request and catch any errors
try {
  await logger.logInfo('Message', {payload: 123});
}
catch (err) {
}

// change the request body with the post logger:
logger.log('Message', {payload: 123}, {requestBodyCallback: (body, details) => {
  return {
    ...body,
    // add .environment to the body
    environment: process.env.NODE_ENV
  };
}});

Note: logging methods are asynchronous and return a Promise. So you can use await or handle the Promise if you want to ensure things worked.

The Logger interface also supports "log levels". This allows you to specify the output levels you would like via flags. By default everything is logged.

const l = new Logger(['console'], {
  // logLevel can be a single level or multiple:
  //   LOG_LEVELS.LOG_ERROR | LOG_LEVELS.LOG_LOG
  // log only errors:
  logLevel: Logger.LOG_LEVELS.LOG_ERROR,
});

Metrics usage

const Metrics = require('@bblabs/mindfulness').Metrics;

const metrics = new Metrics([
  // post metrics to metrics.example.com
  {
    type: 'json_post',
    host: 'metrics.example.com',
    // specify distinct paths for each type of metric call
    paths: {
      increment: '/increment',
      // also supports $category and $metric variables to replace path with those items
      // if $category is blank, it will not be used (and if there's a forward slash in
      // the url following $category, mindfulness will remove that too)
      timing: '/feature/$category/$metric',
    }
  }
]);

// metric with a value
metrics.increment('metric', 10);
metrics.increment('category', 'metric');

// metric with a value... if you need the value to be a string, you must specify
// a category and metric.
metrics.increment('category', 'metric', 10);
metrics.timing('category', 'metric', value);

Metrics JSON POST can handle multiple paths for each metric type:

const metrics = new Metrics()

Error handling

All logging & metrics calls are asynchronous, which also means that errors may occur. Since this package uses native Promises these need to be handled or you will get warnings about unhandled rejections.

To do this, you can either implement your own error handling or use the silent() option:

// this will silence any errors that come from sending this metric
metrics.silent().increase('metric');

// you can still view errors in the metrics object if you want:
if (metrics.errors) {
  console.warn('There were errors sending metrics');
}

.silent() only works on the current request: it will only stop an error from the current call, not subsequent calls.

Additionally, you can configure both classes to always supress errors with alwaysSilent: true in it's options.

Before/After

Both Metrics and Logging support before and after hooks:

const logging = new Logging(['console'], {
  before: (message, payload, options) => {
    return [message.toUpperCase(), payload, options];
  }
});

const metrics = new Metrics(['console'], {
  before: (metricType, metric) => {
    if (!metric.value) {
      metric.value = 1;
    }
    return {metric};
  }
});

JSON POST

JSON POST also can also be modified/customized in a few ways:

const l = new Logger([{
  type: 'json_post',
  // include extra things in the body by default...
  dataDefaults: { includedInBody: 'example' },
  // modify the "body" that is posted to the endpoint...
  requestBodyCallback: (body, details) => {
    return {
      ...body,
      anotherThing: 123,
    }
  }
}]);

The JSON POST functionality will default to localhost if you do not specify a host.

Debug (npm) logging

You can also use the (debug package)[https://www.npmjs.com/package/debug] for logging:

const l = new Logger([
  // similiar to debug('myproject')(message)...
  { type: 'debug', namespace: 'myproject' },
]);

Development

nvm use
npm install

To build from Typescript: npm build or npm build-watch

To test: npm test or npm test-watch

Future

• Custom metrics/logger outputs? e.g. new Metrics([MySpecialMetricsHandler])

RipSecrets

We implement pipeline secret scanning on all pull request events to prevent credentials from being merged. If the pipeline scanner detects a secret in your changed files it will gate the pull request and you will need to purge the found credential from your code and re-open the PR. To prevent getting gated by this tool and as best practice you should install the secret scanner locally in a pre-commit hook to prevent the secret from ever being committed to the repo in the first place. You can find documentation on how to set it up locally here
Ripsecrets has ways to bypass secret scanning although we should not be ignoring secrets that turn up in the scans. If something is out of your control and blocking the pipeline you can bypass it in one of the following ways

1. Adding "# pragma: allowlist secret" to the end of the line with the secret.
   
2. Adding the specific secret underneath the "[secrets]" block in .secretsignore
   
3. Adding the filepath to ignore the whole file aboove the "[secrets]" block in .secretsignore