# 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`:

```json
{"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

```bash
npx @reneturcios/loglens status
```

Or run the container image:

```bash
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

```bash
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:

```bash
npx -y @reneturcios/loglens mcp
```

MCP client configuration:

```json
{
  "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

```bash
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`.