Sections written: - Getting Started (what-is-openacp, for-users, for-developers, for-contributors) - Platform Setup (Telegram, Discord, Slack) - Using OpenACP (commands, sessions, agents, permissions, voice, files) - Self-Hosting (installation, configuration, daemon, security, logging, updating) - Features (tunnel, context-resume, usage, persistence, handoff, doctor, assistant) - Extending (plugin-system, building-adapters, adapter-reference, contributing) - API Reference (CLI commands, REST API, config schema, env vars) - Troubleshooting (Telegram, Discord, Slack, agent issues, FAQ) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
# Logging
|
|
|
|
## Log Levels
|
|
|
|
OpenACP uses [Pino](https://github.com/pinojs/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
|
|
|
|
```json
|
|
"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:
|
|
|
|
```bash
|
|
openacp logs
|
|
```
|
|
|
|
Or directly:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{"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 |
|