feat: comprehensive logging across parser, app, persistence, runtime (X1)
Completes the X1 full sweep started in a8ad0c6 (db.rs). Closes X1 -> [x].
- persistence/mod.rs: debug! on every yaml/CSV/history write -- the
silent-failure-prone disk paths (write_schema, write_table_data incl.
the empty->delete branch, append_history/_failure).
- runtime.rs: debug! on execute_command_typed dispatch (one per executed
command, complements the db.rs executor logs).
- app.rs: debug! on submit (route + submission mode), dispatch_app_command,
and the ADR-0044 diagram-vs-prose render-mode choice.
- dsl/parser.rs: trace! on parse begin/outcome at the parse_command_inner
choke point -- trace, not debug, because the live overlay/completion
re-parse per keystroke (hot path).
- logging.rs: documented level discipline (error/warn/info/debug/trace) so
the convention survives across sessions.
Levels verified end-to-end through the real worker thread + logging::init.
~75 -> 135 tracing sites total. Tests: 2207 pass / 0 fail / 1 ignored.
Clippy clean.
This commit is contained in:
@@ -6,6 +6,38 @@
|
||||
//! environment variable; if neither is set we default to
|
||||
//! `~/.rdbms-playground/playground.log` and create directories as
|
||||
//! needed.
|
||||
//!
|
||||
//! ## Level conventions (X1 — `requirements.md`)
|
||||
//!
|
||||
//! Instrumentation across the tree follows a consistent level
|
||||
//! discipline so the default `info` filter stays quiet and
|
||||
//! `RDBMS_PLAYGROUND_LOG=debug` (or `=trace`) is a rich, layered
|
||||
//! diagnostic stream. The env filter (`RDBMS_PLAYGROUND_LOG`,
|
||||
//! full `EnvFilter` syntax) controls this independently of the
|
||||
//! file path above; the default is `info`.
|
||||
//!
|
||||
//! - **`error!`** — unrecoverable failure (fatal persistence, a
|
||||
//! panic-equivalent). The process is going down or a command is
|
||||
//! hard-failing.
|
||||
//! - **`warn!`** — recoverable failure or a fallback taken (a
|
||||
//! snapshot couldn't be staged, a `PRAGMA` couldn't be restored,
|
||||
//! an integrity check rolled a rebuild back).
|
||||
//! - **`info!`** — low-volume lifecycle, visible by default: db
|
||||
//! worker start/exit, project create/open, "logging initialised".
|
||||
//! - **`debug!`** — the bulk of instrumentation, one line per
|
||||
//! *executed* command and the decision points within it (executor
|
||||
//! entry with key params, autofill/cascade summaries, the
|
||||
//! rebuild-table primitive, persistence writes, render-mode
|
||||
//! choice). Off by default.
|
||||
//! - **`trace!`** — hot paths only: per-keystroke parsing
|
||||
//! (`dsl::parser`), per-key input handling (`app`), per-refresh
|
||||
//! table reads. A firehose; never on except when debugging that
|
||||
//! specific layer.
|
||||
//!
|
||||
//! Rule of thumb for new code: a loop logs a single summary count,
|
||||
//! never per-iteration at `debug`/`info`. Logs are developer-facing,
|
||||
//! so naming the engine (SQLite/PRAGMA) is fine here even though the
|
||||
//! "no engine name" rule (ADR-0002) forbids it in user-facing strings.
|
||||
|
||||
use std::fs::{File, OpenOptions, create_dir_all};
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
Reference in New Issue
Block a user