substreams-sink-prometheus

Crates.iosubstreams-sink-prometheus
lib.rssubstreams-sink-prometheus
version0.1.9
sourcesrc
created_at2023-02-04 21:09:11.207082
updated_at2023-02-16 14:30:42.45753
descriptionSubstreams Prometheus sink module
homepagehttps://github.com/pinax-network/substreams-sink-prometheus
repositoryhttps://github.com/pinax-network/substreams-sink-prometheus
max_upload_size
id776632
size339,148
Yaro Shkvorets (YaroShkvorets)

documentation

README

Substreams Prometheus sink module

github crates.io npm docs.rs GitHub Workflow Status

substreams-sink-prometheus is a tool that allows developers to pipe data extracted metrics from a blockchain into a Prometheus time series database.

📖 Documentation

https://docs.rs/substreams-sink-prometheus

Further resources

CLI

Use pre-built binaries

  • MacOS
  • Linux
  • Windows

Install globally via npm

$ npm install -g substreams-sink-prometheus

Run

$ substreams-sink-prometheus run [options] <spkg>

Open the browser at http://localhost:9102/metrics

🛠 Feature Roadmap

Gauge Metric

  • Set
  • Inc
  • Dec
  • Add
  • Sub
  • SetToCurrentTime
  • Remove
  • Reset

Counter Metric

  • Inc
  • Add
  • Remove
  • Reset

Histogram Metric

  • Observe
    • buckets
  • Zero

Summary Metric

Summaries calculate percentiles of observed values.

  • Observe
    • percentiles
    • maxAgeSeconds
    • ageBuckets
    • compressCount
  • StartTimer

Registry

  • Clear
  • SetDefaultLabels
  • RemoveSingleMetric

Install

$ cargo add substreams-sink-prometheus

Quickstart

Cargo.toml

[dependencies]
substreams = "0.5"
substreams-sink-prometheus = "0.1"

src/lib.rs

use std::collections::HashMap;
use substreams::prelude::*;
use substreams::errors::Error;
use substreams_sink_prometheus::{PrometheusOperations, Counter, Gauge, Summary, Histogram};

#[substreams::handlers::map]
fn prom_out(
    ... some stores ...
) -> Result<PrometheusOperations, Error> {

    // Initialize Prometheus Operations container
    let mut prom_ops: PrometheusOperations = Default::default();

    // Counter Metric
    // ==============
    // Initialize Gauge with a name & labels
    let mut counter = Counter::from("counter_name");

    // Increments the Counter by 1.
    prom_ops.push(counter.inc());

    // Adds an arbitrary value to a Counter. (Returns an error if the value is < 0.)
    prom_ops.push(counter.add(123.456));

    // Labels
    // ======
    // Create a HashMap of labels
    // Labels represents a collection of label name -> value mappings. 
    let labels1 = HashMap::from([("label1".to_string(), "value1".to_string())]);
    let mut labels2 = HashMap::new();
    labels2.insert("label2".to_string(), "value2".to_string());

    // Gauge Metric
    // ============
    // Initialize Gauge
    let mut gauge = Gauge::from("gauge_name").with(labels1);

    // Sets the Gauge to an arbitrary value.
    prom_ops.push(gauge.set(88.8));

    // Increments the Gauge by 1.
    prom_ops.push(gauge.inc());

    // Decrements the Gauge by 1.
    prom_ops.push(gauge.dec());

    // Adds an arbitrary value to a Gauge. (The value can be negative, resulting in a decrease of the Gauge.)
    prom_ops.push(gauge.add(50.0));
    prom_ops.push(gauge.add(-10.0));

    // Subtracts arbitrary value from the Gauge. (The value can be negative, resulting in an increase of the Gauge.)
    prom_ops.push(gauge.sub(25.0));
    prom_ops.push(gauge.sub(-5.0));

    // Set Gauge to the current Unix time in seconds.
    prom_ops.push(gauge.set_to_current_time());

    // Remove metrics for the given label values
    prom_ops.push(gauge.remove(labels2));

    // Reset gauge values
    prom_ops.push(gauge.reset());

    // Summary Metric
    // ==============
    // Initialize Summary
    let mut summary = Summary::from("summary_name");

    /// Observe adds a single observation to the summary.
    /// Observations are usually positive or zero.
    /// Negative observations are accepted but prevent current versions of Prometheus from properly detecting counter resets in the sum of observations
    prom_ops.push(summary.observe(88.8));

    // Start a timer. Calling the returned function will observe the duration in seconds in the summary.
    prom_ops.push(summary.start_timer());

    // Histogram Metric
    // ==============
    // Initialize Summary
    let mut histogram = Histogram::from("histogram_name");

    /// Observe adds a single observation to the histogram.
    /// Observations are usually positive or zero.
    /// Negative observations are accepted but prevent current versions of Prometheus from properly detecting counter resets in the sum of observations
    prom_ops.push(histogram.observe(88.8));

    // Start a timer. Calling the returned function will observe the duration in seconds in the histogram.
    prom_ops.push(histogram.start_timer());

    // Initialize the metrics for the given combination of labels to zero
    prom_ops.push(histogram.zero(HashMap::from([("label1".to_string(), "value1".to_string())])));

    Ok(prom_ops)
}
Commit count: 133

cargo fmt