substreams_sink_prometheus/lib.rs
1//! [![github]](https://github.com/pinax-network/substreams-sink-prometheus) [![crates-io]](https://crates.io/crates/substreams-sink-prometheus) [![docs-rs]](crate)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6//!
7//! > `substreams-sink-prom` is a tool that allows developers to pipe metrics extracted from a blockchain into a Prometheus time series database.
8//!
9//! ## 🛠Feature Roadmap
10//!
11//! ### [Gauge Metric](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Gauge)
12//! - [x] Set
13//! - [x] Inc
14//! - [x] Dec
15//! - [x] Add
16//! - [x] Sub
17//! - [x] SetToCurrentTime
18//!
19//! ### [Counter Metric](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Counter)
20//! - [x] Inc
21//! - [x] Add
22//!
23//! ### [Histogram Metric](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Histogram)
24//! - [x] Observe
25//! - [ ] buckets
26//! - [x] Zero
27//!
28//! ### [Summary Metric](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Summary)
29//! > Summaries calculate percentiles of observed values.
30//! - [x] Observe
31//! - [ ] percentiles
32//! - [ ] maxAgeSeconds
33//! - [ ] ageBuckets
34//! - [ ] compressCount
35//! - [x] StartTimer
36//!
37//! ### [Registry](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Summary)
38//! - [ ] Clear
39//! - [ ] SetDefaultLabels
40//! - [ ] RemoveSingleMetric
41//!
42//! ### Example
43//! ```
44//! use std::collections::HashMap;
45//! use substreams_sink_prometheus::{PrometheusOperations, Gauge, Counter, Summary, Histogram};
46//!
47//! // Initialize Prometheus Operations container
48//! let mut prom_ops: PrometheusOperations = Default::default();
49//!
50//! // Counter Metric
51//! // ==============
52//! // Initialize Gauge with a name & labels
53//! let mut counter = Counter::from("counter_name");
54//!
55//! // Increments the Counter by 1.
56//! prom_ops.push(counter.inc());
57//!
58//! // Adds an arbitrary value to a Counter. (Returns an error if the value is < 0.)
59//! prom_ops.push(counter.add(123.456));
60//!
61//! // Labels
62//! // ======
63//! // Create a HashMap of labels
64//! // Labels represents a collection of label name -> value mappings.
65//! let labels1 = HashMap::from([("label1".to_string(), "value1".to_string())]);
66//! let mut labels2 = HashMap::new();
67//! labels2.insert("label2".to_string(), "value2".to_string());
68//!
69//! // Gauge Metric
70//! // ============
71//! // Initialize Gauge
72//! let mut gauge = Gauge::from("gauge_name").with(labels1);
73//!
74//! // Sets the Gauge to an arbitrary value.
75//! prom_ops.push(gauge.set(88.8));
76//!
77//! // Increments the Gauge by 1.
78//! prom_ops.push(gauge.inc());
79//!
80//! // Decrements the Gauge by 1.
81//! prom_ops.push(gauge.dec());
82//!
83//! // Adds an arbitrary value to a Gauge. (The value can be negative, resulting in a decrease of the Gauge.)
84//! prom_ops.push(gauge.add(50.0));
85//! prom_ops.push(gauge.add(-10.0));
86//!
87//! // Subtracts arbitrary value from the Gauge. (The value can be negative, resulting in an increase of the Gauge.)
88//! prom_ops.push(gauge.sub(25.0));
89//! prom_ops.push(gauge.sub(-5.0));
90//!
91//! // Set Gauge to the current Unix time in seconds.
92//! prom_ops.push(gauge.set_to_current_time());
93//!
94//! // Remove metrics for the given label values
95//! prom_ops.push(gauge.remove(labels2));
96//!
97//! // Reset gauge values
98//! prom_ops.push(gauge.reset());
99//!
100//! // Summary Metric
101//! // ==============
102//! // Initialize Summary
103//! let mut summary = Summary::from("summary_name");
104//!
105//! /// Observe adds a single observation to the summary.
106//! /// Observations are usually positive or zero.
107//! /// Negative observations are accepted but prevent current versions of Prometheus from properly detecting counter resets in the sum of observations
108//! prom_ops.push(summary.observe(88.8));
109//!
110//! // Start a timer. Calling the returned function will observe the duration in seconds in the summary.
111//! prom_ops.push(summary.start_timer());
112//!
113//! // Histogram Metric
114//! // ==============
115//! // Initialize Summary
116//! let mut histogram = Histogram::from("histogram_name");
117//!
118//! /// Observe adds a single observation to the histogram.
119//! /// Observations are usually positive or zero.
120//! /// Negative observations are accepted but prevent current versions of Prometheus from properly detecting counter resets in the sum of observations
121//! prom_ops.push(histogram.observe(88.8));
122//!
123//! // Start a timer. Calling the returned function will observe the duration in seconds in the histogram.
124//! prom_ops.push(histogram.start_timer());
125//!
126//! // Initialize the metrics for the given combination of labels to zero
127//! prom_ops.push(histogram.zero(HashMap::from([("label1".to_string(), "value1".to_string())])));
128//! ```
129#[path = "pb/pinax.substreams.sink.prometheus.v1.rs"]
130#[allow(dead_code)]
131pub mod pb;
132pub use self::pb::*;
133
134mod counter;
135mod helpers;
136pub use self::counter::*;
137mod gauge;
138pub use self::gauge::*;
139mod summary;
140pub use self::summary::*;
141mod histogram;
142pub use self::histogram::*;
143mod labels;
144pub use self::labels::*;