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.