@jnode/server-log

Official logger for JNS.

Installation

npm i @jnode/server-log

Quick start

Import

const { createServer, routerConstructors: r, handlerConstructors: h } = require('@jnode/server');
const { routerConstructors: lr } = require('@jnode/server-log');

Start a server with logging

const server = createServer(
  // wrap your root router with lr.Log
  lr.Log(
    r.Path(h.Text('Hello, world!'), {
      '/api': h.JSON({ ok: true })
    }),
    {
      // Optional: Log to files in the './logs' directory
      folder: './logs'
    }
  )
);

server.listen(8080);

How it works?

LogRouter is a specialized router that sits in front of your application logic. When a request arrives, it records the start time and injects a finalizeLog function into the ctx. It then passes the request to the next router or handler.

Once the response is finished (or a timeout is reached), it gathers information about the request (such as status code, method, and response time) and outputs it to the console and/or a log file.

Reference

Routers

Router: Log(next[, options])

• next router | handler-extended The next step in the routing chain.
• options <Object>
  • folder <string> The directory to save log files. If set, files will be named by date (e.g., 2023-12-31.log).
  • consoleItems <string[]> Array of item keys to display in the console. Default: ['localTime', 'statusCode', 'method', 'url', 'ip', 'responseTime'].
  • fileItems <string[]> Array of item keys to write to the log file. Default: ['iso', 'statusCode', 'method', 'url', 'ip', 'ua', 'responseTime'].
  • itemRegistery <Object> Custom log item functions.
  • disableConsoleLog <boolean> Disable logging to the console. Default: false.
  • plainConsoleLog <boolean> Disable ANSI colors in console output. Default: false.
  • sep <string> The separator between log items. Default: ' ' (space).
  • forceLog <number> Timeout in milliseconds to force log if the response hasn't finished. Default: 10000.

Records request metadata and logs it upon completion. It also adds a ctx.finalizeLog function, allowing handlers (like WebSocket upgrades) to trigger logging manually before the connection context changes.

The LogRouter will add a function .finalizeLog into ctx, when any of later router/handlers wants to log write away (e.g. the WebSocket-related requests) they could call this.

Log Items

Built-in Log Items

These keys can be used in consoleItems or fileItems:

| Item Key | Description | Example Output | | :--- | :--- | :--- | | local | Local date and time | [12/31/2023, 14:30:05] | | localTime | Local time string | [14:30:05] | | localDate | Local date string | [12/31/2023] | | iso | UTC ISO 8601 string | [2023-12-31T14:30:05.000Z] | | isoTime | UTC ISO time part | [14:30:05.000Z] | | isoDate | UTC ISO date part | [2023-12-31] | | timestamp | Unix timestamp (ms) | [1704024000000] | | responseTime| Request duration | 5ms (Green/Yellow/Red) | | method | HTTP method | GET, POST (Blue) | | statusCode | HTTP status code | 200, 404, 500 (Colored) | | path | URL pathname | /api/data | | url | Host + URL | example.com/api/data | | host | Hostname | example.com | | ip | Client IP address | 127.0.0.1 | | ua | User-Agent header | "Mozilla/5.0..." | | referer | Referer header | https://google.com/ | | depth | Routing step count | @2 (Cyan) |

Custom Log Items

You can define custom log items via the itemRegistery option or by passing a function directly into the items array.

The function signature is: (time, env, ctx, plain, styled) => void

• time <Date> The start time of the request.
• env <Object> JNS environment object.
• ctx <Object> JNS context object.
• plain <string[]> Push text here for file logs and plain console logs.
• styled <string[]> Push text with ANSI escape codes here for styled console logs.

Example:

lr.Log(next, {
  itemRegistery: {
    hello: (time, env, ctx, plain, styled) => {
      plain.push('HELLO');
      styled.push('\x1b[32mHELLO\x1b[0m'); // Green HELLO
    }
  },
  consoleItems: ['localTime', 'hello', 'path']
});