e5d578a849
Disable the confirmation dialog when deleting files in the VS Code explorer to streamline the development workflow and reduce friction during file management operations.
437 lines
11 KiB
Markdown
437 lines
11 KiB
Markdown
# morgan
|
|
|
|
[![NPM Version][npm-version-image]][npm-url]
|
|
[![NPM Downloads][npm-downloads-image]][npm-url]
|
|
[![Build Status][ci-image]][ci-url]
|
|
[![Coverage Status][coveralls-image]][coveralls-url]
|
|
|
|
HTTP request logger middleware for node.js
|
|
|
|
> Named after [Dexter](http://en.wikipedia.org/wiki/Dexter_Morgan), a show you should not watch until completion.
|
|
|
|
## Installation
|
|
|
|
This is a [Node.js](https://nodejs.org/en/) module available through the
|
|
[npm registry](https://www.npmjs.com/). Installation is done using the
|
|
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
|
|
|
```sh
|
|
$ npm install morgan
|
|
```
|
|
|
|
## API
|
|
|
|
<!-- eslint-disable no-unused-vars -->
|
|
|
|
```js
|
|
var morgan = require('morgan')
|
|
```
|
|
|
|
### morgan(format, options)
|
|
|
|
Create a new morgan logger middleware function using the given `format` and `options`.
|
|
The `format` argument may be a string of a predefined name (see below for the names),
|
|
a string of a format string, or a function that will produce a log entry.
|
|
|
|
The `format` function will be called with three arguments `tokens`, `req`, and `res`,
|
|
where `tokens` is an object with all defined tokens, `req` is the HTTP request and `res`
|
|
is the HTTP response. The function is expected to return a string that will be the log
|
|
line, or `undefined` / `null` to skip logging.
|
|
|
|
#### Using a predefined format string
|
|
|
|
<!-- eslint-disable no-undef -->
|
|
|
|
```js
|
|
morgan('tiny')
|
|
```
|
|
|
|
#### Using format string of predefined tokens
|
|
|
|
<!-- eslint-disable no-undef -->
|
|
|
|
```js
|
|
morgan(':method :url :status :res[content-length] - :response-time ms')
|
|
```
|
|
|
|
#### Using a custom format function
|
|
|
|
<!-- eslint-disable no-undef -->
|
|
|
|
``` js
|
|
morgan(function (tokens, req, res) {
|
|
return [
|
|
tokens.method(req, res),
|
|
tokens.url(req, res),
|
|
tokens.status(req, res),
|
|
tokens.res(req, res, 'content-length'), '-',
|
|
tokens['response-time'](req, res), 'ms'
|
|
].join(' ')
|
|
})
|
|
```
|
|
|
|
#### Options
|
|
|
|
Morgan accepts these properties in the options object.
|
|
|
|
##### immediate
|
|
|
|
Write log line on request instead of response. This means that a requests will
|
|
be logged even if the server crashes, _but data from the response (like the
|
|
response code, content length, etc.) cannot be logged_.
|
|
|
|
##### skip
|
|
|
|
Function to determine if logging is skipped, defaults to `false`. This function
|
|
will be called as `skip(req, res)`.
|
|
|
|
<!-- eslint-disable no-undef -->
|
|
|
|
```js
|
|
// EXAMPLE: only log error responses
|
|
morgan('combined', {
|
|
skip: function (req, res) { return res.statusCode < 400 }
|
|
})
|
|
```
|
|
|
|
##### stream
|
|
|
|
Output stream for writing log lines, defaults to `process.stdout`.
|
|
|
|
#### Predefined Formats
|
|
|
|
There are various pre-defined formats provided:
|
|
|
|
##### combined
|
|
|
|
Standard Apache combined log output.
|
|
```
|
|
:remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"
|
|
# will output
|
|
::1 - - [27/Nov/2024:06:21:42 +0000] "GET /combined HTTP/1.1" 200 2 "-" "curl/8.7.1"
|
|
```
|
|
|
|
##### common
|
|
|
|
Standard Apache common log output.
|
|
|
|
```
|
|
:remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]
|
|
# will output
|
|
::1 - - [27/Nov/2024:06:21:46 +0000] "GET /common HTTP/1.1" 200 2
|
|
```
|
|
|
|
##### dev
|
|
|
|
Concise output colored by response status for development use. The `:status`
|
|
token will be colored green for success codes, red for server error codes,
|
|
yellow for client error codes, cyan for redirection codes, and uncolored
|
|
for information codes.
|
|
|
|
```
|
|
:method :url :status :response-time ms - :res[content-length]
|
|
# will output
|
|
GET /dev 200 0.224 ms - 2
|
|
```
|
|
|
|
##### short
|
|
|
|
Shorter than default, also including response time.
|
|
|
|
```
|
|
:remote-addr :remote-user :method :url HTTP/:http-version :status :res[content-length] - :response-time ms
|
|
# will output
|
|
::1 - GET /short HTTP/1.1 200 2 - 0.283 ms
|
|
```
|
|
|
|
##### tiny
|
|
|
|
The minimal output.
|
|
|
|
```
|
|
:method :url :status :res[content-length] - :response-time ms
|
|
# will output
|
|
GET /tiny 200 2 - 0.188 ms
|
|
```
|
|
|
|
#### Tokens
|
|
|
|
##### Creating new tokens
|
|
|
|
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:
|
|
|
|
<!-- eslint-disable no-undef -->
|
|
|
|
```js
|
|
morgan.token('type', function (req, res) { return req.headers['content-type'] })
|
|
```
|
|
|
|
Calling `morgan.token()` using the same name as an existing token will overwrite that
|
|
token definition.
|
|
|
|
The token function is expected to be called with the arguments `req` and `res`, representing
|
|
the HTTP request and HTTP response. Additionally, the token can accept further arguments of
|
|
it's choosing to customize behavior.
|
|
|
|
##### :date[format]
|
|
|
|
The current date and time in UTC. The available formats are:
|
|
|
|
- `clf` for the common log format (`"10/Oct/2000:13:55:36 +0000"`)
|
|
- `iso` for the common ISO 8601 date time format (`2000-10-10T13:55:36.000Z`)
|
|
- `web` for the common RFC 1123 date time format (`Tue, 10 Oct 2000 13:55:36 GMT`)
|
|
|
|
If no format is given, then the default is `web`.
|
|
|
|
##### :http-version
|
|
|
|
The HTTP version of the request.
|
|
|
|
##### :method
|
|
|
|
The HTTP method of the request.
|
|
|
|
##### :referrer
|
|
|
|
The Referrer header of the request. This will use the standard mis-spelled Referer header if exists, otherwise Referrer.
|
|
|
|
##### :remote-addr
|
|
|
|
The remote address of the request. This will use `req.ip`, otherwise the standard `req.connection.remoteAddress` value (socket address).
|
|
|
|
##### :remote-user
|
|
|
|
The user authenticated as part of Basic auth for the request.
|
|
|
|
##### :req[header]
|
|
|
|
The given `header` of the request. If the header is not present, the
|
|
value will be displayed as `"-"` in the log.
|
|
|
|
##### :res[header]
|
|
|
|
The given `header` of the response. If the header is not present, the
|
|
value will be displayed as `"-"` in the log.
|
|
|
|
##### :response-time[digits]
|
|
|
|
The time between the request coming into `morgan` and when the response
|
|
headers are written, in milliseconds.
|
|
|
|
The `digits` argument is a number that specifies the number of digits to
|
|
include on the number, defaulting to `3`, which provides microsecond precision.
|
|
|
|
##### :status
|
|
|
|
The status code of the response.
|
|
|
|
If the request/response cycle completes before a response was sent to the
|
|
client (for example, the TCP socket closed prematurely by a client aborting
|
|
the request), then the status will be empty (displayed as `"-"` in the log).
|
|
|
|
##### :total-time[digits]
|
|
|
|
The time between the request coming into `morgan` and when the response
|
|
has finished being written out to the connection, in milliseconds.
|
|
|
|
The `digits` argument is a number that specifies the number of digits to
|
|
include on the number, defaulting to `3`, which provides microsecond precision.
|
|
|
|
##### :url
|
|
|
|
The URL of the request. This will use `req.originalUrl` if exists, otherwise `req.url`.
|
|
|
|
##### :user-agent
|
|
|
|
The contents of the User-Agent header of the request.
|
|
|
|
### morgan.compile(format)
|
|
|
|
Compile a format string into a `format` function for use by `morgan`. A format string
|
|
is a string that represents a single log line and can utilize token syntax.
|
|
Tokens are references by `:token-name`. If tokens accept arguments, they can
|
|
be passed using `[]`, for example: `:token-name[pretty]` would pass the string
|
|
`'pretty'` as an argument to the token `token-name`.
|
|
|
|
The function returned from `morgan.compile` takes three arguments `tokens`, `req`, and
|
|
`res`, where `tokens` is object with all defined tokens, `req` is the HTTP request and
|
|
`res` is the HTTP response. The function will return a string that will be the log line,
|
|
or `undefined` / `null` to skip logging.
|
|
|
|
Normally formats are defined using `morgan.format(name, format)`, but for certain
|
|
advanced uses, this compile function is directly available.
|
|
|
|
## Examples
|
|
|
|
### express/connect
|
|
|
|
Sample app that will log all request in the Apache combined format to STDOUT
|
|
|
|
```js
|
|
var express = require('express')
|
|
var morgan = require('morgan')
|
|
|
|
var app = express()
|
|
|
|
app.use(morgan('combined'))
|
|
|
|
app.get('/', function (req, res) {
|
|
res.send('hello, world!')
|
|
})
|
|
```
|
|
|
|
### vanilla http server
|
|
|
|
Sample app that will log all request in the Apache combined format to STDOUT
|
|
|
|
```js
|
|
var finalhandler = require('finalhandler')
|
|
var http = require('http')
|
|
var morgan = require('morgan')
|
|
|
|
// create "middleware"
|
|
var logger = morgan('combined')
|
|
|
|
http.createServer(function (req, res) {
|
|
var done = finalhandler(req, res)
|
|
logger(req, res, function (err) {
|
|
if (err) return done(err)
|
|
|
|
// respond to request
|
|
res.setHeader('content-type', 'text/plain')
|
|
res.end('hello, world!')
|
|
})
|
|
})
|
|
```
|
|
|
|
### write logs to a file
|
|
|
|
#### single file
|
|
|
|
Sample app that will log all requests in the Apache combined format to the file
|
|
`access.log`.
|
|
|
|
```js
|
|
var express = require('express')
|
|
var fs = require('fs')
|
|
var morgan = require('morgan')
|
|
var path = require('path')
|
|
|
|
var app = express()
|
|
|
|
// create a write stream (in append mode)
|
|
var accessLogStream = fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
|
|
|
|
// setup the logger
|
|
app.use(morgan('combined', { stream: accessLogStream }))
|
|
|
|
app.get('/', function (req, res) {
|
|
res.send('hello, world!')
|
|
})
|
|
```
|
|
|
|
#### log file rotation
|
|
|
|
Sample app that will log all requests in the Apache combined format to one log
|
|
file per day in the `log/` directory using the
|
|
[rotating-file-stream module](https://www.npmjs.com/package/rotating-file-stream).
|
|
|
|
```js
|
|
var express = require('express')
|
|
var morgan = require('morgan')
|
|
var path = require('path')
|
|
var rfs = require('rotating-file-stream') // version 2.x
|
|
|
|
var app = express()
|
|
|
|
// create a rotating write stream
|
|
var accessLogStream = rfs.createStream('access.log', {
|
|
interval: '1d', // rotate daily
|
|
path: path.join(__dirname, 'log')
|
|
})
|
|
|
|
// setup the logger
|
|
app.use(morgan('combined', { stream: accessLogStream }))
|
|
|
|
app.get('/', function (req, res) {
|
|
res.send('hello, world!')
|
|
})
|
|
```
|
|
|
|
### split / dual logging
|
|
|
|
The `morgan` middleware can be used as many times as needed, enabling
|
|
combinations like:
|
|
|
|
* Log entry on request and one on response
|
|
* Log all requests to file, but errors to console
|
|
* ... and more!
|
|
|
|
Sample app that will log all requests to a file using Apache format, but
|
|
error responses are logged to the console:
|
|
|
|
```js
|
|
var express = require('express')
|
|
var fs = require('fs')
|
|
var morgan = require('morgan')
|
|
var path = require('path')
|
|
|
|
var app = express()
|
|
|
|
// log only 4xx and 5xx responses to console
|
|
app.use(morgan('dev', {
|
|
skip: function (req, res) { return res.statusCode < 400 }
|
|
}))
|
|
|
|
// log all requests to access.log
|
|
app.use(morgan('common', {
|
|
stream: fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
|
|
}))
|
|
|
|
app.get('/', function (req, res) {
|
|
res.send('hello, world!')
|
|
})
|
|
```
|
|
|
|
### use custom token formats
|
|
|
|
Sample app that will use custom token formats. This adds an ID to all requests and displays it using the `:id` token.
|
|
|
|
```js
|
|
var express = require('express')
|
|
var morgan = require('morgan')
|
|
var uuid = require('node-uuid')
|
|
|
|
morgan.token('id', function getId (req) {
|
|
return req.id
|
|
})
|
|
|
|
var app = express()
|
|
|
|
app.use(assignId)
|
|
app.use(morgan(':id :method :url :response-time'))
|
|
|
|
app.get('/', function (req, res) {
|
|
res.send('hello, world!')
|
|
})
|
|
|
|
function assignId (req, res, next) {
|
|
req.id = uuid.v4()
|
|
next()
|
|
}
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|
|
|
|
[ci-image]: https://badgen.net/github/checks/expressjs/morgan/master?label=ci
|
|
[ci-url]: https://github.com/expressjs/morgan/actions/workflows/ci.yml
|
|
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/morgan/master
|
|
[coveralls-url]: https://coveralls.io/r/expressjs/morgan?branch=master
|
|
[npm-downloads-image]: https://badgen.net/npm/dm/morgan
|
|
[npm-url]: https://npmjs.org/package/morgan
|
|
[npm-version-image]: https://badgen.net/npm/v/morgan
|