log inbound/outbound HTTP traffic
npm install 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.
---
---
- 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.
Upcoming Features:
- Support any logger that is able to format json objects into log messages (like log4js, winston, pino, etc ...)
---
The above example logs are generated by executing:
``js`
curl localhost:3000 -H "X-myHeader: myHeaderValue"
Assuming that the following example server is running:
!examples/hello_with_outgoing_traffic.js
---
* Node version >= 8
* Koa version >= 2
---
`npm i --save riviere`
---
Example:
`js
const Koa = require('koa');
const Riviere = require('riviere');
const app = new Koa();
app.use(Riviere.middleware());
app.use(async function(ctx) {
ctx.body = 'Hello World';
});
app.listen(3000);
`
Example with outbound HTTP traffic:
`js
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.middleware());
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);
`
---
The behavior of the riviere middleware can be configured by passing a configuration object,
as argument to the Riviere.middleware() method call.
You can start using riviere' by just calling app.use(Riviere.middleware()).riviere
In this case the will use its default configuration.
The default configuration object is the following:
`js`
const riviereConfObj = {
context: ctx => {
return {};
},
errors: {
enabled: true,
callback: (ctx, error) => {
throw(error);
}
},
health: [],
inbound: {
enabled: true,
}
outbound: {
enabled: true
},
bodyKeys: [],
headersRegex: new RegExp('^X-.*', 'i'),
traceHeaderName: 'X-Riviere-Id'
}
Here is an example of a more advanced configuration:
`js
const riviereConfObj = {
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'
};
app.use(Riviere.middleware(riviereConfObj));
`
The supported key-value options, for the configuration object are described below.
---
Enable inbound HTTP traffic logging. Defaults to true.
This option can be used to log specific values from the JSON body of the inbound POST requests.[]
Defaults to empty Array .POST
To use this option, the request's body should be a valid JSON.Koa
Most often this mean that you should register the bodyParser middlewareriviere
(https://www.npmjs.com/package/body-parser) (or something equivalent),
before registering the middleware.
Example:
`js`
{
bodyKeys: [
'education',
'work_experience'
]
}
Log colored log messages. Defaults to: true
Example:
`js`
{
color: true
}
The context to be included in every inbound_request and outbound_response
log message. Defaults to empty Object: .
Example:
`js`
{
context: (ctx) => {
return {
userId: ctx.request.headers['user-id'],
accountId: ctx.request.headers['account-id']
};
}
}
Enable inbound HTTP traffic logs. Defaults to true.
Control how the server handles any unhandled errors inside a request's context.
The default is to re-throw the unhandled error.
Example:
`js
{
errors: {
callback: (ctx, error) => {
ctx.status = error.status || 500;
if (ctx.status < 500) {
ctx.body = {error: error.message};
} else {
ctx.body = {error: 'Internal server error'};
}
}
}
}
`
Specify a regular expression to match the request headers,
that should be included in every inbound_request log message.new RegExp('^X-.+', 'i')
Defaults to .
All the inbound request's headers starting with "X-" will be logged by default.
Example:
`js`
{
headersRegex: new RegExp('X-.+', 'i')
}
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
`js`
{
health: [
{
path: '/health',
method: 'GET'
}
]
}
Enable outbound HTTP traffic logs. Defaults to true.
Example:
`js`
{
outbound: {
enabled: true
}
}
Theis is a Header key for the request id header.
Defaults to: X-Riviere-Id.riviere
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 traceHeaderName to: X-Request-Id
(https://devcenter.heroku.com/articles/http-request-id)
Example:
`js`
{
traceHeaderName: 'X-Request-Id'
}
---
MIT
(!see LICENCE)