loglens

loglens

loglens investigates homelab logs held in a local file: what the store holds, what arrived most recently, what errored, what mentions a term, how volume is spread over time, and what surrounded a moment. One binary serves a command-line interface and a stdio MCP server exposing a single action-dispatched tool, cortex.

This is a labelled core subset. The tool it is modelled on dispatches 60 catalog actions; loglens implements seven of them — status, tail, errors, search, timeline, context, and help — and omits the other 53 (fleet and topology views, AI session analysis, correlation and anomaly analysis, error acknowledgement, notifications, and administration). The help action lists the implemented subset and the omitted actions at runtime.

Log file

Records live in a JSONL file: one JSON object per line, each with ts (an ISO-8601 timestamp), level, source, and message:

{"ts":"2026-10-26T09:15:00.000Z","level":"info","source":"docker/web","message":"container started"}
{"ts":"2026-10-26T09:16:12.000Z","level":"error","source":"syslog","message":"disk almost full"}

The path comes from --file on the CLI, then the LOGLENS_LOG_FILE environment variable, then ./loglens.jsonl. Malformed lines (bad JSON, missing fields, unparseable timestamps) are skipped and counted, never fatal. A missing file is a clean error for data actions; status instead reports the store state with exists: false, and help needs no store at all. All logic is local and deterministic — no network access, ever.

Install

npx @reneturcios/loglens status

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/loglens

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead. Mount your log file and set LOGLENS_LOG_FILE to its in-container path.

CLI

export LOGLENS_LOG_FILE=/var/log/homelab.jsonl

loglens status
loglens tail --limit 5 --source docker/web
loglens errors --limit 10
loglens search "disk" --since 2026-10-26T00:00:00.000Z
loglens timeline --bucket day
loglens context 2026-10-26T09:16:12.000Z --window-minutes 5
loglens context 12 --limit 3
loglens help

loglens --version

Commands print a JSON result. tail, errors, and search return records newest first; context returns them in file order. context accepts either a timestamp (records within --window-minutes of it, or the --limit nearest records around the closest one) or a bare record index (the --limit records on either side of that position). Exit codes: 0 on success, 1 when an operation fails (including a missing log file), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/loglens mcp

MCP client configuration:

{
  "mcpServers": {
    "loglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/loglens", "mcp"],
      "env": { "LOGLENS_LOG_FILE": "/absolute/path/to/logs.jsonl" }
    }
  }
}

Tool

Tool	Input	What it returns
cortex	action (required, one of status, tail, errors, search, timeline, context, help), plus optional query, source, level, limit, since, until, bucket (hour or day), timestamp, window_minutes	Per action: a store summary, the latest matching records, hourly/daily volume buckets, records around a moment, or the subset help text.

A useful first call is {"action":"status"}, then narrow with tail, errors, search, timeline, or context.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real temp JSONL files, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.