Neolithic Prancing Minotaurs
    Wondering what’s next for npm?Check out our public roadmap! »

    @workablehr/riviere
    TypeScript icon, indicating that this package has built-in type declarations

    1.12.2 • Public • Published

    NPM

    Coverage Status

    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.


    Table of contents

    1. Features
    2. Example logs
    3. Requirements
    4. Installation
    5. Usage
    6. Configuration
    7. Available Options
      1. inbound.enabled
      2. inbound.includeHost
      3. inbound.request.enabled
      4. inbound.maxBodyValueChars
      5. bodyKeys
      6. bodyKeysRegex
      7. color
      8. styles
      9. context
      10. errors.callback
      11. headersRegex
      12. health
      13. outbound.enabled
      14. outbound.request.enabled
      15. outbound.maxBodyValueChars
      16. outbound.blacklistedPathRegex
      17. traceHeaderName
    8. 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);

    Example with outbound HTTP traffic:

    const Koa = require('koa');
    const riviere = require('riviere');
    
    // this is just an example, you can use any http library
    const rp = require('request-promise');
    
    const app = new Koa();
    
    app.use(riviere());
    app.use(async function(ctx) {
      await rp({
        uri: '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,
        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

    inbound

    inbound.enabled

    Enable inbound HTTP traffic logging. Defaults to true.

    inbound.request.enabled

    Enable inbound_request HTTP traffic logging. Defaults to true.

    inbound.includeHost

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

    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
        }
    }

    bodyKeys

    This option can be used to log specific values from the JSON body of the inbound POST requests. Defaults to empty Array []. To use this option, the POST 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'
        ]
    }

    bodyKeysRegex

    This option can be used to log specific values from the JSON body of the inbound POST requests. Defaults to undefined. To use this option, the POST 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('.*');
    }

    color

    Log colored log messages. Defaults to: true

    Example:

    {
        color: true
    }

    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']
    }

    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']
            };
        }
    }

    errors

    errors.enabled

    Enable inbound HTTP traffic logs. Defaults to true.

    errors.callback

    Control how the server handles any unhandled errors inside a request's context. The default is to re-throw the unhandled error.

    Example:

    {
        errors: {
            callback: (err, ctx) => {
                ctx.status = err.status || 500;
    
                if (ctx.status < 500) {
                    ctx.body = {error: err.message};
                } else {
                    ctx.body = {error: 'Internal server error'};
                }
            }
        }
    }

    headersRegex

    Specify a regular expression to match the request headers, that should be included in every inbound_request log message. Defaults to new RegExp('^X-.+', 'i'). All the inbound request's headers starting with "X-" will be logged by default.

    Example:

    {
        headersRegex: new RegExp('X-.+', 'i')
    }

    health

    Specify your health endpoints in order to log a minimum subset of information, for these inbound_requests. Defaults to []. This may be useful when: You have a load balancer or other system that pings your server at a specific end-point, periodically, to determine the health of your server, and you do not want to log much details regarding these requests.

    Example

    {
        health: [
            {
                path: '/health',
                method: 'GET'
            }
        ]
    }

    outbound

    outbound.enabled

    Enable outbound HTTP traffic logs. Defaults to true.

    Example:

    {
        outbound: {
            enabled: true
        }
    }

    outbound.request.enabled

    Enable outbound_request HTTP traffic logging. Defaults to true.

    outbound.maxBodyValueChars

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

    Example:

    {
        outbound: {
            maxBodyValueChars: 1024
        }
    }

    outbound.blacklistedPathRegex

    This option can be used to prevent specific outbound paths to be logged. Defaults to [].

    Example:

    {
        outbound: {
            blacklistedPathRegex: /\/health/
        }
    }

    traceHeaderName

    Theis is a Header key for the request id header. Defaults to: X-Riviere-Id. If you already use a request id header you may need to set this options. For example for Heroku deployments, you most often want to set the riviere traceHeaderName to: X-Request-Id (https://devcenter.heroku.com/articles/http-request-id)

    Example:

    {
        traceHeaderName: 'X-Request-Id'
    }

    License

    MIT (see LICENCE)

    Install

    npm i @workablehr/riviere

    DownloadsWeekly Downloads

    42

    Version

    1.12.2

    License

    MIT

    Unpacked Size

    159 kB

    Total Files

    53

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar