express-winston-2
winston middleware for express.js
Installation
npm install express-winston-2
Usage
express-winston-2 provides middleware for request and error logging of your express.js application. It uses 'whitelists' to select properties from the request and (new in 0.2.x) response objects.
To make use of express-winston-2, you need to add the following to your application:
In server.js
(or wherever you need it):
var winston = require('winston'),
expressWinston = require('express-winston-2');
Logging errors to a file
- Logs all responses to the console
- Logs errors to 'errors.log'. In this case, we classify any response with a status code greater than 400 as an error.
{return expressWinston;}
The logger needs to be added AFTER the express router(app.router)
) and BEFORE any of your custom error handlers(express.handler
). Since express-winston-2 will just log the errors and not handle them, you can still use your custom error handler like express.handler
, just be sure to put the logger before any of your handlers.
Options
transports: <WinstonTransport> // list of all winston transports instances to use.winstonInstance: <WinstonLogger> // a winston logger instance. If this is provided the transports option is ignoredlevel: String // log level to use (info/warn/error). The default is "info".getLogLevel: Function // Takes in the response status code as its only parameter and returns (info/warn/error) which then becomes the new 'level'.// function to determine if logging is skipped, defaults to false
To use winston's existing transports, set transports
to the values (as in key-value) of the winston.default.transports
object. This may be done, for example, by using underscorejs: transports: _.values(winston.default.transports)
.
Alternatively, if you're using a winston logger instance elsewhere and have already set up levels and transports, pass the instance into expressWinston with the winstonInstance
option. The transports
option is then ignored.
Request Logging
Use expressWinston.logger(options)
to create a middleware to log your HTTP requests.
var router = ;app;app; // notice how the router goes after the logger.
Examples
var express = ;var expressWinston = ;var winston = ; // for transports.Consolevar app = moduleexports = ;app;app;// Let's make our express `Router` first.var router = express;router;app;// express-winston-2 logger makes sense BEFORE the router.app;// Now we can tell the app to use our routing code:app;// express-winston-2 errorLogger makes sense AFTER the router.app;// Optionally you can include your custom error handler after the logging.app;app;
Browse /
to see a regular HTTP logging like this:
{
"req": {
"httpVersion": "1.1",
"headers": {
"host": "localhost:3000",
"connection": "keep-alive",
"accept": "*/*",
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11",
"accept-encoding": "gzip,deflate,sdch",
"accept-language": "en-US,en;q=0.8,es-419;q=0.6,es;q=0.4",
"accept-charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"cookie": "connect.sid=nGspCCSzH1qxwNTWYAoexI23.seE%2B6Whmcwd"
},
"url": "/",
"method": "GET",
"originalUrl": "/",
"query": {}
},
"res": {
"statusCode": 200
},
"responseTime" : 12,
"level": "info",
"message": "HTTP GET /favicon.ico"
}
Browse /error
will show you how express-winston-2 handles and logs the errors in the express pipeline like this:
{
"date": "Thu Jul 19 2012 23:39:44 GMT-0500 (COT)",
"process": {
"pid": 35719,
"uid": 501,
"gid": 20,
"cwd": "/Users/thepumpkin/Projects/testExpressWinston",
"execPath": "/usr/local/bin/node",
"version": "v0.6.18",
"argv": [
"node",
"/Users/thepumpkin/Projects/testExpressWinston/app.js"
],
"memoryUsage": {
"rss": 14749696,
"heapTotal": 7033664,
"heapUsed": 5213280
}
},
"os": {
"loadavg": [
1.95068359375,
1.5166015625,
1.38671875
],
"uptime": 498086
},
"trace": [
...,
{
"column": 3,
"file": "Object].log (/Users/thepumpkin/Projects/testExpressWinston/node_modules/winston/lib/winston/transports/console.js",
"function": "[object",
"line": 87,
"method": null,
"native": false
}
],
"stack": [
"Error: This is an error and it should be logged to the console",
" at /Users/thepumpkin/Projects/testExpressWinston/app.js:39:15",
" at callbacks (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:272:11)",
" at param (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:246:11)",
" at pass (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:253:5)",
" at Router._dispatch (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:280:4)",
" at Object.handle (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:45:10)",
" at next (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/node_modules/connect/lib/http.js:204:15)",
" at done (/Users/thepumpkin/Dropbox/Projects/express-winston-2/index.js:91:14)",
" at /Users/thepumpkin/Dropbox/Projects/express-winston-2/node_modules/async/lib/async.js:94:25",
" at [object Object].log (/Users/thepumpkin/Projects/testExpressWinston/node_modules/winston/lib/winston/transports/console.js:87:3)"
],
"req": {
"httpVersion": "1.1",
"headers": {
"host": "localhost:3000",
"connection": "keep-alive",
"cache-control": "max-age=0",
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11",
"accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"accept-encoding": "gzip,deflate,sdch",
"accept-language": "en-US,en;q=0.8,es-419;q=0.6,es;q=0.4",
"accept-charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"cookie": "connect.sid=nGspCCSzH1qxwNTWYAoexI23.seE%2B6WhmcwdzFEjqhMDuIIl3mAUY7dT4vn%2BkWvRPhZc"
},
"url": "/error",
"method": "GET",
"originalUrl": "/error",
"query": {}
},
"level": "error",
"message": "middlewareError"
}
Global Whitelists and Blacklists
Express-winston exposes three whitelists that control which properties of the request
, body
, and response
are logged:
requestWhitelist
bodyWhitelist
,bodyBlacklist
responseWhitelist
For example, requestWhitelist
defaults to:
['url', 'headers', 'method', 'httpVersion', 'originalUrl', 'query'];
Only those properties of the request object will be logged. Set or modify the whitelist as necessary.
For example, to include the session property (the session data), add the following during logger setup:
expressWinston.requestWhitelist.push('session');
The blacklisting excludes certain properties and keeps all others. If both bodyWhitelist
and bodyBlacklist
are set
the properties excluded by the blacklist are not included even if they are listed in the whitelist!
Example:
expressWinston.bodyBlacklist.push('secretid', 'secretproperty');
Note that you can log the whole request and/or response body:
expressWinston.requestWhitelist.push('body');
expressWinston.responseWhitelist.push('body');
Route-Specific Whitelists and Blacklists
New in version 0.2.x is the ability to add whitelist elements in a route. express-winston-2 adds a _routeWhitelists
object to the req
uest, containing .body
, .req
and .res` properties, to which you can set an array of 'whitelist' parameters to include in the log, specific to the route in question:
router;
Post to /user/register
would give you something like the following:
{
"req": {
"httpVersion": "1.1",
"headers": {
"host": "localhost:3000",
"connection": "keep-alive",
"accept": "*/*",
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11",
"accept-encoding": "gzip,deflate,sdch",
"accept-language": "en-US,en;q=0.8,es-419;q=0.6,es;q=0.4",
"accept-charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"cookie": "connect.sid=nGspCCSzH1qxwNTWYAoexI23.seE%2B6Whmcwd"
},
"url": "/",
"method": "GET",
"originalUrl": "/",
"query": {},
"body": {
"username": "foo",
"email": "foo@bar.com",
"age": "72"
}
},
"res": {
"statusCode": 200
},
"responseTime" : 12,
"level": "info",
"message": "HTTP GET /favicon.ico"
}
Blacklisting supports only the body
property.
router;
If both req._bodyWhitelist.body
and req._bodyBlacklist.body
are set the result will be the white listed properties
excluding any black listed ones. In the above example, only 'email' and 'age' would be included.
Tests
Run the basic Mocha tests:
npm test
Run the Travis-CI tests (which will fail with < 100% coverage):
npm test-travis
Generate the coverage.html
coverage report:
npm test-coverage
Issues and Collaboration
If you ran into any problems, please use the project Issues section to search or post any bug.
Contributors
- Johan Hernandez (https://github.com/bithavoc)
- Lars Jacob (https://github.com/jaclar)
- Jonathan Lomas (https://github.com/floatingLomas)
Also see AUTHORS file, add yourself if you are missing.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.