angrydutchman.peedee.es
forked from
atscan.net/plcbundle-rs
High-performance implementation of plcbundle written in Rust
tree.fail
Update CLI command references from 'plcbundle-rs' to 'plcbundle' across documentation and codebase for consistency and clarity
1# Logging System
2
3The CLI uses a unified logging system based on the `log` crate + `env_logger`.
4
5## Usage
6
7### In Command Files
8
9```rust
10// Info messages (shown in normal mode)
11log::info!("Processing {} bundles", count);
12
13// Debug messages (shown only with -v/--verbose)
14log::debug!("📦 Index: v{} ({})", version, origin);
15
16// Warnings (shown in normal mode)
17log::warn!("Index is behind (has bundle {}, repo has {})", last, current);
18
19// Errors (always shown, even with --quiet)
20log::error!("DID index does not exist");
21```
22
23### Log Levels
24
25| Level | Flag | When Shown | Use For |
26|-------|------|------------|---------|
27| `ERROR` | Always | All modes | Critical errors |
28| `WARN` | `--quiet` excluded | Normal, Verbose | Warnings that need attention |
29| `INFO` | Default | Normal, Verbose | Standard progress/status messages |
30| `DEBUG` | `-v, --verbose` | Verbose only | Detailed diagnostics, timing info |
31| `TRACE` | Not used | - | Reserved for future use |
32
33### Command-Line Flags
34
35```bash
36# Normal mode (INFO level)
37plcbundle did resolve did:plc:...
38
39# Verbose mode (DEBUG level) - shows all timing and diagnostics
40plcbundle did resolve did:plc:... -v
41
42# Quiet mode (ERROR only) - only JSON output and critical errors
43plcbundle did resolve did:plc:... --quiet
44```
45
46## Output Guidelines
47
48### Use `log::info!()` for:
49- Operation start/completion messages
50- Progress summaries
51- Final statistics
52- User-facing status updates
53
54### Use `log::debug!()` for:
55- Detailed timing information
56- Internal state information
57- Diagnostic messages
58- Performance metrics
59
60### Use `log::error!()` for:
61- Operation failures
62- Missing prerequisites
63- Invalid input
64
65### Use `log::warn!()` for:
66- Non-critical issues
67- Deprecation notices
68- Performance warnings
69
70### Use `println!()` for:
71- Actual data output (JSON, formatted results)
72- Structured output that should ALWAYS appear
73
74### Use `eprint!()` / `eprintln!()` for:
75- Progress bars (dynamic updates like `\r`)
76- Live counters
77
78## Examples
79
80### Good ✅
81```rust
82// Verbose diagnostics
83log::debug!("Shard {:02x} loaded, size: {} bytes", shard_num, size);
84
85// Normal progress
86log::info!("Building DID index...");
87log::info!("✅ Complete in {:?}", elapsed);
88
89// Actual output
90println!("{}", json);
91```
92
93### Bad ❌
94```rust
95// Don't use eprintln! for static messages
96eprintln!("Processing bundles..."); // Use log::info! instead
97
98// Don't use println! for diagnostics
99println!("DEBUG: shard loaded"); // Use log::debug! instead
100
101// Don't use log::info! for JSON output
102log::info!("{}", json); // Use println! instead
103```
104
105## Environment Variable
106
107The logger respects `RUST_LOG` environment variable:
108
109```bash
110# Override log level
111RUST_LOG=trace plcbundle did resolve did:plc:...
112
113# Filter by module
114RUST_LOG=plcbundle::did_index=debug plcbundle did resolve did:plc:...
115```
116
117## Implementation
118
119The logger is initialized in `main()` based on CLI flags:
120
121```rust
122fn main() -> Result<()> {
123 let cli = Cli::parse();
124
125 // Initialize logger
126 commands::logger::init_logger(cli.verbose, cli.quiet);
127
128 // ... rest of main
129}
130```
131
132Logger configuration in `src/bin/commands/logger.rs`:
133- **Quiet mode**: Only ERROR level
134- **Normal mode**: INFO level and above
135- **Verbose mode**: DEBUG level and above
136
137Format:
138- DEBUG/ERROR: Include `[LEVEL]` prefix
139- INFO/WARN: Clean output without prefix
140