@e9n/pi-logger

Event bus logger for pi. Subscribes to events on the shared event bus and writes structured JSONL log files, one per day.

Features

• Captures any event on the pi event bus as a structured log entry
• Writes JSONL files named YYYY-MM-DD.jsonl, one per day
• Global scope — all sessions write to ~/.pi/agent/logs/
• Project scope — logs write to .pi/logs/ next to project code
• Configurable minimum level, event whitelist/ignore, and channel whitelist/ignore
• Level inferred from event name when not explicitly set
• Timestamps use the configured IANA timezone (defaults to system timezone)
• Runtime control via /logger command — change level, scope, or reload settings without restarting

Setup / Settings

Add to ~/.pi/agent/settings.json (global) or .pi/settings.json (project):

{
  "pi-logger": {
    "level": "INFO",
    "scope": "global",
    "timezone": "Europe/Oslo",
    "events_whitelist": ["log"],
    "events_ignore": [],
    "channels_whitelist": [],
    "channels_ignore": []
  }
}

| Key | Default | Description | |-----|---------|-------------| | level | "INFO" | Minimum log level: DEBUG, INFO, WARN, ERROR. | | scope | "global" | "global" → ~/.pi/agent/logs/, "project" → .pi/logs/. | | timezone | System tz | IANA timezone for timestamps (e.g. "Europe/Oslo"). | | events_whitelist | ["log"] | Bus event prefixes to subscribe to. [] = capture all known events. | | events_ignore | [] | Bus event prefixes to skip (applied after whitelist). | | channels_whitelist | [] | Channels to accept in the log handler. [] = all. | | channels_ignore | [] | Channels to drop in the log handler. |

Logging from extensions

Emit structured log entries via the "log" bus event:

// Channel + level
pi.events.emit("log", { channel: "myext", level: "WARN", data: { msg: "something odd" } });

// Channel + sub-event
pi.events.emit("log", { channel: "myext", event: "request", data: { path: "/api" } });

// Shorthand by level (level inferred from event name)
pi.events.emit("log:error", { event: "myext:crash", data: { message: "oops" } });
pi.events.emit("log:warn",  { event: "myext:slow",  data: { ms: 2000 } });

Level inference

Events are assigned a level from their name when no explicit level is given:

| Pattern in event name | Level | |-----------------------|-------| | error or fail | ERROR | | warn or alert | WARN | | debug | DEBUG | | Anything else | INFO |

Log format

Each line is a JSON object:

{"ts":"2026-02-12T11:24:17.123+01:00","level":"INFO","channel":"heartbeat","event":"result","data":{"ok":true,"durationMs":3200}}

The bus event name is split on the first : into channel and event:
heartbeat:result → channel: "heartbeat", event: "result"

Known bus events captured

channel:send/receive/register · cron:job_start/job_complete/add/remove/enable/disable/run/status/reload · heartbeat:check/result · jobs:recorded · web:mount/unmount/mount-api/unmount-api/ready · kysely:ready/ack

For events not in this list, use the log / log:* protocol above.

Commands

| Command | Description | |---------|-------------| | /logger or /logger status | Show current settings and active subscription count | | /logger level <DEBUG\|INFO\|WARN\|ERROR> | Change minimum log level for the current session | | /logger scope <global\|project> | Change log scope for the current session | | /logger reload | Reload settings from disk and resubscribe to events |

Install

pi install npm:@e9n/pi-logger

License

MIT