node_modules/morgan/README.md

   1 # morgan
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Build Status][travis-image]][travis-url]
   6 [![Test Coverage][coveralls-image]][coveralls-url]
   7
   8 HTTP request logger middleware for node.js
   9
  10 > Named after [Dexter](http://en.wikipedia.org/wiki/Dexter_Morgan), a show you should not watch until completion.
  11
  12 ## API
  13
  14 <!-- eslint-disable no-unused-vars -->
  15
  16 ```js
  17 var morgan = require('morgan')
  18 ```
  19
  20 ### morgan(format, options)
  21
  22 Create a new morgan logger middleware function using the given `format` and `options`.
  23 The `format` argument may be a string of a predefined name (see below for the names),
  24 a string of a format string, or a function that will produce a log entry.
  25
  26 The `format` function will be called with three arguments `tokens`, `req`, and `res`,
  27 where `tokens` is an object with all defined tokens, `req` is the HTTP request and `res`
  28 is the HTTP response. The function is expected to return a string that will be the log
  29 line, or `undefined` / `null` to skip logging.
  30
  31 #### Using a predefined format string
  32
  33 <!-- eslint-disable no-undef -->
  34
  35 ```js
  36 morgan('tiny')
  37 ```
  38
  39 #### Using format string of predefined tokens
  40
  41 <!-- eslint-disable no-undef -->
  42
  43 ```js
  44 morgan(':method :url :status :res[content-length] - :response-time ms')
  45 ```
  46
  47 #### Using a custom format function
  48
  49 <!-- eslint-disable no-undef -->
  50
  51 ``` js
  52 morgan(function (tokens, req, res) {
  53   return [
  54     tokens.method(req, res),
  55     tokens.url(req, res),
  56     tokens.status(req, res),
  57     tokens.res(req, res, 'content-length'), '-',
  58     tokens['response-time'](req, res), 'ms'
  59   ].join(' ')
  60 })
  61 ```
  62
  63 #### Options
  64
  65 Morgan accepts these properties in the options object.
  66
  67 ##### immediate
  68
  69 Write log line on request instead of response. This means that a requests will
  70 be logged even if the server crashes, _but data from the response (like the
  71 response code, content length, etc.) cannot be logged_.
  72
  73 ##### skip
  74
  75 Function to determine if logging is skipped, defaults to `false`. This function
  76 will be called as `skip(req, res)`.
  77
  78 <!-- eslint-disable no-undef -->
  79
  80 ```js
  81 // EXAMPLE: only log error responses
  82 morgan('combined', {
  83   skip: function (req, res) { return res.statusCode < 400 }
  84 })
  85 ```
  86
  87 ##### stream
  88
  89 Output stream for writing log lines, defaults to `process.stdout`.
  90
  91 #### Predefined Formats
  92
  93 There are various pre-defined formats provided:
  94
  95 ##### combined
  96
  97 Standard Apache combined log output.
  98
  99 ```
 100 :remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"
 101 ```
 102
 103 ##### common
 104
 105 Standard Apache common log output.
 106
 107 ```
 108 :remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]
 109 ```
 110
 111 ##### dev
 112
 113 Concise output colored by response status for development use. The `:status`
 114 token will be colored red for server error codes, yellow for client error
 115 codes, cyan for redirection codes, and uncolored for all other codes.
 116
 117 ```
 118 :method :url :status :response-time ms - :res[content-length]
 119 ```
 120
 121 ##### short
 122
 123 Shorter than default, also including response time.
 124
 125 ```
 126 :remote-addr :remote-user :method :url HTTP/:http-version :status :res[content-length] - :response-time ms
 127 ```
 128
 129 ##### tiny
 130
 131 The minimal output.
 132
 133 ```
 134 :method :url :status :res[content-length] - :response-time ms
 135 ```
 136
 137 #### Tokens
 138
 139 ##### Creating new tokens
 140
 141 To define a token, simply invoke `morgan.token()` with the name and a callback function.
 142 This callback function is expected to return a string value. The value returned is then
 143 available as ":type" in this case:
 144
 145 <!-- eslint-disable no-undef -->
 146
 147 ```js
 148 morgan.token('type', function (req, res) { return req.headers['content-type'] })
 149 ```
 150
 151 Calling `morgan.token()` using the same name as an existing token will overwrite that
 152 token definition.
 153
 154 The token function is expected to be called with the arguments `req` and `res`, representing
 155 the HTTP request and HTTP response. Additionally, the token can accept further arguments of
 156 it's choosing to customize behavior.
 157
 158 ##### :date[format]
 159
 160 The current date and time in UTC. The available formats are:
 161
 162   - `clf` for the common log format (`"10/Oct/2000:13:55:36 +0000"`)
 163   - `iso` for the common ISO 8601 date time format (`2000-10-10T13:55:36.000Z`)
 164   - `web` for the common RFC 1123 date time format (`Tue, 10 Oct 2000 13:55:36 GMT`)
 165
 166 If no format is given, then the default is `web`.
 167
 168 ##### :http-version
 169
 170 The HTTP version of the request.
 171
 172 ##### :method
 173
 174 The HTTP method of the request.
 175
 176 ##### :referrer
 177
 178 The Referrer header of the request. This will use the standard mis-spelled Referer header if exists, otherwise Referrer.
 179
 180 ##### :remote-addr
 181
 182 The remote address of the request. This will use `req.ip`, otherwise the standard `req.connection.remoteAddress` value (socket address).
 183
 184 ##### :remote-user
 185
 186 The user authenticated as part of Basic auth for the request.
 187
 188 ##### :req[header]
 189
 190 The given `header` of the request. If the header is not present, the
 191 value will be displayed as `"-"` in the log.
 192
 193 ##### :res[header]
 194
 195 The given `header` of the response. If the header is not present, the
 196 value will be displayed as `"-"` in the log.
 197
 198 ##### :response-time[digits]
 199
 200 The time between the request coming into `morgan` and when the response
 201 headers are written, in milliseconds.
 202
 203 The `digits` argument is a number that specifies the number of digits to
 204 include on the number, defaulting to `3`, which provides microsecond precision.
 205
 206 ##### :status
 207
 208 The status code of the response.
 209
 210 If the request/response cycle completes before a response was sent to the
 211 client (for example, the TCP socket closed prematurely by a client aborting
 212 the request), then the status will be empty (displayed as `"-"` in the log).
 213
 214 ##### :url
 215
 216 The URL of the request. This will use `req.originalUrl` if exists, otherwise `req.url`.
 217
 218 ##### :user-agent
 219
 220 The contents of the User-Agent header of the request.
 221
 222 ### morgan.compile(format)
 223
 224 Compile a format string into a `format` function for use by `morgan`. A format string
 225 is a string that represents a single log line and can utilize token syntax.
 226 Tokens are references by `:token-name`. If tokens accept arguments, they can
 227 be passed using `[]`, for example: `:token-name[pretty]` would pass the string
 228 `'pretty'` as an argument to the token `token-name`.
 229
 230 The function returned from `morgan.compile` takes three arguments `tokens`, `req`, and
 231 `res`, where `tokens` is object with all defined tokens, `req` is the HTTP request and
 232 `res` is the HTTP response. The function will return a string that will be the log line,
 233 or `undefined` / `null` to skip logging.
 234
 235 Normally formats are defined using `morgan.format(name, format)`, but for certain
 236 advanced uses, this compile function is directly available.
 237
 238 ## Examples
 239
 240 ### express/connect
 241
 242 Simple app that will log all request in the Apache combined format to STDOUT
 243
 244 ```js
 245 var express = require('express')
 246 var morgan = require('morgan')
 247
 248 var app = express()
 249
 250 app.use(morgan('combined'))
 251
 252 app.get('/', function (req, res) {
 253   res.send('hello, world!')
 254 })
 255 ```
 256
 257 ### vanilla http server
 258
 259 Simple app that will log all request in the Apache combined format to STDOUT
 260
 261 ```js
 262 var finalhandler = require('finalhandler')
 263 var http = require('http')
 264 var morgan = require('morgan')
 265
 266 // create "middleware"
 267 var logger = morgan('combined')
 268
 269 http.createServer(function (req, res) {
 270   var done = finalhandler(req, res)
 271   logger(req, res, function (err) {
 272     if (err) return done(err)
 273
 274     // respond to request
 275     res.setHeader('content-type', 'text/plain')
 276     res.end('hello, world!')
 277   })
 278 })
 279 ```
 280
 281 ### write logs to a file
 282
 283 #### single file
 284
 285 Simple app that will log all requests in the Apache combined format to the file
 286 `access.log`.
 287
 288 ```js
 289 var express = require('express')
 290 var fs = require('fs')
 291 var morgan = require('morgan')
 292 var path = require('path')
 293
 294 var app = express()
 295
 296 // create a write stream (in append mode)
 297 var accessLogStream = fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
 298
 299 // setup the logger
 300 app.use(morgan('combined', { stream: accessLogStream }))
 301
 302 app.get('/', function (req, res) {
 303   res.send('hello, world!')
 304 })
 305 ```
 306
 307 #### log file rotation
 308
 309 Simple app that will log all requests in the Apache combined format to one log
 310 file per day in the `log/` directory using the
 311 [rotating-file-stream module](https://www.npmjs.com/package/rotating-file-stream).
 312
 313 ```js
 314 var express = require('express')
 315 var fs = require('fs')
 316 var morgan = require('morgan')
 317 var path = require('path')
 318 var rfs = require('rotating-file-stream')
 319
 320 var app = express()
 321 var logDirectory = path.join(__dirname, 'log')
 322
 323 // ensure log directory exists
 324 fs.existsSync(logDirectory) || fs.mkdirSync(logDirectory)
 325
 326 // create a rotating write stream
 327 var accessLogStream = rfs('access.log', {
 328   interval: '1d', // rotate daily
 329   path: logDirectory
 330 })
 331
 332 // setup the logger
 333 app.use(morgan('combined', { stream: accessLogStream }))
 334
 335 app.get('/', function (req, res) {
 336   res.send('hello, world!')
 337 })
 338 ```
 339
 340 ### split / dual logging
 341
 342 The `morgan` middleware can be used as many times as needed, enabling
 343 combinations like:
 344
 345   * Log entry on request and one on response
 346   * Log all requests to file, but errors to console
 347   * ... and more!
 348
 349 Sample app that will log all requests to a file using Apache format, but
 350 error responses are logged to the console:
 351
 352 ```js
 353 var express = require('express')
 354 var fs = require('fs')
 355 var morgan = require('morgan')
 356 var path = require('path')
 357
 358 var app = express()
 359
 360 // log only 4xx and 5xx responses to console
 361 app.use(morgan('dev', {
 362   skip: function (req, res) { return res.statusCode < 400 }
 363 }))
 364
 365 // log all requests to access.log
 366 app.use(morgan('common', {
 367   stream: fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
 368 }))
 369
 370 app.get('/', function (req, res) {
 371   res.send('hello, world!')
 372 })
 373 ```
 374
 375 ### use custom token formats
 376
 377 Sample app that will use custom token formats. This adds an ID to all requests and displays it using the `:id` token.
 378
 379 ```js
 380 var express = require('express')
 381 var morgan = require('morgan')
 382 var uuid = require('node-uuid')
 383
 384 morgan.token('id', function getId (req) {
 385   return req.id
 386 })
 387
 388 var app = express()
 389
 390 app.use(assignId)
 391 app.use(morgan(':id :method :url :response-time'))
 392
 393 app.get('/', function (req, res) {
 394   res.send('hello, world!')
 395 })
 396
 397 function assignId (req, res, next) {
 398   req.id = uuid.v4()
 399   next()
 400 }
 401 ```
 402
 403 ## License
 404
 405 [MIT](LICENSE)
 406
 407 [npm-image]: https://img.shields.io/npm/v/morgan.svg
 408 [npm-url]: https://npmjs.org/package/morgan
 409 [travis-image]: https://img.shields.io/travis/expressjs/morgan/master.svg
 410 [travis-url]: https://travis-ci.org/expressjs/morgan
 411 [coveralls-image]: https://img.shields.io/coveralls/expressjs/morgan/master.svg
 412 [coveralls-url]: https://coveralls.io/r/expressjs/morgan?branch=master
 413 [downloads-image]: https://img.shields.io/npm/dm/morgan.svg
 414 [downloads-url]: https://npmjs.org/package/morgan