mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-27 23:47:28 +00:00
docs(agents): make the structured-logging rule reachable and enforceable (#5828)
The RustFS event shape (`event`/`component`/`subsystem`/`result` + context, message last) is specified only in `.agents/skills/rustfs-logging-governance/SKILL.md`, and nothing routes a change to it: - `AGENTS.md`, which is what an agent actually loads by default, never mentions logging. Its only related line is "log unknown fields at `warn`" under Serde Safety, which is about level, not shape. - The skill's `description` says "use when editing or reviewing RustFS logs", so a bugfix that adds one log line in passing — how most new log sites enter this repo — never matches it. - `scripts/check_logging_guardrails.sh` is a blocklist: 500+ `rg -F` literals that retire log lines which already shipped. It cannot see a newly written one. For `crates/ecstore/src/disk/local.rs` the only check is that `#[tracing::instrument]` is TRACE-only; `warn!`/`info!` shape is unchecked. PR #5822 landed `warn!("heal rename_data: purging ... {:?} failed: {}", ...)` in `disk/local.rs` — sentence-style, no fields, directly beside `info!(event = EVENT_DISK_LOCAL_RENAME_REJECTED, component = ..., subsystem = ...)` — with every check green. That is the gap, not an authoring mistake. Close all three: - `AGENTS.md`: a Logging section stating the field shape, the level policy, the reuse-the-file's-constants rule, and that it applies to any `tracing` macro added in passing, not only to log-focused changes. - Skill `description`: trigger on adding or editing any `tracing` macro, naming the single-line-added-in-passing case explicitly. - Guardrail: assert the event shape positively on the already-governed disk files — `error!`/`warn!`/`info!` must open with fields or a `target:`, never a bare string. Commented-out macros are excluded; `debug!`/`trace!` stay out of scope as targeted diagnostics. Self-test fixtures cover both directions. `crates/ecstore/src/disk/mod.rs` carried the one live violation in that file set (`conv_part_err_to_int`), so it is converted here; the guardrail would otherwise fail on an untouched file. Verification: - `./scripts/check_logging_guardrails.sh` — passes - Negative control: re-inserting PR #5822's exact `warn!` line into `disk/local.rs` makes it exit 1 pointing at that line - `cargo fmt -p rustfs-ecstore -- --check`, `cargo check -p rustfs-ecstore`
This commit is contained in:
@@ -42,6 +42,10 @@ pub const PART_TRANSACTION_NEW_META: &str = "new.meta";
|
||||
pub const PART_TRANSACTION_OLD_META: &str = "old.meta";
|
||||
pub const PART_TRANSACTION_ROLLBACK: &str = "rollback";
|
||||
|
||||
const LOG_COMPONENT_ECSTORE: &str = "ecstore";
|
||||
const LOG_SUBSYSTEM_DISK: &str = "disk";
|
||||
const EVENT_DISK_PART_ERR_UNCLASSIFIED: &str = "disk_part_err_unclassified";
|
||||
|
||||
pub fn part_transaction_path(part_path: &str) -> String {
|
||||
match part_path.rsplit_once('/') {
|
||||
Some((parent, name)) => format!("{parent}/.{name}.rustfs-txn"),
|
||||
@@ -1196,7 +1200,13 @@ pub fn conv_part_err_to_int(err: &Option<Error>) -> usize {
|
||||
Some(DiskError::DiskNotFound) => CHECK_PART_DISK_NOT_FOUND,
|
||||
None => CHECK_PART_SUCCESS,
|
||||
_ => {
|
||||
tracing::warn!("conv_part_err_to_int: unknown error: {err:?}");
|
||||
tracing::warn!(
|
||||
event = EVENT_DISK_PART_ERR_UNCLASSIFIED,
|
||||
component = LOG_COMPONENT_ECSTORE,
|
||||
subsystem = LOG_SUBSYSTEM_DISK,
|
||||
error = ?err,
|
||||
"Part error has no check-part code and degrades to unknown"
|
||||
);
|
||||
CHECK_PART_UNKNOWN
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user