mirror of
https://github.com/rustfs/rustfs.git
synced 2026-10-13 16:11:56 +00:00
Chris
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# Logging Audit and Migration Reference
|
|
|
|
Use the [root logging rules](../../AGENTS.md#logging) for individual events.
|
|
Read this reference only for a broad logging audit, an event-model migration,
|
|
or a change to `scripts/check_logging_guardrails.sh`. Use `Cargo.toml` for the
|
|
current workspace/crate list instead of maintaining one here.
|
|
|
|
## Audit by Operational Role
|
|
|
|
- Server/protocol/admin: lifecycle, authorization failures, request boundaries,
|
|
and degraded subsystems; avoid normal request success at `info`.
|
|
- Storage/heal/scanner/capacity: integrity failures and aggregate lifecycle;
|
|
avoid per-object, per-shard, and folder iteration noise.
|
|
- IAM/policy/credentials/KMS/crypto: safe identifiers and enforcement results;
|
|
never emit secrets, claims, payloads, or expected authenticators.
|
|
- Notify/audit/targets: target lifecycle and batch/backpressure summaries; avoid
|
|
per-event success logs.
|
|
- Locking/concurrency/I/O foundations: contention anomalies and state changes;
|
|
prefer metrics for high-frequency worker/permit signals.
|
|
- Shared type/schema crates: log at the operational caller boundary unless the
|
|
crate itself owns the failure context.
|
|
|
|
## Event Shape
|
|
|
|
Prefer stable fields in this order when available:
|
|
|
|
1. `event`
|
|
2. `component`
|
|
3. `subsystem`
|
|
4. `state` or `result`
|
|
5. stable context such as mode, duration, reason, counts, safe identifiers, or
|
|
capacity/permit values
|
|
6. short message label
|
|
|
|
Reuse the module's constants and neighboring field names. Do not create aliases
|
|
for the same concept.
|
|
|
|
## Patterns to Retire
|
|
|
|
- sentence-style lifecycle announcements;
|
|
- startup banners and checklist lines;
|
|
- repetitive success logs at `info`/`debug`;
|
|
- raw inventories when an aggregate count is sufficient;
|
|
- fallback prose with values embedded in the message;
|
|
- `?value`/`Debug` output for credential-bearing or attacker-controlled data;
|
|
- logging a parse input when the malformed input may itself be a secret.
|
|
|
|
## Guardrail Changes
|
|
|
|
When expanding `scripts/check_logging_guardrails.sh`:
|
|
|
|
1. Add only files/patterns intentionally migrated in the same change.
|
|
2. Keep patterns concrete and grep-friendly.
|
|
3. Do not encode a style that remains valid elsewhere as a global ban.
|
|
4. Run the guardrail script and the root validation tier.
|
|
5. Treat the script as a floor; manually verify level, field shape, and privacy.
|
|
|
|
Useful search seeds for the changed surface:
|
|
|
|
```bash
|
|
rg -n 'error!|warn!|info!|debug!|trace!|#\[instrument' <changed-paths>
|
|
rg -n '\?[^,)]|secret|token|credential|authorization|merged_config' <changed-paths>
|
|
```
|