Operations runbook

Where the data lives

The app resolves the database path in this order: LOGGERHEAD_DB_PATH, then DATA_DIR/loggerhead.db, then the per-OS default. On a Mac the default is:

~/Library/Application Support/Loggerhead/loggerhead.db

The schema is versioned and migrates at start. There is no manual migration step.

Reset the database

1. Quit Loggerhead.
2. Delete the database file.
3. Open Loggerhead. It creates a new file.

Look at the file directly

DuckDB allows one process on the file. While Loggerhead runs, a second opener fails, even read-only. Read the data through the MCP server instead. To open the file in the DuckDB CLI, quit Loggerhead first.

Retention

The app keeps retention_days of data and runs cleanup on a schedule. Change the number on the Settings page. To empty the database now, use Settings › Storage › Clear. That step deletes every log, trace, and metric, and you cannot undo it.

Troubleshooting

Nothing shows up. Read the effective ports on the Collectors page, or ask your AI coding tool to call get_receiver_info. Confirm the producer or the branch sends to that port. Confirm the branch stamps loggerhead.collector.id. The Collectors page shows last-seen and error counts for each collector.

The port moved. Another program holds 4317 or 4318. The root moved along the ladder. Copy the effective port from the Collectors page. See Ports and the effective port.

A remote branch is rejected. The token on the branch does not match ingest_token, or the branch does not trust the receiver’s certificate. Loopback producers are exempt, so if it works locally and not remotely, the token or TLS is the difference.

A page says “Database not open”. The app could not open its database file. Another copy of Loggerhead may hold it, because DuckDB allows one writer. Quit every copy, then open the app again.