middleware morgan

middleware de registro de peticiones HTTP para node.js

Nombrado por Dexter, una serie que no deberías ver hasta el final.

Instalación

Este es un módulo de Node.js disponible a través del registro npm. La instalación se hace usando el comando npm install:

npm install morgan

API

var morgan = require('morgan');

Crea una nueva función de middleware de registro morgan usando el format y las options dadas. El argumento format puede ser una cadena con un nombre predefinido (ver abajo los nombres), una cadena de formato, o una función que producirá una entrada de registro.

La función format será llamada con tres argumentos tokens, req, y res, donde tokens es un objeto con todos los tokens definidos, req es la petición HTTP y res es la respuesta HTTP. Se espera que la función devuelva una cadena que será la línea de registro, o undefined / null para omitir el registro.

Usar una cadena de formato predefinido

morgan('tiny');

Usar una cadena de formato con tokens predefinidos

morgan(':method :url :status :res[content-length] - :response-time ms');

Usar una función de formato personalizada

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'](https://github.com/expressjs/morgan/blob/HEAD/req, res), 'ms'
  ].join(' ')
})

Opciones

Morgan acepta estas propiedades en el objeto de opciones.

immediate

Escribe la línea de registro en la petición en lugar de en la respuesta. Esto significa que las peticiones se registrarán incluso si el servidor falla, pero los datos de la respuesta (como el código de respuesta, longitud del contenido, etc.) no pueden registrarse.

skip

Función para determinar si se omite el registro, por defecto false. Esta función se llamará como skip(req, res).

// EXAMPLE: only log error responses
morgan('combined', {
  skip: function (req, res) {
    return res.statusCode < 400;
  },
});

stream

Flujo de salida para escribir las líneas de registro, por defecto process.stdout.

Formatos predefinidos

Hay varios formatos predefinidos proporcionados:

combined

Salida combinada estándar de Apache.

: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

Salida común estándar de Apache.

: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

Salida concisa coloreada por el estado de la respuesta para uso en desarrollo. El token :status se coloreará verde para códigos de éxito, rojo para códigos de error del servidor, amarillo para códigos de error del cliente, cian para códigos de redirección, y sin color para códigos informativos.

:method :url :status :response-time ms - :res[content-length]
# will output
GET /dev 200 0.224 ms - 2

short

Más corto que el por defecto, incluyendo también el tiempo de respuesta.

: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

La salida mínima.

:method :url :status :res[content-length] - :response-time ms
# will output
GET /tiny 200 2 - 0.188 ms

Tokens

Crear nuevos tokens

Para definir un token, simplemente invoca morgan.token() con el nombre y una función callback. Se espera que esta función callback devuelva un valor de cadena. El valor devuelto estará luego disponible como ":type" en este caso:

morgan.token('type', function (req, res) {
  return req.headers['content-type'];
});

Llamar a morgan.token() usando el mismo nombre que un token existente sobrescribirá esa definición de token.

Se espera que la función del token sea llamada con los argumentos req y res, representando la petición HTTP y la respuesta HTTP. Además, el token puede aceptar argumentos adicionales a su elección para personalizar el comportamiento.

:date[format]

La fecha y hora actual en UTC. Los formatos disponibles son:

clf para el formato de registro común ("10/Oct/2000:13:55:36 +0000")
iso para el formato de fecha y hora ISO 8601 común (2000-10-10T13:55:36.000Z)
web para el formato de fecha y hora RFC 1123 común (Tue, 10 Oct 2000 13:55:36 GMT)

Si no se proporciona ningún formato, el valor por defecto es web.

:http-version

La versión HTTP de la petición.

:method

El método HTTP de la petición.

:pid

El ID del proceso de Node.js que maneja la petición.

:referrer

El encabezado Referrer de la petición. Usará el encabezado Referer mal escrito estándar si existe, de lo contrario Referrer.

:remote-addr

La dirección remota de la petición. Usará req.ip, de lo contrario el valor estándar de req.connection.remoteAddress (dirección del socket).

:remote-user

El usuario autenticado como parte de la autenticación Basic para la petición.

:req[header]

El header dado de la petición. Si el encabezado no está presente, el valor se mostrará como "-" en el registro.

:res[header]

El header dado de la respuesta. Si el encabezado no está presente, el valor se mostrará como "-" en el registro.

:response-time[digits]

El tiempo entre la entrada de la petición a morgan y cuando los encabezados de respuesta se escriben, en milisegundos.

El argumento digits es un número que especifica el número de dígitos a incluir en el número, por defecto 3, que proporciona precisión de microsegundos.

:status

El código de estado de la respuesta.

Si el ciclo petición/respuesta se completa antes de que se envíe una respuesta al cliente (por ejemplo, el socket TCP se cerró prematuramente por un cliente que abortó la petición), entonces el estado estará vacío (mostrado como "-" en el registro).

:total-time[digits]

El tiempo entre la entrada de la petición a morgan y cuando la respuesta ha terminado de escribirse en la conexión, en milisegundos.

El argumento digits es un número que especifica el número de dígitos a incluir en el número, por defecto 3, que proporciona precisión de microsegundos.

:url

La URL de la petición. Usará req.originalUrl si existe, de lo contrario req.url.

:user-agent

El contenido del encabezado User-Agent de la petición.

morgan.compile(format)

Compila una cadena de formato en una función format para su uso por morgan. Una cadena de formato es una cadena que representa una sola línea de registro y puede utilizar la sintaxis de tokens. Los tokens se referencian por :token-name. Si los tokens aceptan argumentos, pueden pasarse usando [], por ejemplo: :token-name[pretty] pasaría la cadena 'pretty' como argumento al token token-name.

La función devuelta por morgan.compile toma tres argumentos tokens, req, y res, donde tokens es un objeto con todos los tokens definidos, req es la petición HTTP y res es la respuesta HTTP. La función devolverá una cadena que será la línea de registro, o undefined / null para omitir el registro.

Normalmente los formatos se definen usando morgan.format(name, format), pero para ciertos usos avanzados, esta función de compilación está disponible directamente.

Ejemplos

express/connect

Aplicación de ejemplo que registrará todas las peticiones en formato combinado de Apache a STDOUT

var express = require('express');
var morgan = require('morgan');

var app = express();

app.use(morgan('combined'));

app.get('/', function (req, res) {
  res.send('hello, world!');
});

servidor http vanilla

Aplicación de ejemplo que registrará todas las peticiones en formato combinado de Apache a STDOUT

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!');
  });
});

escribir logs a un archivo

archivo único

Aplicación de ejemplo que registrará todas las peticiones en formato combinado de Apache al archivo access.log.

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!');
});

rotación de archivo de registro

Aplicación de ejemplo que registrará todas las peticiones en formato combinado de Apache en un archivo de registro por día en el directorio log/ usando el módulo rotating-file-stream.

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!');
});

registro dividido / dual

El middleware morgan puede usarse tantas veces como sea necesario, permitiendo combinaciones como:

Entrada de registro al hacer la petición y otra al responder
Registrar todas las peticiones a archivo, pero los errores a consola
… y más!

Aplicación de ejemplo que registrará todas las peticiones a un archivo en formato Apache, pero las respuestas de error se registran en la consola:

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!');
});

usar formatos de token personalizados

Aplicación de ejemplo que usará formatos de token personalizados. Esto añade un ID a todas las peticiones y lo muestra usando el token :id.

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();
}

Licencia

MIT