Struct Gauge 

pub struct Gauge { /* private fields */ }

A cache-padded atomic gauge for point-in-time measurements.

Gauges represent a current value that is periodically sampled and set, such as memory usage, queue depth, or progress percentage.

Why Only set() and get()?

This type intentionally omits add()/inc()/dec() methods. If you need to increment or decrement a value from multiple threads (e.g., tracking active connections), use Counter instead - it’s thread-sharded for contention-free concurrent increments.

Providing increment methods here would create a footgun: the API would look convenient for counting, but the single-atomic implementation would cause cache-line contention under concurrent writes. By limiting the API to set()/get(), we make the intended usage pattern clear: periodic point-in-time snapshots from a single writer.

Why Not Thread-Sharded?

Thread-sharding works for Counter because addition is commutative — you can sum the shards to get the total. This includes subtraction (adding negative values): the shard sums still produce the correct aggregate. set() is not commutative; there’s no meaningful way to aggregate “last value written” across shards.

The cache padding prevents false sharing if this gauge is stored adjacent to frequently-accessed data.

Implementations

impl Gauge

pub fn new() -> Self

Create a new gauge initialized to zero.

pub fn with_value(initial: i64) -> Self

Create a new gauge with an initial value.

pub fn set(&self, value: i64)

Set the gauge to a value.

pub fn get(&self) -> i64

Get the current value.

Trait Implementations

impl ClickHouseExport for Gauge

fn export_clickhouse( &self, batch: &mut ClickHouseMetricBatch, name: &str, description: &str, time_unix_nano: u64, )

impl Default for Gauge

fn default() -> Self

Returns the “default value” for a type.

impl DogStatsDExport for Gauge

fn export_dogstatsd( &self, output: &mut String, name: &str, tags: &[(&str, &str)], )

Export this metric to the output string in DogStatsD format.

impl OtlpExport for Gauge

fn export_otlp( &self, metrics: &mut Vec<Metric>, name: &str, description: &str, time_unix_nano: u64, )

impl PrometheusExport for Gauge

fn export_prometheus(&self, output: &mut String, name: &str, help: &str)

Export this metric to the output string.