Document UUIDv7 statistics

Refs #70.

Author: dexcompiler

CHANGELOG.md

@@ -7,10 +7,14 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+### Added
+- Add opt-in `UuidV7FactoryStatistics` counters for generated UUIDs, clock rollback, counter overflow, spin-wait, logical drift, CAS retries, and random-buffer refills.
+
 ### Changed
 - `HlcGuidFactory` constructor now enforces a 14-bit node ID constraint and throws `ArgumentOutOfRangeException` for values above `HlcGuidFactory.MaxNodeId` (16383). Previously, higher values were silently truncated in generated UUIDv7 values.
 
 ### Documentation
+- Document UUIDv7 factory statistics and counter semantics.
 - Clarify `UuidV7Factory` collision and clock-skew guarantees, including the distinction between per-instance deterministic monotonicity and probabilistic cross-factory uniqueness.
 - Document the custom RNG contract for `UuidV7Factory`, including deterministic replay behavior and production CSPRNG guidance.
 

README.md

@@ -21,6 +21,7 @@ It is built around `TimeProvider` so that *time becomes an injectable dependency
   - `UuidV7Factory` produces RFC 9562 UUIDv7 values as `Guid`
   - Works with real or simulated time
   - Configurable counter overflow behavior
+  - Optional statistics for rollback, overflow, spin-wait, contention, and random-buffer refill diagnostics
   - Per-instance monotonicity under clock rollback; cross-factory uniqueness remains probabilistic unless coordinated externally
 
 - **Hybrid Logical Clock (HLC)**
@@ -35,7 +36,7 @@ It is built around `TimeProvider` so that *time becomes an injectable dependency
   - Canonical binary wire format (`VectorClock.WriteTo`/`ReadFrom`) and string form for HTTP/gRPC headers
 
 - **Lightweight instrumentation**
-  - Counters for timers, advances, and timeouts useful in simulation/test assertions
+  - Counters for timers, advances, timeouts, and UUIDv7 factory behavior useful in simulation/test assertions
 
 ## Installation
 

docs/changelog.md

@@ -10,10 +10,14 @@ This page mirrors the repository root `CHANGELOG.md`.
 
 ## [Unreleased]
 
+### Added
+- Add opt-in `UuidV7FactoryStatistics` counters for generated UUIDs, clock rollback, counter overflow, spin-wait, logical drift, CAS retries, and random-buffer refills.
+
 ### Changed
 - `HlcGuidFactory` constructor now enforces a 14-bit node ID constraint and throws `ArgumentOutOfRangeException` for values above `HlcGuidFactory.MaxNodeId` (16383). Previously, higher values were silently truncated in generated UUIDv7 values.
 
 ### Documentation
+- Document UUIDv7 factory statistics and counter semantics.
 - Clarify `UuidV7Factory` collision and clock-skew guarantees, including the distinction between per-instance deterministic monotonicity and probabilistic cross-factory uniqueness.
 - Document the custom RNG contract for `UuidV7Factory`, including deterministic replay behavior and production CSPRNG guidance.
 

docs/guide/instrumentation.md

@@ -33,6 +33,45 @@ You can reset counters between test phases:
 tp.Statistics.Reset();
 ```
 
+## UUIDv7 factory statistics
+
+`UuidV7Factory` can update opt-in `UuidV7FactoryStatistics` counters:
+
+```csharp
+var stats = new UuidV7FactoryStatistics();
+using var factory = new UuidV7Factory(
+    TimeProvider.System,
+    rng: null,
+    overflowBehavior: CounterOverflowBehavior.SpinWait,
+    statistics: stats);
+
+factory.NewGuid();
+
+var snapshot = stats.Snapshot();
+Console.WriteLine(snapshot.GeneratedCount);
+Console.WriteLine(snapshot.ClockRollbackCount);
+Console.WriteLine(snapshot.CasRetryCount);
+```
+
+Statistics are disabled unless you pass an instance to the factory. When enabled, counters use atomic operations so they can be read safely while UUIDs are being generated concurrently.
+
+Useful counters include:
+
+- `GeneratedCount`
+- `ClockRollbackCount`
+- `CounterOverflowCount`
+- `SpinWaitCount`
+- `LogicalTimestampAdvanceCount`
+- `MaxLogicalDriftMs`
+- `CasRetryCount`
+- `RandomBufferRefillCount`
+
+Use `Snapshot()` when you need a point-in-time value object, and `Reset()` to isolate test phases:
+
+```csharp
+stats.Reset();
+```
+
 ## Timeout statistics
 
 Timeout factory helpers (`Timeouts`) can record aggregate timeout activity via `TimeoutStatistics`.
@@ -58,4 +97,3 @@ If you prefer isolation per test (or per component), pass your own `TimeoutStati
 var stats = new TimeoutStatistics();
 using var handle = Timeouts.CreateTimeoutHandle(tp, TimeSpan.FromSeconds(1), stats);
 ```
-

docs/guide/uuidv7.md

@@ -68,6 +68,46 @@ For production services, prefer a single `UuidV7Factory` singleton per process o
 
 For high-assurance shared namespaces, use a storage uniqueness constraint as the final guardrail and retry on conflict. If you need node-aware ordering semantics, consider `HlcGuidFactory`; it embeds a node ID and HLC timestamp, but it should be chosen for causal/node-aware ordering rather than treated as a blanket substitute for storage-level uniqueness.
 
+## Statistics
+
+`UuidV7Factory` statistics are opt-in. Leave them disabled for the lowest-overhead path, or pass a `UuidV7FactoryStatistics` instance when you want to observe clock rollback, counter overflow, spin-wait pressure, and lock-free contention:
+
+```csharp
+var stats = new UuidV7FactoryStatistics();
+using var factory = new UuidV7Factory(
+    TimeProvider.System,
+    rng: null,
+    overflowBehavior: CounterOverflowBehavior.SpinWait,
+    statistics: stats);
+
+var id = factory.NewGuid();
+var snapshot = stats.Snapshot();
+
+Console.WriteLine(snapshot.GeneratedCount);
+Console.WriteLine(snapshot.CounterOverflowCount);
+```
+
+The built-in DI helpers can register the same shared statistics object as the singleton factory:
+
+```csharp
+services.AddLockFreeGuidFactory(new UuidV7FactoryStatistics());
+```
+
+Key counters:
+
+| Counter | Meaning |
+|---|---|
+| `GeneratedCount` | Number of UUIDs successfully generated. Batch generation increments by the span length. |
+| `ClockRollbackCount` | Successful allocation decisions made while physical time was behind the factory's logical frontier. |
+| `CounterOverflowCount` | Times the 12-bit per-millisecond counter overflow path was reached. |
+| `SpinWaitCount` | Times overflow handling had to wait for physical time to advance. |
+| `LogicalTimestampAdvanceCount` | Successful allocation decisions that emitted logical time ahead of physical time. |
+| `MaxLogicalDriftMs` | Maximum observed distance between emitted logical time and physical time. |
+| `CasRetryCount` | Failed compare-exchange attempts in the lock-free allocation loop. |
+| `RandomBufferRefillCount` | Thread-local random buffer refills. |
+
+Most counters are diagnostic event counts, not rates. For example, a single `NewGuids(span)` call may reserve many UUIDs with one successful allocation decision, so `GeneratedCount` increases by `span.Length` while rollback or drift counters increase once for that reservation.
+
 ## Custom RNGs and Deterministic Tests
 
 Custom RNG injection exists so tests and simulations can replay exact UUID sequences. Clockworks does not ship a deterministic RNG implementation; provide your own test-only `RandomNumberGenerator` when you need replay.
@@ -162,3 +202,5 @@ dotnet run --project demo/Clockworks.Demo -- uuidv7-sortability
 # Benchmark mode
 dotnet run --project demo/Clockworks.Demo -- uuidv7 --bench
 ```
+
+Benchmark mode includes a side-by-side single-threaded comparison of the default hot path and statistics-enabled hot path.