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