Update 0.7.1

Author: jamesgober

CHANGELOG.md

@@ -11,6 +11,22 @@
 ## [Unreleased]
 
 
+<br>
+
+## [0.7.1] - 2025-08-30
+### Added
+- Optional `trace` feature providing lightweight internal trace hooks for debugging overhead.
+  - Crate-private `trace::record_event()`; zero cost when feature is off.
+  - Wired into `Watch::record()` fast/slow paths behind `cfg(feature = "trace")`.
+
+### Fixed
+- Eliminated `dead_code` warnings for `HistBackend` by gating the module behind `collector + metrics` in `src/lib.rs`.
+- Removed an incorrect public `trace!` macro to avoid unresolved symbol/API surface growth.
+
+### Maintenance
+- Macro forward-compatibility: accepted optional trailing commas across timing/benchmark macros.
+
+
 <br>
 
 ## [0.7.0] - 2025-08-30
@@ -251,7 +267,8 @@ Initial pre-dev release for backup.
 
 
 
-[Unreleased]: https://github.com/jamesgober/rust-benchmark/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/jamesgober/rust-benchmark/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/jamesgober/rust-benchmark/compare/v0.7.0...v0.7.1
 [0.8.0]: https://github.com/jamesgober/rust-benchmark/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/jamesgober/rust-benchmark/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/jamesgober/rust-benchmark/compare/v0.5.8...v0.6.0

Cargo.lock

@@ -10,7 +10,7 @@
 #╚═══════════╩══════════════════════════════════╩════════════╝
 [package]
 name    = "benchmark"
-version = "0.7.0"
+version = "0.7.1"
 edition = "2021"
 
 # Minimum Supported Rust Version (MSRV)
@@ -62,6 +62,7 @@ default        = ["benchmark", "collector"]               # Turn-key dev: timing
 benchmark      = ["std"]                                   # Enable real timing
 collector      = ["std"]                                   # Collector + histogram
 metrics        = ["collector"]                             # Watch/Timer production metrics
+trace          = ["std"]                                   # Optional lightweight trace hooks (no-op when disabled)
 
 # Precision backends
 high-precision = ["collector"]                             # Swap to high-precision histogram backend

Cargo.toml

@@ -111,7 +111,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-benchmark = "0.7.0"
+benchmark = "0.7.1"
 ```
 
 <br>
@@ -123,7 +123,7 @@ benchmark = "0.7.0"
 [dependencies]
 
 # Enables Production & Development.
-benchmark = { version = "0.7.0", features = ["standard"] }
+benchmark = { version = "0.7.1", features = ["standard"] }
 ```
 
 <br>
@@ -134,7 +134,7 @@ Enable production observability using `Watch`/`Timer` or the `stopwatch!` macro.
 Cargo features:
 ```toml
 [dependencies]
-benchmark = { version = "0.7.0", features = ["std", "metrics"] }
+benchmark = { version = "0.7.1", features = ["std", "metrics"] }
 ```
 
 Record with `Timer` (auto-record on drop):
@@ -169,7 +169,7 @@ assert!(watch.snapshot()["render"].count >= 1);
 ```toml
 [dependencies]
 # Disable default features for true zero-overhead
-benchmark = { version = "0.7.0", default-features = false }
+benchmark = { version = "0.7.1", default-features = false }
 ```
 <br>
 
@@ -406,6 +406,23 @@ overhead::time_macro/time_macro_add
 
 <hr>
 
+<h2>MSRV &amp; SemVer Policy</h2>
+<ul>
+  <li><b>MSRV</b>: 1.70+ (as indicated by the badge). We bump MSRV only in <b>minor</b> releases and document it in the changelog.</li>
+  <li><b>SemVer</b>:
+    <ul>
+      <li>Patch (x.y.<b>z</b>): bug fixes, internal improvements, and documentation.</li>
+      <li>Minor (x.<b>y</b>.z): new features and non-breaking API additions.</li>
+      <li>Major (<b>x</b>.y.z): breaking changes only, announced in the changelog with migration notes.</li>
+    </ul>
+  </li>
+  <li><b>Feature flags</b>: additive and stable. Disabled paths remain zero-cost.</li>
+  <li><b>No unsafe</b> in hot paths; any future "unsafe" will be justified and tested.</li>
+  <li><b>Docs.rs</b>: examples note required feature flags to avoid confusion.</li>
+  </ul>
+
+<hr>
+
 <h2 align="center">
     DEVELOPMENT &amp; CONTRIBUTION
 </h2>

README.md

@@ -76,7 +76,7 @@
 Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
-benchmark = "0.7.0"
+benchmark = "0.7.1"
 ```
 
 <br>
@@ -97,7 +97,7 @@ Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
 # Disable default features for true zero-overhead
-benchmark = { version = "0.7.0", default-features = false }
+benchmark = { version = "0.7.1", default-features = false }
 ```
 
 <br>
@@ -134,6 +134,23 @@ Notes:
 
 <br>
 
+## Quickstart
+Minimal examples to get productive fast. See full examples below for more depth.
+
+```rust
+// Benchmarking (default features)
+let (out, d) = benchmark::time!({ 2 + 2 });
+assert_eq!(out, 4);
+assert!(d.as_nanos() >= 0);
+
+// Production metrics (features = ["metrics"]) 
+let w = benchmark::Watch::new();
+benchmark::stopwatch!(w, "op", { std::thread::sleep(std::time::Duration::from_millis(1)); });
+assert!(w.snapshot()["op"].count >= 1);
+```
+
+<br>
+
 ## Types
 
 ### Duration
@@ -421,7 +438,7 @@ Provides production-friendly timing and percentile statistics with negligible ov
 Installation with feature:
 ```toml
 [dependencies]
-benchmark = { version = "0.7.0", features = ["metrics"] }
+benchmark = { version = "0.7.1", features = ["metrics"] }
 ```
 
 ### Watch
@@ -694,11 +711,18 @@ When compiled with `default-features = false` or without `benchmark`:
 - `benchmark!` executes once and returns `(Some(result), Vec::new())`.
 - `Collector` and `Stats` are `collector`-gated; if `collector` is disabled they are not available.
 
+## Common Pitfalls
+- Ensure required features are enabled for copied snippets (`collector`, `metrics`).
+- Zero durations are valid; avoid rewriting them at collection time. Clamp only at presentation.
+- Tune histogram bounds near your SLOs for better percentile precision and lower memory.
+- Keep metric names low-cardinality and stable to reduce map contention.
+- Avoid holding your own locks across `await` inside timed regions.
+
 ### Best Practices: Handling 0ns in dashboards
-- Preserve fidelity in the data layer: zero durations are valid measurements for extremely fast operations.
-- Apply a visualization floor at presentation time only if necessary (e.g., show 1ns instead of 0ns) to avoid skewing aggregates.
-- Consider filtering 0ns when computing percentiles for SLO charts if they represent measurement granularity rather than business latency.
-- If you need to avoid zeros in histograms, clamp on export, not at collection: `max(value, 1)`. Keep raw storage exact for audits.
+- Preserve fidelity in the data layer: zero durations are valid measurements for extremely fast ops.
+- Apply a visualization floor only at presentation time if necessary.
+- Consider filtering 0ns when computing percentiles if they reflect timer granularity rather than business latency.
+- If you must avoid zeros in histograms, clamp on export (`max(value, 1)`), not at collection.
 
 <br>
 

docs/API.md

@@ -55,10 +55,10 @@ The <b>benchmark</b> feature provides a lightweight, statistically-sound toolkit
 [dependencies]
 
 # Benchmark is enabled by default.
-benchmark = "0.7.0"
+benchmark = "0.7.1"
 
 # or enable benchmark explicitly.
-benchmark = { version = "0.7.0", features = ["benchmark"]}
+benchmark = { version = "0.7.1", features = ["benchmark"]}
 ```
 > ⚙️ Add directly to your `Cargo.toml`.
 

docs/features/BENCHMARK.md

@@ -50,7 +50,7 @@ The <b>metrics</b> feature provides production-grade latency metrics with near-z
 ### Manual installation:
 ```toml
 [dependencies]
-benchmark = { version = "0.5.8", features = ["metrics"] }
+benchmark = { version = "0.7.1", features = ["metrics"] }
 ```
 > ⚙️ Add directly to your `Cargo.toml`.
 
@@ -87,6 +87,20 @@ fn main() {
 }
 ```
 
+<br>
+<hr>
+<br>
+
+## Accuracy and Performance Trade-offs
+
+- **Bounds selection**: Choose `lowest` and `highest` close to your SLOs. Tighter ranges improve percentile precision and reduce memory.
+- **Input clamping**: `Watch::record()` clamps to histogram bounds. Percentile queries clamp `q` to [0.0, 1.0]. This avoids panics and yields sane results for out-of-range inputs.
+- **Precision vs memory**: The built-in histogram is fixed-size and optimized for lock-free recording; memory usage grows with the configured range. Tune bounds rather than sampling frequency.
+- **Contention**: Recording is lock-free; map access for new metric names may take a write lock once. Keep metric names stable and low-cardinality. Consider sharding hot metrics and merging snapshots offline if necessary.
+- **Snapshots**: Percentiles are computed from cloned histograms outside locks to minimize contention. Snapshot costs scale with the number of metrics.
+- **Zero durations**: Some platforms can return 0ns for extremely fast ops; this is preserved. Clamp in presentation if needed, not at collection.
+- **Tracing hooks (optional)**: Enabling the `trace` feature adds lightweight, gated logging for hot-path events to aid debugging overhead; it is zero-cost when disabled.
+
 ### Ergonomic scoped timing with `stopwatch!`
 ```rust
 use benchmark::{stopwatch, Watch};

docs/features/METRICS.md

@@ -76,7 +76,7 @@ Notes:
 #### Manual installation:
 ```toml
 [dependencies]
-benchmark = "0.7.0" # default features enabled (benchmark + collector)
+benchmark = "0.7.1" # default features enabled (benchmark + collector)
 ```
 > ⚙️ Add directly to your `Cargo.toml`.
 
@@ -104,7 +104,7 @@ Enables the [**`benchmark`**](./BENCHMARK.md) feature.
 #### Manual installation:
 ```toml
 [dependencies]
-benchmark = { version = "0.7.0", features = ["metrics"]}
+benchmark = { version = "0.7.1", features = ["metrics"]}
 ```
 
 #### Terminal
@@ -128,7 +128,7 @@ cargo add benchmark -F metrics
 #### Manual installation:
 ```toml
 [dependencies]
-benchmark = { version = "0.7.0", default-features = false }
+benchmark = { version = "0.7.1", default-features = false }
 ```
 > ⚙️ Add directly to your `Cargo.toml`.