Fastmetrics

https://docs.rs/fastmetrics
Admin
Fastmetrics is a Rust library designed for efficient collection, management, and exposure of various...
Tokens:174,114
Snippets:1,518
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Usage

Source: https://docs.rs/fastmetrics/latest/fastmetrics/encoder/trait.EncodeLabelName.html

Demonstrates how to use types that implement EncodeLabelName.

```APIDOC
## Example

```rust
let name: &str = "name";                   // str implements `EncodeLabelName`
let name: String = String::from("name");   // String implement `EncodeLabelName`
```
```

--------------------------------

### StateSet Example with JobState Enum

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/state_set/struct.StateSet.html

Demonstrates creating, setting, and retrieving states using `StateSet` with a custom enum `JobState`. Shows how to get all states and their boolean status. Requires `StateSetValue` trait implementation for the enum.

```rust
#[derive(Copy, Clone, Debug, PartialEq, Default)]
enum JobState {
    #[default]
    Pending,
    Running,
    Completed,
    Failed,
}

// Can use `#[derive(StateSetValue)]` to simplify the code, but need to enable `derive` feature
impl StateSetValue for JobState {
    fn variants() -> &'static [Self] {
        &[Self::Pending, Self::Running, Self::Completed, Self::Failed]
    }

    fn as_str(&self) -> &str {
        match self {
            Self::Pending => "Pending",
            Self::Running => "Running",
            Self::Completed => "Completed",
            Self::Failed => "Failed",
        }
    }
}

// Create a default stateset (Pending)
let state = StateSet::<JobState>::default();
assert_eq!(state.get(), &JobState::Pending);

// Create a stateset with initial state
let state = StateSet::new(JobState::Running);
assert_eq!(state.get(), &JobState::Running);

// Change state
state.set(JobState::Completed);
assert_eq!(state.get(), &JobState::Completed);

// Get all states with their status
let states = state.states();
assert_eq!(states, vec![
    ("Pending", false),
    ("Running", false),
    ("Completed", true),
    ("Failed", false),
]);
```

--------------------------------

### FastMetrics Example: Registering and Exporting Metrics

Source: https://docs.rs/fastmetrics

Demonstrates how to use the FastMetrics crate to create a registry, register different types of metrics (simple counter and a labeled counter family), update their values, and export them in Prometheus text format. This example requires enabling the 'derive' feature for simplified label handling.

```rust
use fastmetrics::{
    encoder::{EncodeLabel, EncodeLabelSet, EncodeLabelValue, LabelSetEncoder, LabelEncoder},
    error::Result,
    format::text::{self, TextProfile},
    metrics::{counter::Counter, family::Family},
    raw::LabelSetSchema,
    registry::Registry,
};

#[derive(Clone, Eq, PartialEq, Hash)]
struct Labels {
    method: Method,
    status: u16,
}

// Can use `#[derive(LabelSet)]` or `#[derive(EncodeLabelSet, LabelSetSchema)]`
// to simplify the code, but need to enable `derive` feature

impl LabelSetSchema for Labels {
    fn names() -> Option<&'static [&'static str]> {
        Some(&["method", "status"])
    }
}

impl EncodeLabelSet for Labels {
    fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
        encoder.encode(&("method", &self.method))?;
        encoder.encode(&("status", &self.status))?;
        Ok(())
    }
}

#[derive(Clone, Eq, PartialEq, Hash)]
enum Method {
    Get,
    Put,
}

// Can use `#[derive(EncodeLabelValue)]` to simplify the code, but need to enable `derive` feature
impl EncodeLabelValue for Method {
    fn encode(&self, encoder: &mut dyn LabelEncoder) -> Result<()> {
        match self {
            Self::Get => encoder.encode_str_value("Get"),
            Self::Put => encoder.encode_str_value("Put"),
        }
    }
}

// Create a registry with a namespace and some constant labels
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;

// Register a simple counter
let requests = <Counter>::default();
registry.register("requests", "Total requests processed", requests.clone())?;

// Register a counter metric family for tracking requests with labels
let http_requests = Family::<Labels, Counter>::default();
registry.register(
    "http_requests",
    "Total HTTP requests",
    http_requests.clone()
)?;

// Update the simple counter
requests.inc();
assert_eq!(requests.total(), 1);

// Update the counter family
let labels = Labels { method: Method::Get, status: 200 };
http_requests.with_or_new(&labels, |req| req.inc());
assert_eq!(http_requests.with(&labels, |req| req.total()), Some(1));

// Export metrics in text format
let mut output = String::new();
text::encode(&mut output, &registry, TextProfile::default())?;
// println!("{}", output);
assert!(output.contains(r#"myapp_http_requests_total{env=\"prod\",method=\"Get\",status=\"200\"} 1"#));

```

--------------------------------

### Registry Usage Example

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Demonstrates how to create a Registry, configure its namespace and constant labels, register metrics, and create nested subsystems.

```APIDOC
## Registry Usage Example

### Description
This example shows how to initialize a `Registry` with a specific namespace and constant labels, then register metrics directly and within nested subsystems.

### Method
```rust
Registry::builder()
```

### Endpoint
N/A (Rust API)

### Parameters
#### Builder Configuration
- `with_namespace(namespace: impl Into<Cow<'static, str>>)`: Sets a namespace prefix for all metrics.
- `with_const_labels(labels: [(impl Into<Cow<'static, str>>, impl Into<Cow<'static, str>>)])`: Attaches constant labels to the registry.
- `with_name_rule(rule: NameRule)`: Sets the metric/label name rule for registration.

#### Registry Methods
- `register(name: &str, description: &str, metric: impl Metric)`: Registers a metric with a name and description.
- `subsystem(name: &str)`: Creates a new subsystem with the given name.
- `subsystem_builder(name: &str)`: Creates a builder for a subsystem with the given name.

### Request Example
```rust
# use fastmetrics::registry::Registry;
# use fastmetrics::metrics::{counter::Counter, gauge::Gauge};
# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a registry with a `myapp` namespace and `env=prod` label
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;

// Register a metric
let uptime_seconds = Gauge::default();
registry.register("uptime_seconds", "Application uptime", uptime_seconds)?;

// Create a subsystem for database metrics
let db = registry.subsystem("database")?;

// Register a metric in the subsystem
let db_connections = Gauge::default();
db.register("connections", "Active database connections", db_connections)?;

// Create a nested subsystem with additional labels
let mysql = db.subsystem_builder("mysql")
    .with_const_labels([("engine", "innodb")])
    .build()?;

// Register a metric in the nested subsystem
let mysql_queries = Counter::default();
mysql.register("queries", "Total MySQL queries", mysql_queries)?;
# Ok(())
# }
```

### Response
#### Success Response
- `Ok(())`: Indicates successful registration or subsystem creation.

#### Response Example
N/A (Rust API, success is indicated by the absence of an error).
```

--------------------------------

### Example: Create and Fetch LazyGauge

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/gauge.rs.html

Shows how to create a `LazyGauge` using a closure that fetches a value, and then retrieves that value.

```rust
# use std::sync::atomic::{AtomicI64, Ordering};
# 
# use fastmetrics::metrics::gauge::LazyGauge;
# 
let lazy = LazyGauge::new({
    let value = AtomicI64::new(42);
    move || value.load(Ordering::Relaxed)
});
assert_eq!(lazy.fetch(), 42);
```

--------------------------------

### Counter Usage Example

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/counter.rs.html

Demonstrates how to create, increment, and retrieve the value of a Counter metric.

```APIDOC
## Counter

### Description

Represents a monotonically increasing value, typically used for counting discrete events. The counter's value can only increase or be reset to zero. It supports standard increment operations and provides options for wrapping or saturating arithmetic on overflow.

### Method

N/A (Struct with methods)

### Endpoint

N/A (Rust struct)

### Parameters

N/A

### Request Example

```rust
# use std::time::SystemTime;
# use fastmetrics::metrics::counter::Counter;

// Create a default counter
let counter = <Counter>::default();
assert_eq!(counter.total(), 0);
assert!(counter.created().is_none());

// Increment by 1
counter.inc();
assert_eq!(counter.total(), 1);

// Increment by custom value
counter.inc_by(5);
assert_eq!(counter.total(), 6);

// Create a counter with created timestamp
let created = SystemTime::UNIX_EPOCH
    .elapsed()
    .expect("UNIX timestamp when the counter was created");
let counter = <Counter>::with_created(created);
assert!(counter.created().is_some());
```

### Response

N/A (Rust struct methods)

### Methods

- **`default()`**: Creates a new `Counter` with a total value of 0 and no creation timestamp.
- **`with_created(created: Duration)`**: Creates a new `Counter` with a specified creation timestamp.
- **`inc()`**: Increases the counter's value by 1. Uses wrapping arithmetic on overflow for integer types.
- **`inc_by(v: N)`**: Increases the counter's value by `v`. Uses wrapping arithmetic on overflow for integer types. Panics if `v` is negative.
- **`saturating_inc()`**: Increases the counter's value by 1, clamping at the maximum value instead of wrapping on overflow. Only available for integer types.
- **`saturating_inc_by(v: N)`**: Increases the counter's value by `v`, clamping at the maximum value instead of wrapping on overflow. Only available for integer types. Panics if `v` is negative.
- **`total()`**: Returns the current total value of the counter.
- **`created()`**: Returns the creation timestamp of the counter, if set.
```

--------------------------------

### ConstCounter Example Usage

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/counter.rs.html

Illustrates how to instantiate and use ConstCounter, verifying its total value and creation timestamp.

```rust
/// # Example
///
/// ```rust
/// # use std::time::SystemTime;
/// # 
/// # use fastmetrics::metrics::counter::ConstCounter;
/// # 
/// // Create a constant counter with initial value
/// let counter = ConstCounter::new(42_u64);
/// assert_eq!(counter.total(), 42);
/// assert!(counter.created().is_none());
///
/// // Create a constant counter with created timestamp
/// let created = SystemTime::UNIX_EPOCH
///     .elapsed()
///     .expect("UNIX timestamp when the counter was created");
/// let counter = ConstCounter::with_created(42_u64, created);
/// assert_eq!(counter.total(), 42);
/// assert!(counter.created().is_some());
/// ```
```

--------------------------------

### Examples of EncodeLabelName Implementations

Source: https://docs.rs/fastmetrics/latest/fastmetrics/encoder/trait.EncodeLabelName.html

Demonstrates how `str` and `String` types, which implement `EncodeLabelName`, can be used.

```rust
let name: &str = "name";                   // str implements `EncodeLabelName`
let name: String = String::from("name");   // String implement `EncodeLabelName`
```

--------------------------------

### ConstStateSet Example

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/state_set/struct.ConstStateSet.html

Demonstrates how to create and use a ConstStateSet with a custom enum for job states. Shows how to initialize the set and retrieve the current state and all possible states with their status.

```rust
#[derive(Copy, Clone, Debug, PartialEq)]
enum JobState {
    Pending,
    Running,
    Completed,
    Failed,
}

// Can use `#[derive(StateSetValue)]` to simplify the code, but need to enable `derive` feature
impl StateSetValue for JobState {
    fn variants() -> &'static [Self] {
        &[Self::Pending, Self::Running, Self::Completed, Self::Failed]
    }

    fn as_str(&self) -> &str {
        match self {
            Self::Pending => "Pending",
            Self::Running => "Running",
            Self::Completed => "Completed",
            Self::Failed => "Failed",
        }
    }
}

// Create a constant stateset with initial state
let state = ConstStateSet::new(JobState::Completed);
assert_eq!(state.get(), &JobState::Completed);

// Get all states with their status
let states = state.states();
assert_eq!(states, vec![
    ("Pending", false),
    ("Running", false),
    ("Completed", true),
    ("Failed", false),
]);
```

--------------------------------

### Counter Usage Example

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/counter/struct.Counter.html

Demonstrates creating a default counter, checking its initial state, incrementing it by 1 and a custom value, and verifying the total. Also shows how to create a counter with a specific creation timestamp.

```rust
use std::time::{Duration, SystemTime};
use fastmetrics::metrics::counter::Counter;

// Create a default counter
let counter = <Counter>::default();
assert_eq!(counter.total(), 0);
assert!(counter.created().is_none());

// Increment by 1
counter.inc();
assert_eq!(counter.total(), 1);

// Increment by custom value
counter.inc_by(5);
assert_eq!(counter.total(), 6);

// Create a counter with created timestamp
let created = SystemTime::UNIX_EPOCH
    .elapsed()
    .expect("UNIX timestamp when the counter was created");
let counter = <Counter>::with_created(created);
assert!(counter.created().is_some());
```

--------------------------------

### LazyCounter Example

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/counter/struct.LazyCounter.html

Demonstrates creating and using a LazyCounter with a closure that reads an AtomicU64. The value is fetched lazily.

```rust
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;

let lazy = LazyCounter::new({
    let total = AtomicU64::new(42);
    move || total.load(Ordering::Relaxed)
});
assert_eq!(lazy.fetch(), 42);
```

--------------------------------

### Recommended `expect` Message Style for Environment Variables

Source: https://docs.rs/fastmetrics/latest/fastmetrics/error/type.Result.html

Provides an example of a recommended `expect` message style, focusing on describing why the `Ok` value is expected, particularly for environment variable retrieval.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Basic Metric Registration and Usage

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/lib.rs.html

Demonstrates how to create a registry, register different types of metrics (Counter, Family), update them, and export them in text format. This example shows the fundamental workflow for using FastMetrics.

```rust
use fastmetrics::{
    encoder::{EncodeLabel, EncodeLabelSet, EncodeLabelValue, LabelSetEncoder, LabelEncoder},
    error::Result,
    format::text::{self, TextProfile},
    metrics::{counter::Counter, family::Family},
    raw::LabelSetSchema,
    registry::Registry,
};

#[derive(Clone, Eq, PartialEq, Hash)]
struct Labels {
    method: Method,
    status: u16,
}

// Can use `#[derive(LabelSet)]` or `#[derive(EncodeLabelSet, LabelSetSchema)]`
// to simplify the code, but need to enable `derive` feature

impl LabelSetSchema for Labels {
    fn names() -> Option<&'static [&'static str]> {
        Some(&["method", "status"])
    }
}

impl EncodeLabelSet for Labels {
    fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
        encoder.encode(&("method", &self.method))?;
        encoder.encode(&("status", &self.status))?;
        Ok(())
    }
}

#[derive(Clone, Eq, PartialEq, Hash)]
enum Method {
    Get,
    Put,
}

// Can use `#[derive(EncodeLabelValue)]` to simplify the code, but need to enable `derive` feature
impl EncodeLabelValue for Method {
    fn encode(&self, encoder: &mut dyn LabelEncoder) -> Result<()> {
        match self {
            Self::Get => encoder.encode_str_value("Get"),
            Self::Put => encoder.encode_str_value("Put"),
        }
    }
}

# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a registry with a namespace and some constant labels
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;

// Register a simple counter
let requests = <Counter>::default();
registry.register("requests", "Total requests processed", requests.clone())?;

// Register a counter metric family for tracking requests with labels
let http_requests = Family::<Labels, Counter>::default();
registry.register(
    "http_requests",
    "Total HTTP requests",
    http_requests.clone()
)?;

// Update the simple counter
requests.inc();
assert_eq!(requests.total(), 1);

// Update the counter family
let labels = Labels { method: Method::Get, status: 200 };
http_requests.with_or_new(&labels, |req| req.inc());
assert_eq!(http_requests.with(&labels, |req| req.total()), Some(1));

// Export metrics in text format

```

--------------------------------

### Example Usage of EncodeLabelSet

Source: https://docs.rs/fastmetrics/latest/fastmetrics/encoder/trait.EncodeLabelSet.html

Demonstrates how a vector of label pairs can implement and be used with the EncodeLabelSet trait.

```rust
// labels implements `EncodeLabelSet` and can be encoded as a label set
let labels = vec![("method", "GET"), ("status", "200")];
```

--------------------------------

### Create and Use Histogram

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/histogram/struct.Histogram.html

Demonstrates creating a histogram with custom linear buckets, observing values, and checking the resulting snapshot counts and sums. Includes an example of creating a histogram with a creation timestamp.

```rust
use std::time::{Duration, SystemTime};
use fastmetrics::metrics::histogram::{Histogram, linear_buckets};

// Create a histogram with custom bucket boundaries
let hist = Histogram::new(linear_buckets(1.0, 1.0, 10));

// Observe some values
hist.observe(0.5);  // Falls into ≤1.0 bucket
hist.observe(1.5);  // Falls into ≤2.0 bucket
hist.observe(3.0);  // Falls into ≤3.0 bucket
hist.observe(20.0); // Falls into +Inf bucket

// Check snapshot
hist.with_snapshot(|s| {
    // Get bucket counts
    let buckets = s.buckets();
    assert_eq!(buckets[0].upper_bound(), 1.0);
    assert_eq!(buckets[0].count(), 1);  // One value ≤1.0
    assert_eq!(buckets[1].upper_bound(), 2.0);
    assert_eq!(buckets[1].count(), 1);  // One value ≤2.0
    assert_eq!(buckets[2].upper_bound(), 3.0);
    assert_eq!(buckets[2].count(), 1);  // One value ≤5.0
    assert_eq!(buckets[10].upper_bound(), f64::INFINITY);
    assert_eq!(buckets[10].count(), 1);  // One value in +Inf bucket
    // Get count and sum statistics
    assert_eq!(s.count(), 4);      // Total number of observations
    assert_eq!(s.sum(), 25.0);     // Sum of all observed values
});

// Create a histogram with created timestamp
let created = SystemTime::UNIX_EPOCH
    .elapsed()
    .expect("UNIX timestamp when the histogram was created");
let hist = Histogram::with_created(linear_buckets(1.0, 1.0, 10), created);
assert!(hist.created().is_some());
```

--------------------------------

### Example of using Family with Counter

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/family/struct.Family.html

Demonstrates creating a `Family` of `Counter` metrics and registering it with a `Registry`. It shows how to define custom labels, implement `LabelSetSchema` and `EncodeLabelSet`, and then use `with_or_new` to increment a specific counter.

```rust
let mut registry = Registry::default();

#[derive(Clone, Eq, PartialEq, Hash)]
struct HttpLabels {
    method: &'static str,
    status: &'static str,
}

impl LabelSetSchema for HttpLabels {
    fn names() -> Option<&'static [&'static str]> {
        Some(&["method", "status"])
    }
}

impl EncodeLabelSet for HttpLabels {
    fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
        encoder.encode(&("method", self.method))?;
        encoder.encode(&("status", self.status))?;
        Ok(())
    }
}

let http_requests = Family::<HttpLabels, Counter>::default();

registry.register("http_requests", "Total HTTP requests", http_requests.clone())?;

// Create metrics with different labels
let labels = HttpLabels { method: "GET", status: "200" };
http_requests.with_or_new(&labels, |metric| metric.inc());
```

--------------------------------

### Example Usage of Text Encoding

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/lib.rs.html

Demonstrates how to encode metrics into a string format using the text encoder. This snippet shows the typical workflow of creating a registry, encoding metrics, and asserting the output content.

```rust
//! let mut output = String::new();
//! text::encode(&mut output, &registry, TextProfile::default())?;
//! // println!("{}", output);
//! assert!(output.contains(r#"myapp_http_requests_total{env=\"prod\",method=\"Get\",status=\"200\"} 1"#));
//! # Ok(())
//! # }
```

--------------------------------

### StateSet Methods

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/state_set/struct.StateSet.html

Provides methods for creating, setting, getting, and listing states within a StateSet.

```APIDOC
## StateSet<T>

Represents a series of related boolean values, also called a bitset.

### Methods

#### `new(initial_state: T) -> Self`

Creates a `StateSet` with the given initial state.

#### `set(&self, state: T)`

Sets the current state.

#### `get(&self) -> &T`

Gets the current state.

#### `states(&self) -> Vec<(&str, bool)>`

Returns all states with exactly one Boolean value being true.
```

--------------------------------

### Example Implementation of TypedMetric

Source: https://docs.rs/fastmetrics/latest/fastmetrics/raw/trait.TypedMetric.html

Demonstrates how to implement the TypedMetric trait for a custom struct, associating it with the Gauge metric type.

```rust
struct MyGauge;

impl TypedMetric for MyGauge {
    const TYPE: MetricType = MetricType::Gauge;
}
```

--------------------------------

### Example of using a Metric Family for HTTP Requests

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/family.rs.html

Demonstrates how to create and use a `Family` of `Counter` metrics to track HTTP requests, distinguishing them by method and status code. It shows registration with a `Registry` and incrementing specific metrics based on their labels.

```rust
use fastmetrics::{
    encoder::{EncodeLabelSet, LabelSetEncoder},
    error::Result,
    metrics::{counter::Counter, family::Family},
    raw::LabelSetSchema,
    registry::Registry,
};

fn main() -> Result<()> {
let mut registry = Registry::default();

#[derive(Clone, Eq, PartialEq, Hash)]
struct HttpLabels {
    method: &'static str,
    status: &'static str,
}

impl LabelSetSchema for HttpLabels {
    fn names() -> Option<&'static [&'static str]> {
        Some(&["method", "status"])
    }
}

impl EncodeLabelSet for HttpLabels {
    fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
        encoder.encode(&("method", self.method))?;
        encoder.encode(&("status", self.status))?;
        Ok(())
    }
}

let http_requests = Family::<HttpLabels, Counter>::default();

registry.register("http_requests", "Total HTTP requests", http_requests.clone())?;

// Create metrics with different labels
let labels = HttpLabels { method: "GET", status: "200" };
http_requests.with_or_new(&labels, |metric| metric.inc());

Ok(())
}

```

--------------------------------

### Gauge Metric Usage Example

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/gauge/struct.Gauge.html

Demonstrates creating a Gauge with default and initial values, and performing increment, decrement, and set operations. Use this for tracking current measurements like memory usage or queue size.

```rust
use fastmetrics::metrics::gauge::Gauge;

// Create a default gauge
let gauge = <Gauge>::default();
assert_eq!(gauge.get(), 0);

// Create a gauge with initial value
let gauge = <Gauge>::new(42);
assert_eq!(gauge.get(), 42);

// Increment and decrement
gauge.inc();
assert_eq!(gauge.get(), 43);
gauge.dec();
assert_eq!(gauge.get(), 42);

// Increment and decrement by custom values
gauge.inc_by(10);
assert_eq!(gauge.get(), 52);
gauge.dec_by(5);
assert_eq!(gauge.get(), 47);

// Set to specific value
gauge.set(-10);
assert_eq!(gauge.get(), -10);
```

--------------------------------

### LazyCounter Example

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/counter.rs.html

Demonstrates how to create and use a LazyCounter, which computes its value lazily. Ideal for metrics that involve expensive OS queries or computations, ensuring they are only performed when the metric is scraped.

```rust
use std::sync::atomic::{AtomicU64, Ordering};
use fastmetrics::metrics::counter::LazyCounter;

let lazy = LazyCounter::new({
    let total = AtomicU64::new(42);
    move || total.load(Ordering::Relaxed)
});
assert_eq!(lazy.fetch(), 42);
```

--------------------------------

### Create and Get a ConstGauge

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/gauge/struct.ConstGauge.html

Demonstrates how to create a new ConstGauge with an initial value and then retrieve that value. This is useful for metrics that have a fixed, unchanging value.

```rust
let gauge = ConstGauge::new(42);
assert_eq!(gauge.get(), 42);
```

--------------------------------

### Registering a metric with a custom unit (Gauge)

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/fn.register_with_unit.html

This example demonstrates registering a gauge metric with a custom unit string, such as 'celsius'. The custom unit must adhere to OpenMetrics ABNF rules.

```rust
let temperature = register_with_unit(
    "cpu_temperature",
    "CPU temperature",
    "celsius",
    <Gauge>::default(),
)?;

temperature.set(65);
```

--------------------------------

### Examples of EncodeLabelValue Implementations

Source: https://docs.rs/fastmetrics/latest/fastmetrics/encoder/trait.EncodeLabelValue.html

Demonstrates how common types like strings, integers, and booleans implement the EncodeLabelValue trait.

```rust
let value: &str = "200"; // str implements `EncodeLabelValue`
let value: i32 = 200;    // integers implement `EncodeLabelValue`
let value: bool = true;  // bool implements `EncodeLabelValue`
```

--------------------------------

### Counter Initialization

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/counter.rs.html

Shows how to initialize a default Counter and a Counter with a creation timestamp. The default counter starts at 0 with no creation time, while the `with_created` variant includes a specific timestamp.

```rust
let counter = <Counter>::default();
assert_eq!(counter.total(), 0);
assert!(counter.created().is_none());

let created = std::time::SystemTime::UNIX_EPOCH
    .elapsed()
    .expect("UNIX timestamp when the counter was created");
let counter = <Counter>::with_created(created);
assert_eq!(counter.total(), 0);
assert!(counter.created().is_some());
```

--------------------------------

### Get Metric Help Text

Source: https://docs.rs/fastmetrics/latest/fastmetrics/raw/metadata/struct.Metadata.html

Retrieves the help text describing the metric family, included as a HELP comment in OpenMetrics output.

```rust
pub fn help(&self) -> &str
```

--------------------------------

### Get Metric Reference and Apply Function

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/family.rs.html

Demonstrates retrieving a metric by its labels and applying a function to it, returning `None` if the metric does not exist.

```rust
/// #[derive(Clone, Eq, PartialEq, Hash)]
/// struct Labels {
///     method: &'static str,
///     status: &'static str,
/// }
///
/// impl LabelSetSchema for Labels {
///     fn names() -> Option<&'static [&'static str]> {
///         Some(&["method", "status"])
///     }
/// }
///
/// impl EncodeLabelSet for Labels {
///     fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
///         encoder.encode(&("method", self.method))?;
///         encoder.encode(&("status", self.status))?;
///         Ok(())
///     }
/// }
///
/// let http_requests = Family::<Labels, Counter>::default();
///
/// registry.register("http_requests", "Total HTTP requests", http_requests.clone())?;
///
/// let labels = Labels { method: "GET", status: "200" };
/// assert_eq!(http_requests.with(&labels, |req| req.total()), None);
```

--------------------------------

### Implementing Register for a Custom Metrics Struct

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/trait.Register.html

Example of implementing the `Register` trait for a custom `Metrics` struct. This demonstrates how to register individual metrics within the `register` method.

```rust
#[derive(Clone, Default)]
struct Metrics {
    counter: Counter,
}

impl Register for Metrics {
    fn register(&self, registry: &mut Registry) -> Result<()> {
        registry.register("my_counter", "My counter help", self.counter.clone())?;
        Ok(())
    }
}

fn main() -> Result<()> {
    let mut registry = Registry::default();
    let metrics = Metrics::default();
    metrics.register(&mut registry)?;
    // ...
    Ok(())
}
```

--------------------------------

### Using with_or_new for Metric Operations

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/family/struct.Family.html

This example shows the core usage of the `with_or_new` method on a Family metric. It creates a metric if it doesn't exist and applies a function, then asserts the resulting metric value.

```rust
let mut registry = Registry::default();

#[derive(Clone, Eq, PartialEq, Hash)]
struct Labels {
    method: &'static str,
    status: &'static str,
}

impl LabelSetSchema for Labels {
    fn names() -> Option<&'static [&'static str]> {
        Some(&["method", "status"])
    }
}

impl EncodeLabelSet for Labels {
    fn encode(&self, encoder: &mut dyn LabelSetEncoder) -> Result<()> {
        encoder.encode(&("method", self.method))?;
        encoder.encode(&("status", self.status))?;
        Ok(())
    }
}

let http_requests = Family::<Labels, Counter>::default();

registry.register("http_requests", "Total HTTP requests", http_requests.clone())?;

let labels = Labels { method: "GET", status: "200" };
http_requests.with_or_new(&labels, |req| req.inc());
assert_eq!(http_requests.with(&labels, |req| req.total()), Some(1));
```

--------------------------------

### Implementing StateSetValue for ConstStateSet Example

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/state_set.rs.html

Provides an example implementation of the `StateSetValue` trait for a `JobState` enum, intended for use with `ConstStateSet`.

```rust
use fastmetrics::metrics::state_set::{ConstStateSet, StateSetValue};

#[derive(Copy, Clone, Debug, PartialEq)]
enum JobState {
    Pending,
    Running,
    Completed,
    Failed,
}

// Can use `#[derive(StateSetValue)]` to simplify the code, but need to enable `derive` feature
impl StateSetValue for JobState {
    fn variants() -> &'static [Self] {
        &[Self::Pending, Self::Running, Self::Completed, Self::Failed]
    }

    fn as_str(&self) -> &str {
        match self {
            Self::Pending => "Pending",
            Self::Running => "Running",
            Self::Completed => "Completed",
            Self::Failed => "Failed",
        }
    }
}

```

--------------------------------

### Building a Registry with Namespaces and Constant Labels

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Demonstrates how to initialize a new registry with a specific namespace and constant labels. This serves as a base for creating subsystems.

```rust
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;
```

--------------------------------

### Rust Histogram Snapshot Access Example

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/histogram.rs.html

Shows how to access a snapshot of a Histogram's current state using the `with_snapshot` method and a closure. This allows inspecting the total count and sum of observed values.

```rust
use fastmetrics::metrics::histogram::{Histogram, linear_buckets};

let hist = Histogram::new(linear_buckets(1.0, 1.0, 3));
hist.observe(2.5);

hist.with_snapshot(|s| {
    assert_eq!(s.count(), 1);
    assert_eq!(s.sum(), 2.5);
});

```

--------------------------------

### Building a Registry with a Subsystem

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/struct.RegistrySubsystemBuilder.html

Demonstrates how to build a root registry with a namespace and constant labels, and then create a subsystem with its own specific labels.

```rust
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;

let subsystem = registry
    .subsystem_builder("database")
    .with_const_labels([("engine", "innodb"), ("instance", "primary")])
    .build()?;
```

--------------------------------

### ConstStateSet::get

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/state_set/struct.ConstStateSet.html

Gets the current state of the ConstStateSet.

```APIDOC
## `get`

### Description

Gets the current state.

### Signature

```rust
pub fn get(&self) -> &T
```

### Returns

A reference to the current state.
```

--------------------------------

### Generate Linear Buckets

Source: https://docs.rs/fastmetrics/latest/fastmetrics/raw/bucket/fn.linear_buckets.html

Creates 5 linearly spaced buckets starting from 0.0 with a width of 1.0. Asserts that the generated buckets match the expected values.

```rust
let buckets: Vec<f64> = linear_buckets(0.0, 1.0, 5).collect();
assert_eq!(buckets, vec![0.0, 1.0, 2.0, 3.0, 4.0]);
```

--------------------------------

### Create and Configure Registry with Namespace and Labels

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/struct.Registry.html

Demonstrates how to create a new Registry instance with a specified namespace and constant labels. It also shows how to register metrics and create nested subsystems with additional labels.

```rust
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;
assert_eq!(registry.namespace(), Some("myapp"));
assert_eq!(registry.constant_labels(), [("env".into(), "prod".into())]);

let uptime_seconds = <Gauge>::default();
registry.register("uptime_seconds", "Application uptime", uptime_seconds.clone())?;

let db = registry.subsystem("database")?;
assert_eq!(db.namespace(), Some("myapp_database"));
assert_eq!(db.constant_labels(), [("env".into(), "prod".into())]);

let db_connections = <Gauge>::default();
db.register("connections", "Active database connections", db_connections.clone())?;

let mysql = db.subsystem_builder("mysql").with_const_labels([("engine", "innodb")]).build()?;
assert_eq!(mysql.namespace(), Some("myapp_database_mysql"));
assert_eq!(
    mysql.constant_labels(),
    [("env".into(), "prod".into()), ("engine".into(), "innodb".into())],
);

let mysql_queries = <Counter>::default();
mysql.register("queries", "Total MySQL queries", mysql_queries.clone())?;
```

--------------------------------

### Example of EncodeLabel Implementation for Tuples

Source: https://docs.rs/fastmetrics/latest/fastmetrics/encoder/trait.EncodeLabel.html

Demonstrates how a tuple representing a name-value pair implements EncodeLabel. This is useful for directly encoding string literals or other compatible types as labels.

```rust
let label = ("method", "GET"); // implements `EncodeLabel`
```

--------------------------------

### Get Gauge Value

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/gauge.rs.html

Retrieves the current value of the Gauge.

```rust
pub fn get(&self) -> N {
        self.value.get()
    }
```

--------------------------------

### Build Registry with Namespace and Constant Labels

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/struct.Registry.html

Demonstrates building a registry with a namespace and constant labels, and then creating nested subsystems that inherit these configurations.

```rust
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;
assert_eq!(registry.namespace(), Some("myapp"));
assert_eq!(registry.constant_labels(), [("env".into(), "prod".into())]);

let subsystem1 = registry.subsystem("subsystem1")?;
assert_eq!(subsystem1.namespace(), Some("myapp_subsystem1"));
assert_eq!(subsystem1.constant_labels(), [("env".into(), "prod".into())]);

let subsystem2 = registry.subsystem("subsystem2")?;
assert_eq!(subsystem2.namespace(), Some("myapp_subsystem2"));
assert_eq!(subsystem2.constant_labels(), [("env".into(), "prod".into())]);

let nested_subsystem =
    registry.subsystem("subsystem1")?.subsystem("subsystem2")?;
assert_eq!(nested_subsystem.namespace(), Some("myapp_subsystem1_subsystem2"));
assert_eq!(nested_subsystem.constant_labels(), [("env".into(), "prod".into())]);
```

--------------------------------

### with

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/family.rs.html

Gets a reference to the metric with the specified labels and applies a function to it.

```APIDOC
## with

### Description
Gets a reference to the metric with the specified labels and applies a function to it. If no metric exists for the given label set, the function is not applied and `None` is returned.

### Signature
```rust
pub fn with<F, R>(&self, labels: &LS, func: F) -> Option<R>
where
    F: FnOnce(&M) -> R,
```

### Parameters
* `labels`: The labels to identify the metric.
* `func`: A closure that takes a reference to the metric `M` and returns a value `R`.

### Returns
Returns `Some(R)` where `R` is the return value of `func` if the metric exists, or `None` if no metric exists for the given label set.

### Example
```rust
# use fastmetrics::metrics::family::Family;
# use fastmetrics::metrics::counter::Counter;
# #[derive(Clone, Eq, PartialEq, Hash)]
# struct Labels { method: &'static str, status: &'static str }
# impl fastmetrics::raw::LabelSetSchema for Labels { fn names() -> Option<&'static [&'static str]> { Some(&["method", "status"]) } }
# impl fastmetrics::encoder::EncodeLabelSet for Labels { fn encode(&self, encoder: &mut dyn fastmetrics::encoder::LabelSetEncoder) -> fastmetrics::error::Result<()> { encoder.encode(&("method", self.method))?; encoder.encode(&("status", self.status))?; Ok(()) } }
# fn main() -> fastmetrics::error::Result<()> {
let http_requests = Family::<Labels, Counter>::default();
let labels = Labels { method: "GET", status: "200" };
assert_eq!(http_requests.with(&labels, |req| req.total()), None);
# Ok(())
# }
```
```

--------------------------------

### Create a RegistryBuilder

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Instantiate a `RegistryBuilder` to begin configuring a new `Registry`. This is the entry point for building a registry.

```rust
pub fn builder() -> RegistryBuilder {
        RegistryBuilder::default()
    }
```

--------------------------------

### Counter::created

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/counter/struct.Counter.html

Gets the optional creation timestamp of the Counter.

```APIDOC
## Counter::created

### Description
Retrieves the optional creation timestamp of the `Counter`. This will return `Some(Duration)` if the counter was created with a timestamp, and `None` otherwise.

### Method
`counter.created() -> Option<Duration>`

### Returns
An `Option<Duration>` representing the creation timestamp, or `None` if not set.

### Example
```rust
use fastmetrics::metrics::counter::Counter;
use std::time::{SystemTime, Duration};

let counter_with_time = <Counter>::with_created(Duration::from_secs(100));
assert!(counter_with_time.created().is_some());

let counter_without_time = <Counter>::default();
assert!(counter_without_time.created().is_none());
```
```

--------------------------------

### Register a static metric using LazyLock

Source: https://docs.rs/fastmetrics/latest/fastmetrics/registry/fn.register_metric.html

This example shows how to register a metric lazily using `LazyLock`. This is useful for static metrics that are initialized only when first accessed, ensuring they are registered correctly even in concurrent environments.

```rust
static MEMORY_USAGE: LazyLock<Gauge> = LazyLock::new(|| {
    register_metric(
        "memory_usage",
        "Current memory usage",
        Some(Unit::Bytes),
        <Gauge>::default(),
    )
    .expect("Failed to register memory_usage gauge")
});

fn update_memory_stats() {
    MEMORY_USAGE.set(1024 * 1024 * 512); // 512MB
}
```

--------------------------------

### Counter::total

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/counter/struct.Counter.html

Gets the current total value of the Counter.

```APIDOC
## Counter::total

### Description
Retrieves the current total value of the `Counter`.

### Method
`counter.total() -> N`

### Returns
The current total value of the `Counter`.

### Example
```rust
use fastmetrics::metrics::counter::Counter;

let counter = <Counter>::default();
counter.inc_by(5);
assert_eq!(counter.total(), 5);
```
```

--------------------------------

### Building a Subsystem with Constant Labels

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Shows how to create a subsystem builder, attach it to a parent registry, and configure it with its own set of constant labels. These labels will be merged with the parent's labels.

```rust
let subsystem = registry
    .subsystem_builder("database")
    .with_const_labels([("engine", "innodb"), ("instance", "primary")])
    .build()?;
```

--------------------------------

### Get Error Kind

Source: https://docs.rs/fastmetrics/latest/fastmetrics/error/struct.Error.html

Retrieves the specific kind of the error.

```rust
pub fn kind(&self) -> ErrorKind
```

--------------------------------

### Get Error Message

Source: https://docs.rs/fastmetrics/latest/fastmetrics/error/struct.Error.html

Retrieves the human-readable message associated with the error.

```rust
pub fn message(&self) -> &str
```

--------------------------------

### Get Error Message

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/error.rs.html

Returns the primary error message associated with the error.

```rust
pub fn message(&self) -> &str {
        &self.message
    }
```

--------------------------------

### Get Total Histogram Sum

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/histogram/struct.HistogramSnapshot.html

Retrieves the sum of all observed values in the histogram.

```rust
pub const fn sum(&self) -> f64
```

--------------------------------

### Creating Subsystems with Inherited and Specific Labels

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Shows how to create subsystems that inherit the parent registry's namespace and constant labels, and how to add subsystem-specific labels.

```rust
let subsystem1 = registry.subsystem("subsystem1")?;
assert_eq!(subsystem1.namespace(), Some("myapp_subsystem1"));
assert_eq!(subsystem1.constant_labels(), [("env".into(), "prod".into())]);
```

```rust
let nested_subsystem = registry.subsystem("subsystem1").unwrap().subsystem("subsystem2")?;
assert_eq!(nested_subsystem.namespace(), Some("myapp_subsystem1_subsystem2"));
assert_eq!(nested_subsystem.constant_labels(), [("env".into(), "prod".into())]);
```

```rust
let subsystem1 = registry
    .subsystem_builder("subsystem1")
    .with_const_labels([("name", "value")])
    .build()?;
assert_eq!(subsystem1.namespace(), Some("myapp_subsystem1"));
assert_eq!(
    subsystem1.constant_labels(),
    [("env".into(), "prod".into()), ("name".into(), "value".into())]
);
```

--------------------------------

### Creating and Configuring a Fastmetrics Registry

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Demonstrates how to create a new Registry with a namespace, constant labels, and register different types of metrics. It also shows how to create nested subsystems with additional labels.

```rust
use fastmetrics::{
    error::Result,
    metrics::{counter::Counter, gauge::Gauge},
    registry::Registry,
};

fn main() -> Result<()> {
// Create a registry with a `myapp` namespace
let mut registry = Registry::builder()
    .with_namespace("myapp")
    .with_const_labels([("env", "prod")])
    .build()?;
assert_eq!(registry.namespace(), Some("myapp"));
assert_eq!(registry.constant_labels(), [("env".into(), "prod".into())]);

// Register metrics into the registry
let uptime_seconds = <Gauge>::default();
registry.register("uptime_seconds", "Application uptime", uptime_seconds.clone())?;

// Create a subsystem for database metrics
let db = registry.subsystem("database")?;
assert_eq!(db.namespace(), Some("myapp_database"));
assert_eq!(db.constant_labels(), [("env".into(), "prod".into())]);

// Register metrics into the database subsystem
let db_connections = <Gauge>::default();
db.register("connections", "Active database connections", db_connections.clone())?;

// Create a nested subsystem with additional constant labels
let mysql = db.subsystem_builder("mysql").with_const_labels([("engine", "innodb")]).build()?;
assert_eq!(mysql.namespace(), Some("myapp_database_mysql"));
assert_eq!(
    mysql.constant_labels(),
    [("env".into(), "prod".into()), ("engine".into(), "innodb".into())],
);

// Register metrics into the mysql subsystem
let mysql_queries = <Counter>::default();
mysql.register("queries", "Total MySQL queries", mysql_queries.clone())?;
Ok(())
}

```

--------------------------------

### Get Constant Gauge Value

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/gauge.rs.html

Retrieves the constant value of the `ConstGauge`. This operation is `const`.

```rust
pub const fn get(&self) -> N {
        self.value
    }
```

--------------------------------

### Get Total Histogram Count

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/histogram/struct.HistogramSnapshot.html

Retrieves the total number of observations recorded in the histogram.

```rust
pub const fn count(&self) -> u64
```

--------------------------------

### ConstGauge Initialization

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/metrics/types/gauge.rs.html

Shows how to create a ConstGauge with a fixed value and demonstrates cloning it.

```rust
let gauge = ConstGauge::new(42i64);
assert_eq!(gauge.get(), 42);

let clone = gauge.clone();
assert_eq!(clone.get(), 42);
```

--------------------------------

### Get Unknown Value

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/unknown/struct.Unknown.html

Retrieves a reference to the unknown value stored within the Unknown metric.

```rust
pub fn get(&self) -> &T
```

--------------------------------

### Building Subsystems with Constant Labels

Source: https://docs.rs/fastmetrics/latest/src/fastmetrics/registry/mod.rs.html

Demonstrates building a subsystem with constant labels and testing scenarios for invalid, mismatched, and identical labels.

```rust
fn test_subsystem_const_labels_existing_behaviors() -> Result<()> {
        let mut registry = Registry::builder().with_namespace("myapp").build()?;
        registry
            .subsystem_builder("cache")
            .with_const_labels([("role", "primary")])
            .build()?;

        // Existing subsystem with invalid constant labels should error
        let result_invalid = registry
            .subsystem_builder("cache")
            .with_const_labels([("1invalid", "value")])
            .build();
        assert!(result_invalid.is_err());

        // Existing subsystem with different constant labels should error
        let result_mismatch = registry
            .subsystem_builder("cache")
            .with_const_labels([("role", "secondary")])
            .build();
        assert!(result_mismatch.is_err());

        // Same subsystem with identical constant labels should be reused
        let result_same = registry
            .subsystem_builder("cache")
            .with_const_labels([("role", "primary")])
            .build();
        assert!(result_same.is_ok());

        Ok(())
    }
```

--------------------------------

### Get Histogram Bucket Counts

Source: https://docs.rs/fastmetrics/latest/fastmetrics/metrics/histogram/struct.HistogramSnapshot.html

Retrieves the current counts for each bucket in the histogram. These counts are non-cumulative.

```rust
pub fn buckets(&self) -> &[Bucket]
```
Tokens:
Raw