Logging

Log Levels

OpenACP uses Pino for structured logging. The valid levels, in ascending severity order, are:

Level	When to use
silent	Suppress all output
debug	Verbose internals — ACP events, session state transitions, config loads
info	Normal operational events — server start, session created/completed, channel connected
warn	Non-fatal issues — stale PID file, insecure file permissions, failed validation with fallback
error	Failures that affect functionality but do not crash the process
fatal	Unrecoverable errors before process exit

The default level is info.

Configuration

"logging": {
  "level": "info",
  "logDir": "~/.openacp/logs",
  "maxFileSize": "10m",
  "maxFiles": 7,
  "sessionLogRetentionDays": 30
}

Field	Type	Default	Description
level	string	"info"	Minimum level to emit
logDir	string	"~/.openacp/logs"	Directory for log files. ~ is expanded to the home directory.
maxFileSize	string | number	"10m"	Maximum size per log file before rotation. Accepts bytes or suffixes: k, m, g.
maxFiles	number	7	Number of rotated log files to keep.
sessionLogRetentionDays	number	30	Per-session log files older than this are deleted at startup.

Change these values via openacp config (Logging section) or by editing ~/.openacp/config.json directly.

Log Files

The main log file is:

~/.openacp/logs/openacp.log

This file receives all log output from the running process, including the daemon's stdout and stderr when in daemon mode. It is rotated using pino-roll when it reaches maxFileSize. Up to maxFiles rotated files are retained.

To tail the log in real time:

openacp logs

Or directly:

tail -f ~/.openacp/logs/openacp.log

Per-Session Logs

Each session gets its own log file under:

~/.openacp/logs/sessions/<sessionId>.log

Session log entries are written simultaneously to the session file and to the main openacp.log (with the sessionId field present on every record). This lets you review a single session's history in isolation without filtering the combined log.

Session log files are cleaned up automatically at startup. Any file in ~/.openacp/logs/sessions/ whose last modification time is older than sessionLogRetentionDays days is deleted.

Debug Mode

To enable debug logging without editing the config file, set OPENACP_DEBUG=true:

OPENACP_DEBUG=true openacp start

This sets the log level to debug at runtime, provided OPENACP_LOG_LEVEL is not also set. Debug output includes:

• Full ACP event payloads from agent subprocesses

• Session state machine transitions

• Config load and migration details

• API request routing

You can also override the level directly:

OPENACP_LOG_LEVEL=debug openacp start

Structured JSON Format

Log entries are written to files as newline-delimited JSON (Pino's default format). Each line is a self-contained JSON object. Example:

{"level":30,"time":1711234567890,"pid":12345,"hostname":"host","module":"core","msg":"Server started","port":21420}

The terminal transport uses pino-pretty for human-readable coloured output. The file transport writes raw JSON for easy ingestion by log aggregators (Loki, Datadog, etc.).

Common fields on every log record:

Field	Description
level	Numeric Pino level (10=trace, 20=debug, 30=info, 40=warn, 50=error, 60=fatal)
time	Unix timestamp in milliseconds
module	Source module (e.g., "core", "session", "api-server")
sessionId	Present on session-scoped records
msg	Human-readable message