diff options
Diffstat (limited to 'node_modules/morgan/README.md')
| -rw-r--r-- | node_modules/morgan/README.md | 414 |
1 files changed, 0 insertions, 414 deletions
diff --git a/node_modules/morgan/README.md b/node_modules/morgan/README.md deleted file mode 100644 index ba8b256..0000000 --- a/node_modules/morgan/README.md +++ /dev/null @@ -1,414 +0,0 @@ -# morgan - -[![NPM Version][npm-image]][npm-url] -[![NPM Downloads][downloads-image]][downloads-url] -[![Build Status][travis-image]][travis-url] -[![Test Coverage][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. - -## 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" -``` - -##### common - -Standard Apache common log output. - -``` -:remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] -``` - -##### dev - -Concise output colored by response status for development use. The `:status` -token will be colored red for server error codes, yellow for client error -codes, cyan for redirection codes, and uncolored for all other codes. - -``` -:method :url :status :response-time ms - :res[content-length] -``` - -##### short - -Shorter than default, also including response time. - -``` -:remote-addr :remote-user :method :url HTTP/:http-version :status :res[content-length] - :response-time ms -``` - -##### tiny - -The minimal output. - -``` -:method :url :status :res[content-length] - :response-time 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). - -##### :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 - -Simple 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 - -Simple 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 - -Simple 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 - -Simple 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 fs = require('fs') -var morgan = require('morgan') -var path = require('path') -var rfs = require('rotating-file-stream') - -var app = express() -var logDirectory = path.join(__dirname, 'log') - -// ensure log directory exists -fs.existsSync(logDirectory) || fs.mkdirSync(logDirectory) - -// create a rotating write stream -var accessLogStream = rfs('access.log', { - interval: '1d', // rotate daily - path: logDirectory -}) - -// 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) - -[npm-image]: https://img.shields.io/npm/v/morgan.svg -[npm-url]: https://npmjs.org/package/morgan -[travis-image]: https://img.shields.io/travis/expressjs/morgan/master.svg -[travis-url]: https://travis-ci.org/expressjs/morgan -[coveralls-image]: https://img.shields.io/coveralls/expressjs/morgan/master.svg -[coveralls-url]: https://coveralls.io/r/expressjs/morgan?branch=master -[downloads-image]: https://img.shields.io/npm/dm/morgan.svg -[downloads-url]: https://npmjs.org/package/morgan |