mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-30 00:47:13 +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:
@@ -322,6 +322,28 @@ High risk: all seven roles.
|
||||
- Use environment variables or vault tooling for sensitive configuration.
|
||||
- For localhost-sensitive tests, verify proxy settings to avoid traffic leakage.
|
||||
|
||||
## Logging
|
||||
|
||||
Applies to **every** `tracing` macro you add or edit, including a single line
|
||||
added in passing while fixing something else — not only to log-focused changes.
|
||||
|
||||
- Fields first, message second: `event`, `component`, `subsystem`,
|
||||
`result`/`state`, then key context. The message is a short label, not a
|
||||
sentence with values interpolated into it.
|
||||
- Reuse the existing `EVENT_*` / `LOG_COMPONENT_*` / `LOG_SUBSYSTEM_*`
|
||||
constants of the module you are editing; match the shape of the log sites
|
||||
already in that file rather than introducing a second style next to them.
|
||||
- Level policy: `error` for behavior/security-affecting failures, `warn` for
|
||||
degraded or fallback paths, `info` for low-frequency lifecycle, `debug` for
|
||||
targeted diagnostics, `trace` for hot paths. Per-object and per-request
|
||||
success paths are `trace`.
|
||||
- Never log secrets, tokens, credential payloads, or merged config dumps.
|
||||
- `scripts/check_logging_guardrails.sh` enforces a subset of this on the files
|
||||
it lists; passing it is a floor, not evidence the log matches the house style.
|
||||
|
||||
See `.agents/skills/rustfs-logging-governance/SKILL.md` for the full event
|
||||
model, level policy, and guardrail-update checklist.
|
||||
|
||||
## Tools
|
||||
|
||||
### xl.meta decode tool Quick Use
|
||||
|
||||
Reference in New Issue
Block a user