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.