open_metrics_client/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(unused)]
3#![deny(dead_code)]
4
5//! Client library implementation of the [Open Metrics
6//! specification](https://github.com/OpenObservability/OpenMetrics). Allows
7//! developers to instrument applications and thus enables operators to monitor
8//! said applications with monitoring systems like
9//! [Prometheus](https://prometheus.io/).
10//!
11//! # Examples
12//!
13//! ```
14//! # use open_metrics_client::encoding::text::Encode;
15//! # use open_metrics_client::encoding::text::encode;
16//! # use open_metrics_client::metrics::counter::{Atomic, Counter};
17//! # use open_metrics_client::metrics::family::Family;
18//! # use open_metrics_client::registry::Registry;
19//! # use std::io::Write;
20//! #
21//! // Create a metric registry.
22//! //
23//! // Note the angle brackets to make sure to use the default (dynamic
24//! // dispatched boxed metric) for the generic type parameter.
25//! let mut registry = <Registry>::default();
26//!
27//! // Define a type representing a metric label set, i.e. a key value pair.
28//! //
29//! // You could as well use `(String, String)` to represent a label set,
30//! // instead of the custom type below.
31//! #[derive(Clone, Hash, PartialEq, Eq, Encode)]
32//! struct Labels {
33//!   // Use your own enum types to represent label values.
34//!   method: Method,
35//!   // Or just a plain string.
36//!   path: String,
37//! };
38//!
39//! #[derive(Clone, Hash, PartialEq, Eq, Encode)]
40//! enum Method {
41//!   GET,
42//!   PUT,
43//! };
44//!
45//! // Create a sample counter metric family utilizing the above custom label
46//! // type, representing the number of HTTP requests received.
47//! let http_requests = Family::<Labels, Counter>::default();
48//!
49//! // Register the metric family with the registry.
50//! registry.register(
51//!   // With the metric name.
52//!   "http_requests",
53//!   // And the metric help text.
54//!   "Number of HTTP requests received",
55//!   Box::new(http_requests.clone()),
56//! );
57//!
58//! // Somewhere in your business logic record a single HTTP GET request.
59//! http_requests.get_or_create(
60//!     &Labels { method: Method::GET, path: "/metrics".to_string() }
61//! ).inc();
62//!
63//! // When a monitoring system like Prometheus scrapes the local node, encode
64//! // all metrics in the registry in the text format, and send the encoded
65//! // metrics back.
66//! let mut buffer = vec![];
67//! encode(&mut buffer, &registry).unwrap();
68//!
69//! let expected = "# HELP http_requests Number of HTTP requests received.\n".to_owned() +
70//!                "# TYPE http_requests counter\n" +
71//!                "http_requests_total{method=\"GET\",path=\"/metrics\"} 1\n" +
72//!                "# EOF\n";
73//! assert_eq!(expected, String::from_utf8(buffer).unwrap());
74//! ```
75//! See [examples] directory for more.
76//!
77//! [examples]: https://github.com/mxinden/rust-open-metrics-client/tree/master/examples
78
79pub mod encoding;
80pub mod metrics;
81pub mod registry;
open_metrics_client/lib.rs

open_metrics_client/
lib.rs
