riviere

The riviere module decorates your Koa middleware chain with inbound/outbound HTTP traffic logs.

Use riviere if you want an easy way to log all the HTTP traffic for your server. riviere works independently of your logging library, if you use any.

Features
Example logs
Requirements
Installation
Usage
Configuration
Available Options
License

Features

Log all the HTTP(s) requests that are coming into your server and the corresponding responses. (inbound_request/outbound_response)
Log all the HTTP(s) requests that your server sends to any external systems and the corresponding responses. (outbound_request/inbound_response)
Log any unhandled errors that are thrown inside a requests's context.
Format logs in json (fully compatible with Google Stackdriver)

Example logs

alt text

The above example logs are generated by executing:

curl localhost:3000 -H "X-myHeader: myHeaderValue"

Assuming that the following example server is running: examples/hello_with_outgoing_traffic.js

Requirements

Node version >= 8
Koa version >= 2

Installation

npm i --save riviere

Usage

Example:

const Koa = require('koa');
const riviere = require('riviere');

const app = new Koa();

app.use(riviere());
app.use(async function(ctx) {
    ctx.body = 'Hello World';
});

app.listen(3000);

<a name="example_with_outbound_http_traffic"></a> Example with outbound HTTP traffic:

const Koa = require('koa');
const riviere = require('riviere');

const app = new Koa();

app.use(riviere());
app.use(async function(ctx) {
  await fetch('https://www.google.com', {
    // You can include the x-riviere-id header
    // to trace the request's context inside which
    // the external request is made
    // This is optional but recommended for better tracing:
    headers: {
      'x-riviere-id': ctx.request.headers['x-riviere-id'] // notice that this is lowercase
    }
  });
  ctx.body = 'Hello World';
});

app.listen(3000);

Configuration

The behavior of the riviere middleware can be configured by passing a configuration object, as argument to the riviere() method call.

You can start using riviere' by just calling app.use(riviere()). In this case the riviere will use its default configuration.

The default configuration object is the following:

const configuration = {
    context: ctx => {
        return {};
    },
    errors: {
        enabled: true,
        callback: (err, ctx) => {
            throw(err);
        }
    },
    health: [],
    inbound: {
        enabled: true,
        request: {
            enabled: true
        },
        maxBodyValueChars: undefined
    },
    outbound: {
        enabled: true,
        request: {
            enabled: true
        },
        maxBodyValueChars: undefined
    },
    bodyKeys: [],
    bodyKeysRegex: undefined,
    bodyKeysCallback: (body: any, ctx?: KoaContext) => ({}),
    headersRegex: new RegExp('^X-.*', 'i'),
    traceHeaderName: 'X-Riviere-Id',
    styles: ['simple'],
}

Here is an example of a more advanced configuration:

const configuration = {
    bodyKeys: [
        'education',
        'work_experience'
    ],
    color: true,
    context: (ctx) => {
        return {
            userId: ctx.request.headers['user-id'],
            accountId: ctx.request.headers['account-id']
        };
    },
    errors: {
        enabled: true,
        callback: (ctx, error) => {
            ctx.status = error.status || 500;

            if (ctx.status < 500) {
                ctx.body = {error: error.message};
            } else {
                ctx.body = {error: 'Internal server error'};
            }
        }
    },
    headersRegex: new RegExp('X-.+', 'i'),
    health: [
        {
            path: '/health',
            method: 'GET'
        }
    ],
    outbound: {
        enabled: true
    },
    traceHeaderName: 'X-Request-Id',
    styles: ['simple', 'json']
};

app.use(riviere(configuration));

The supported key-value options, for the configuration object are described below.

Available options

<a name="options_inbound"></a> inbound

<a name="options_inbound_enabled"></a> inbound.enabled

Enable inbound HTTP traffic logging. Defaults to true.

<a name="options_inbound_request_enabled"></a> inbound.request.enabled

Enable inbound_request HTTP traffic logging. Defaults to true.

<a name="options_inbound_includeHost"></a> inbound.includeHost

Log full path, including host on inbound requests. Defaults to false.

<a name="options_inbound_max_body_value_chars"></a> inbound.maxBodyValueChars

This option can be used to truncate values JSON body of the inbound POST requests to a specified length. Defaults to undefined. To use this option, the POST request's body should be a valid JSON.

Example:

{
    inbound: {
        maxBodyValueChars: 1024
    }
}

<a name="options_body_keys"></a> bodyKeys

This option can be used to log specific values from the JSON body of the inbound POST, PUT & PATCH requests. Defaults to empty Array []. To use this option, the request's body should be a valid JSON. Most often this mean that you should register the Koa bodyParser middleware (https://www.npmjs.com/package/body-parser) (or something equivalent), before registering the riviere middleware.

Example:

{
    bodyKeys: [
        'education',
        'work_experience'
    ]
}

<a name="options_body_keys_regex"></a> bodyKeysRegex

This option can be used to log specific values from the JSON body of the inbound POST, PUT & PATCH requests. Defaults to undefined. To use this option, the request's body should be a valid JSON. Most often this mean that you should register the Koa bodyParser middleware (https://www.npmjs.com/package/body-parser) (or something equivalent), before registering the riviere middleware.

This option will override bodyKeys

Example:

{
    bodyKeysRegex: new RegExp('.*');
}

<a name="options_body_keys_callback"></a> bodyKeysCallback

This option can be used to let you choose which fields should be logged on inbound POST, PUT & PATCH requests. Defaults to undefined. To use this option, the request's body should be a valid JSON. Most often this mean that you should register the Koa bodyParser middleware (https://www.npmjs.com/package/body-parser) (or something equivalent), before registering the riviere middleware.

This option will override bodyKeys and bodyKeysRegex

Example:

{
    bodyKeysCallback: (body: any, ctx?: KoaContext) => {
        if (!ctx) return body;
        return {
            ...body,
            fields: body.fields.filter(f => !f._obfuscated)
        }
    };
}

<a name="options_color"></a> color

Log colored log messages. Defaults to: true

Example:

{
    color: true
}

<a name="options_styles"></a> styles

This option is used to format log messages with specific styles. Defaults to: ['simple'] If multiple options are defined one line is exported for every different style. Available options are:

'simple': Prints method, path, status code and timing followed by ' | ' and a string containing key-value pairs of object properties
'extended': Same as simple but also contains key-value pairs of all properties (fully compatible with LogEntries)
'json': All object properties as a valid JSON object (fully compatible with Google Stackdriver)

Example:

{
    styles: ['simple', 'json']
}

<a name="options_context"></a> context

The context to be included in every inbound_request and outbound_response log message. Defaults to empty Object: {}.

Example:

{
    context: (ctx) => {
        return {
            userId: ctx.request.headers['user-id'],
            accountId: ctx.request.headers['account-id']
        };
    }
}

<a name="options_errors"></a> errors

<a name="options_errors_enabled"></a> errors.enabled

Enable inbound HTTP traffic logs. Defaults to true.

<a name="options_errors_callback"></a

Riviere

Install / Use

README

riviere

Table of contents

Features

Example logs

Requirements

Installation

Usage

Configuration

Available options