[AI generated] Implemented metric sampling

[DrDet]

Add Per-Metric Sampling to C++ Client

Adds sample_factor(n) method for configurable client-side sampling of high-volume metrics.

Usage

// Send ~1% of events with counters automatically multiplied by 100
statshouse.metric("hot_metric").sample_factor(100).write_count(1);

How It Works

• Events written with probability 1/sample_factor
• Counter multiplied by factor to preserve expected values
• Zero overhead when sample_factor=1 (default)
• Thread-local wyhash PRNG - no locks

API

MetricBuilder& sample_factor(uint32_t factor);  // factor >= 1

Works with all write methods:

• write_count()
• write_value() / write_values()
• write_unique()

Example

statshouse::TransportUDP statshouse;

// Normal metric
statshouse.metric("requests").write_count(1);

// Hot metric - 100x less overhead
statshouse.metric("api_calls")
    .tag("endpoint", "/v1/users")
    .sample_factor(100)
    .write_count(1);

Performance

Case	Overhead
No sampling (factor=1)	Zero - single LIKELY branch
With sampling	One wyhash call + modulo

Uses thread-local wyhash PRNG (same as the library's hashing) - no locks, no allocations, no syscalls.

// Hot path: single branch, no function calls
if (STATSHOUSE_LIKELY(sample_factor_ <= 1)) { return true; }

// Sampling: fast wyhash
auto r = wyhash::wyrand(&seed);
return wyhash::wy2u0k(r, sample_factor_) == 0;

Implementation Notes

• TransportUDP: Sampling at write time
• Registry: Sampling during aggregation, unsampled flush
• Fully backward compatible (default factor=1)