ecs-pretty

A CLI tool that transforms ECS-format JSON logs into colorized, human-readable output.

node my-app.js | ecs-pretty

Example

Given this ECS log input:

{"@timestamp":"2026-03-19T10:22:01.003Z","log.level":"info","message":"Request completed","log.logger":"http.server","process.pid":4821,"http.request.method":"GET","url.path":"/api/health","http.response.status_code":200}

Output:

━━ INFO ━━ 10:22:01.003 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Request completed
  logger: http.server  pid: 4821
  http.request.method: GET
  url.path: /api/health
  http.response.status_code: 200

Install

npm i -g ecs-pretty

Requires Node.js >= 18.3.

Options

--no-color             Disable colorized output
--color                Force colorized output (even non-TTY)
--separator <style>    heavy, line, double, blank, none (default: heavy)
--timestamp-format <f> time, short, iso, relative (default: time)
--include-fields <f>   Comma-separated fields to always show
--exclude-fields <f>   Comma-separated fields to hide
--level-filter <l>     Minimum log level to display (default: trace)
-h, --help             Show help
-v, --version          Show version

Pino Transport

Use ecs-pretty directly as a pino transport — no child process needed:

import pino from "pino";

const logger = pino(
  pino.transport({
    target: "ecs-pretty/transport",
    options: { separator: "line" },
  })
);

logger.info({ "service.name": "my-app" }, "hello from transport");

Transport Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | colorize | boolean | auto (TTY) | true = force color, false = no color | | separator | string | "heavy" | heavy, line, double, blank, none | | timestampFormat | string | "time" | time, short, iso, relative | | includeFields | string[] | [] | Fields to always show | | excludeFields | string[] | [] | Fields to hide | | levelFilter | string | "trace" | Minimum log level to display |

Features

• Non-JSON lines pass through unchanged
• Color-coded log levels (fatal, error, warn, info, debug, trace)
• Nested objects flattened to dot-notation
• Error stack traces preserved and colored
• Respects NO_COLOR env var and auto-detects non-TTY
• Handles SIGPIPE cleanly when piped to head, grep, etc.