Clarify threading model for metrics

design.md

@@ -154,6 +154,26 @@ A high-performance, multi-stage, lock-free pipeline for inter-thread communicati
 - **Builder pattern** for constructing commit requests
 - **String views** pointing to arena-allocated memory to avoid unnecessary copying
 
+#### **Metrics System** (`src/metric.{hpp,cpp}`)
+
+**High-Performance Metrics Implementation:**
+- **Thread-local counters/histograms** with single writer for performance
+- **Global gauges** with lock-free atomic CAS operations for multi-writer scenarios
+- **SIMD-optimized histogram bucket updates** using AVX instructions for high throughput
+- **Arena allocator integration** for efficient memory management during rendering
+
+**Threading Model:**
+- **Counters**: Per-thread storage, single writer, atomic write in `Counter::inc()`, atomic read in render thread
+- **Histograms**: Per-thread storage, single writer, per-histogram mutex serializes all access (observe and render)
+- **Gauges**: Lock-free atomic operations using `std::bit_cast` for double precision
+- **Thread cleanup**: Automatic accumulation of thread-local state into global state on destruction
+
+**Prometheus Compatibility:**
+- **Standard metric types** with proper label handling and validation
+- **Bucket generation helpers** for linear/exponential histogram distributions
+- **Callback-based metrics** for dynamic values
+- **UTF-8 validation** using simdutf for label values
+
 #### **Configuration & Optimization**
 
 **Configuration System** (`src/config.{hpp,cpp}`):