ADR 0007: Logging policy
- Status: Accepted
- Date: 2026-10-19
Context
The code review found that:
- Expected errors (read-only mode, invalid argument, permission denied) are stored as
errorwith a stack trace, which pollutes recent errors and statistics. - Every call writes two entries ("started" and "completed") that duplicate the
executionstable. - Reading the logs opens executions and counts them as activity.
- Parameters are stored with their value, and they may be personal data.
- Calls to Databricks leave no trace: retries, chosen warehouse, token refresh, duration of the read-only check and
401rejections.
Decision
DakErrors are stored aswarnwithout a stack trace; only unexpected errors areerrorwith a stack trace.- One entry per call, when it ends, with tool, arguments, duration and a summary of the result (
statementId,warehouseId, state, rows,truncated). - Of the SQL, the first 4 KB are stored; of the parameters, name and type, not the value.
- Reading
resource://logs/*does not open executions. - The following are logged: retries (
warn), the warehouse choice (info), token refresh and every HTTP request (debug), the start and end of each export (info) and HTTP401rejections (warn, limited to one per minute).
Details in section 6 of the design.
Consequences
- Recent errors and statistics reflect real failures.
- The volume of logs drops for normal calls and grows only at the
debuglevel. - The value of a parameter cannot be reconstructed from the logs; the SQL remains the main data for analysis.
- The test that expects a stack trace on a SQL failure (
test/server.test.ts) must change.