metrics-lib 0.9.1

The fastest metrics library for Rust. Lock-free 0.6ns gauges, 18ns counters, timers, rate meters, async timing, adaptive sampling, and system health. Cross-platform with minimal dependencies.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# Performance and Architecture Review (v0.9.1)

This document summarizes the current performance profile and implementation status of `metrics-lib` as of `0.9.1`.

## Snapshot

- Focus: low-overhead, in-process metrics for hot paths
- Core strategy: lock-free atomics on hot-path metric updates
- Registry strategy: `RwLock<HashMap<...>>` per metric type for name lookup/creation
- Feature model: compile-time feature gates (`count`, `gauge`, `timer`, `meter`, `sample`, `async`, etc.)

## Verified Benchmark Reference

Latest local reference run (Windows x86_64, Rust stable):

```bash
cargo bench --bench metrics_bench --features meter
```

Criterion means:

- `counter/increment`: 1.48 ns/op
- `gauge/set`: 0.40 ns/op
- `timer/record`: 3.17 ns/op
- `global_metrics/mixed_operations`: 151.58 ns/op

Notes:

- These are environment-dependent microbenchmarks.
- Use CI benchmark history and repeated local runs for trend analysis.

## Current Strengths

### 1) Hot-path execution model

- Atomic operations in core metric types avoid mutex contention in update paths.
- Cache-line alignment (`#[repr(align(64))]`) reduces false sharing for heavily contended metrics.
- Fast-path methods stay minimal (`inc`, `set`, `record_ns`, `tick`).

### 2) Correctness hardening

- Counter checked methods (`try_*`) now use CAS loops to avoid TOCTOU races.
- Gauge math methods guard non-finite input/result paths.
- Unsafe blocks in async pin-projection paths have explicit `SAFETY` rationale.

### 3) Feature-gated binary shaping

- Metric types and APIs compile out when feature-disabled.
- Bench/example targets now declare required features for consistency.

### 4) Test and quality gates

- Formatting and strict lint (`clippy -D warnings`) are enforced.
- Coverage gate (`cargo-llvm-cov`, line threshold 85%) is passing.
- Ignored chaos/longevity suites execute under all-features when requested.

## Current Limits and Trade-offs

### 1) Registry is not lock-free

- Lookup/creation uses `RwLock<HashMap<...>>` by design.
- This is acceptable for read-heavy workloads but should not be described as lock-free.

### 2) Documentation test coverage model

- API markdown is now covered by executable smoke tests.
- Full prose examples are not all auto-executed as strict doctests.

### 3) Benchmark interpretation

- Single-machine numbers are useful for trend tracking, not universal claims.
- Cross-platform and cross-hardware comparisons require controlled environments.

## Practical Guidance

- Use default features for general-purpose services.
- Enable `meter` only where rate tracking is required.
- Prefer `try_*` APIs for untrusted or externally sourced values.
- Pre-register handles in startup paths to keep runtime lookups predictable.
- Run benchmark comparisons with the same feature set and Criterion settings.

## Recommended Validation Matrix

For release-quality confidence, run at minimum:

```bash
cargo fmt --all -- --check
cargo clippy --all-features --all-targets -- -D warnings
cargo test
cargo test --all-features
cargo test --all-features -- --ignored
cargo llvm-cov --summary-only --workspace --fail-under-lines 85 --ignore-filename-regex '^(dev/|docs/|benches/|examples/)'
cargo bench --bench metrics_bench --features meter
```

## Conclusion

`metrics-lib` `0.9.1` is in a strong production-ready state for the validated configurations: fast hot-path updates, explicit feature gating, and passing test/lint/coverage/benchmark checks. Remaining risk is mostly environmental variance (hardware/power policy/OS noise), not a known architectural blocker in the current codebase.