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 |
|
9 | HTTP 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
|
16 | var morgan = require('morgan')
|
17 | ```
|
18 |
|
19 | ### morgan(format, options)
|
20 |
|
21 | Create a new morgan logger middleware function using the given `format` and `options`.
|
22 | The `format` argument may be a string of a predefined name (see below for the names),
|
23 | a string of a format string, or a function that will produce a log entry.
|
24 |
|
25 | #### Options
|
26 |
|
27 | Morgan accepts these properties in the options object.
|
28 |
|
29 | #### immediate
|
30 |
|
31 | Write log line on request instead of response. This means that a requests will
|
32 | be logged even if the server crashes, _but data from the response (like the
|
33 | response code, content length, etc.) cannot be logged_.
|
34 |
|
35 | ##### skip
|
36 |
|
37 | Function to determine if logging is skipped, defaults to `false`. This function
|
38 | will be called as `skip(req, res)`.
|
39 |
|
40 | ```js
|
41 | // EXAMPLE: only log error responses
|
42 | morgan('combined', {
|
43 | skip: function (req, res) { return res.statusCode < 400 }
|
44 | })
|
45 | ```
|
46 |
|
47 | ##### stream
|
48 |
|
49 | Output stream for writing log lines, defaults to `process.stdout`.
|
50 |
|
51 | #### Predefined Formats
|
52 |
|
53 | There are various pre-defined formats provided:
|
54 |
|
55 | ##### combined
|
56 |
|
57 | Standard 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 |
|
65 | Standard 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 |
|
73 | Concise output colored by response status for development use. The `:status`
|
74 | token will be colored red for server error codes, yellow for client error
|
75 | codes, 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 |
|
83 | Shorter 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 |
|
91 | The minimal output.
|
92 |
|
93 | ```
|
94 | :method :url :status :res[content-length] - :response-time ms
|
95 | ```
|
96 |
|
97 | #### Tokens
|
98 |
|
99 | ##### Creating new tokens
|
100 |
|
101 | To 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
|
103 | morgan.token('type', function(req, res){ return req.headers['content-type']; })
|
104 | ```
|
105 |
|
106 | Calling `morgan.token()` using the same name as an existing token will overwrite that token definition.
|
107 |
|
108 | ##### :date[format]
|
109 |
|
110 | The 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 |
|
116 | If no format is given, then the default is `web`.
|
117 |
|
118 | ##### :http-version
|
119 |
|
120 | The HTTP version of the request.
|
121 |
|
122 | ##### :method
|
123 |
|
124 | The HTTP method of the request.
|
125 |
|
126 | ##### :referrer
|
127 |
|
128 | The Referrer header of the request. This will use the standard mis-spelled Referer header if exists, otherwise Referrer.
|
129 |
|
130 | ##### :remote-addr
|
131 |
|
132 | The remote address of the request. This will use `req.ip`, otherwise the standard `req.connection.remoteAddress` value (socket address).
|
133 |
|
134 | ##### :remote-user
|
135 |
|
136 | The user authenticated as part of Basic auth for the request.
|
137 |
|
138 | ##### :req[header]
|
139 |
|
140 | The given `header` of the request.
|
141 |
|
142 | ##### :res[header]
|
143 |
|
144 | The given `header` of the response.
|
145 |
|
146 | ##### :response-time[digits]
|
147 |
|
148 | The time between the request coming into `morgan` and when the response
|
149 | headers are written, in milliseconds.
|
150 |
|
151 | The `digits` argument is a number that specifies the number of digits to
|
152 | include on the number, defaulting to `3`, which provides microsecond percision.
|
153 |
|
154 | ##### :status
|
155 |
|
156 | The status code of the response.
|
157 |
|
158 | If the request/response cycle completes before a response was sent to the
|
159 | client (for example, the TCP socket closed prematurely by a client aborting
|
160 | the request), then the status will be empty (displayed as `"-"` in the log).
|
161 |
|
162 | ##### :url
|
163 |
|
164 | The URL of the request. This will use `req.originalUrl` if exists, otherwise `req.url`.
|
165 |
|
166 | ##### :user-agent
|
167 |
|
168 | The contents of the User-Agent header of the request.
|
169 |
|
170 | ### morgan.compile(format)
|
171 |
|
172 | Compile a format string into a function for use by `morgan`. A format string
|
173 | is a string that represents a single log line and can utilize token syntax.
|
174 | Tokens are references by `:token-name`. If tokens accept arguments, they can
|
175 | be passed using `[]`, for example: `:token-name[pretty]` would pass the string
|
176 | `'pretty'` as an argument to the token `token-name`.
|
177 |
|
178 | Normally formats are defined using `morgan.format(name, format)`, but for certain
|
179 | advanced uses, this compile function is directly available.
|
180 |
|
181 | ## Examples
|
182 |
|
183 | ### express/connect
|
184 |
|
185 | Simple app that will log all request in the Apache combined format to STDOUT
|
186 |
|
187 | ```js
|
188 | var express = require('express')
|
189 | var morgan = require('morgan')
|
190 |
|
191 | var app = express()
|
192 |
|
193 | app.use(morgan('combined'))
|
194 |
|
195 | app.get('/', function (req, res) {
|
196 | res.send('hello, world!')
|
197 | })
|
198 | ```
|
199 |
|
200 | ### vanilla http server
|
201 |
|
202 | Simple app that will log all request in the Apache combined format to STDOUT
|
203 |
|
204 | ```js
|
205 | var finalhandler = require('finalhandler')
|
206 | var http = require('http')
|
207 | var morgan = require('morgan')
|
208 |
|
209 | // create "middleware"
|
210 | var logger = morgan('combined')
|
211 |
|
212 | http.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 |
|
228 | Simple app that will log all requests in the Apache combined format to the file
|
229 | `access.log`.
|
230 |
|
231 | ```js
|
232 | var express = require('express')
|
233 | var fs = require('fs')
|
234 | var morgan = require('morgan')
|
235 |
|
236 | var app = express()
|
237 |
|
238 | // create a write stream (in append mode)
|
239 | var accessLogStream = fs.createWriteStream(__dirname + '/access.log', {flags: 'a'})
|
240 |
|
241 | // setup the logger
|
242 | app.use(morgan('combined', {stream: accessLogStream}))
|
243 |
|
244 | app.get('/', function (req, res) {
|
245 | res.send('hello, world!')
|
246 | })
|
247 | ```
|
248 |
|
249 | #### log file rotation
|
250 |
|
251 | Simple app that will log all requests in the Apache combined format to one log
|
252 | file per date in the `log/` directory using the
|
253 | [file-stream-rotator module](https://www.npmjs.com/package/file-stream-rotator).
|
254 |
|
255 | ```js
|
256 | var FileStreamRotator = require('file-stream-rotator')
|
257 | var express = require('express')
|
258 | var fs = require('fs')
|
259 | var morgan = require('morgan')
|
260 |
|
261 | var app = express()
|
262 | var logDirectory = __dirname + '/log'
|
263 |
|
264 | // ensure log directory exists
|
265 | fs.existsSync(logDirectory) || fs.mkdirSync(logDirectory)
|
266 |
|
267 | // create a rotating write stream
|
268 | var 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
|
276 | app.use(morgan('combined', {stream: accessLogStream}))
|
277 |
|
278 | app.get('/', function (req, res) {
|
279 | res.send('hello, world!')
|
280 | })
|
281 | ```
|
282 |
|
283 | ### use custom token formats
|
284 |
|
285 | Sample app that will use custom token formats. This adds an ID to all requests and displays it using the `:id` token.
|
286 |
|
287 | ```js
|
288 | var express = require('express')
|
289 | var morgan = require('morgan')
|
290 | var uuid = require('node-uuid')
|
291 |
|
292 | morgan.token('id', function getId(req) {
|
293 | return req.id
|
294 | })
|
295 |
|
296 | var app = express()
|
297 |
|
298 | app.use(assignId)
|
299 | app.use(morgan(':id :method :url :response-time'))
|
300 |
|
301 | app.get('/', function (req, res) {
|
302 | res.send('hello, world!')
|
303 | })
|
304 |
|
305 | function 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/
|