EKOSdocs
Docs / Operations Operate

Logging

Log levels, JSON output, structured run logs and where diagnostics go.

Logging uses tracing. Configure in ekos.toml:

[workspace]
log-level = "info"
log-format = "json"       # "pretty" for terminals

EKOS_LOG (a tracing env filter, e.g. EKOS_LOG=ekos_recovery=debug,info) and EKOS_LOG_FORMAT override the config for one run.

Run logs (RFC 0220)

build, recover, resolve, compile and commit — and every command whose catalogue class is write, review, admin or external — write a run log: JSON lines with a fixed key order, one per step with its counts (started, connector scans, each catalog query with rows and milliseconds, a passes summary, the stage's statistics), warnings copied redacted (the first 200, then counted), then an llm line with the model calls the run made — completions, cache hits and embedding requests counted separately — and a run finished line with the outcome.

Where When
$EKOS_RUN_LOG when set (the console sets one file per run)
<state dir>/runs/<UTC stamp>-<command>.jsonl otherwise

The terminal does not repeat these lines unless EKOS_LOG asks for their targets (ekos_run_log, ekos_model_call). The console serves a run's lines at GET /api/runs/<id>/events. On a large Oracle estate a full five-command run settled at 72 lines (12 KB), with llm showing 0 calls (devlog_292).

Diagnostics and other logs

Stage diagnostics are also written to .ekos/diagnostics/ (for example compile.log) — that is where the reason behind a summary count of warnings lives. The console keeps its own log and run logs under <home>/control/; ekos console logs shows the end of it. On Azure Container Apps a stopped revision's console output is kept only in Log Analytics.

Do not log content you would not store: redaction protects the ledger, artifacts and the warnings copied into run logs, but raw source printed to a debug log is not redacted.