1 // Copyright 2019 TiKV Project Authors. Licensed under Apache-2.0. 2 3 /*! 4 The Rust client library for [Prometheus](https://prometheus.io/). 5 6 Use of this library involves a few core concepts: 7 8 * [`Metric`s](core/trait.Metric.html) like [`Counter`s](type.Counter.html) that 9 represent information about your system. 10 11 * A [`Registry`](struct.Registry.html) that [`Metric`s](core/trait.Metric.html) 12 are registered with. 13 14 * An endpoint that calls [`gather`](fn.gather.html) which returns 15 [`MetricFamily`s](proto/struct.MetricFamily.html) through an 16 [`Encoder`](trait.Encoder.html). 17 18 19 # Basic Example 20 21 ```rust 22 use prometheus::{Opts, Registry, Counter, TextEncoder, Encoder}; 23 24 // Create a Counter. 25 let counter_opts = Opts::new("test_counter", "test counter help"); 26 let counter = Counter::with_opts(counter_opts).unwrap(); 27 28 // Create a Registry and register Counter. 29 let r = Registry::new(); 30 r.register(Box::new(counter.clone())).unwrap(); 31 32 // Inc. 33 counter.inc(); 34 35 // Gather the metrics. 36 let mut buffer = vec![]; 37 let encoder = TextEncoder::new(); 38 let metric_families = r.gather(); 39 encoder.encode(&metric_families, &mut buffer).unwrap(); 40 41 // Output to the standard output. 42 println!("{}", String::from_utf8(buffer).unwrap()); 43 ``` 44 45 You can find more examples within 46 [`/examples`](https://github.com/tikv/rust-prometheus/tree/master/examples). 47 48 49 # Static Metrics 50 51 This crate supports staticly built metrics. You can use it with 52 [`lazy_static`](https://docs.rs/lazy_static/) to quickly build up and collect 53 some metrics. 54 55 ```rust 56 #[macro_use] extern crate lazy_static; 57 #[macro_use] extern crate prometheus; 58 use prometheus::{self, IntCounter, TextEncoder, Encoder}; 59 60 lazy_static! { 61 static ref HIGH_FIVE_COUNTER: IntCounter = 62 register_int_counter!("highfives", "Number of high fives received").unwrap(); 63 } 64 65 HIGH_FIVE_COUNTER.inc(); 66 assert_eq!(HIGH_FIVE_COUNTER.get(), 1); 67 ``` 68 69 By default, this registers with a default registry. To make a report, you can call 70 [`gather`](fn.gather.html). This will return a family of metrics you can then feed through an 71 [`Encoder`](trait.Encoder.html) and report to Promethus. 72 73 ``` 74 # #[macro_use] extern crate lazy_static; 75 #[macro_use] extern crate prometheus; 76 # use prometheus::IntCounter; 77 use prometheus::{self, TextEncoder, Encoder}; 78 79 // Register & measure some metrics. 80 # lazy_static! { 81 # static ref HIGH_FIVE_COUNTER: IntCounter = 82 # register_int_counter!("highfives", "Number of high fives received").unwrap(); 83 # } 84 # HIGH_FIVE_COUNTER.inc(); 85 86 let mut buffer = Vec::new(); 87 let encoder = TextEncoder::new(); 88 89 // Gather the metrics. 90 let metric_families = prometheus::gather(); 91 // Encode them to send. 92 encoder.encode(&metric_families, &mut buffer).unwrap(); 93 94 let output = String::from_utf8(buffer.clone()).unwrap(); 95 const EXPECTED_OUTPUT: &'static str = "# HELP highfives Number of high fives received\n# TYPE highfives counter\nhighfives 1\n"; 96 assert!(output.starts_with(EXPECTED_OUTPUT)); 97 ``` 98 99 See [prometheus_static_metric](https://docs.rs/prometheus-static-metric) for 100 additional functionality. 101 102 103 # Features 104 105 This library supports four features: 106 107 * `gen`: To generate protobuf client with the latest protobuf version instead of 108 using the pre-generated client. 109 * `nightly`: Enable nightly only features. 110 * `process`: For collecting process info. 111 * `push`: Enable push support. 112 113 */ 114 115 #![allow( 116 clippy::needless_pass_by_value, 117 clippy::new_without_default, 118 clippy::new_ret_no_self 119 )] 120 #![deny(missing_docs)] 121 #![deny(missing_debug_implementations)] 122 123 /// Protocol buffers format of metrics. 124 #[cfg(feature = "protobuf")] 125 #[allow(warnings)] 126 #[rustfmt::skip] 127 #[path = "../proto/proto_model.rs"] 128 pub mod proto; 129 130 #[cfg(feature = "protobuf")] 131 macro_rules! from_vec { 132 ($e: expr) => { 133 ::protobuf::RepeatedField::from_vec($e) 134 }; 135 } 136 137 #[cfg(not(feature = "protobuf"))] 138 #[path = "plain_model.rs"] 139 pub mod proto; 140 141 #[cfg(not(feature = "protobuf"))] 142 macro_rules! from_vec { 143 ($e: expr) => { 144 $e 145 }; 146 } 147 148 #[macro_use] 149 extern crate cfg_if; 150 #[macro_use] 151 extern crate lazy_static; 152 153 #[macro_use] 154 mod macros; 155 mod atomic64; 156 mod auto_flush; 157 mod counter; 158 mod desc; 159 mod encoder; 160 mod errors; 161 mod gauge; 162 mod histogram; 163 mod metrics; 164 #[cfg(feature = "push")] 165 mod push; 166 mod registry; 167 mod value; 168 mod vec; 169 170 // Public for generated code. 171 #[doc(hidden)] 172 pub mod timer; 173 174 #[cfg(all(feature = "process", target_os = "linux"))] 175 pub mod process_collector; 176 177 pub mod local { 178 /*! 179 180 Unsync local metrics, provides better performance. 181 182 */ 183 pub use super::counter::{ 184 CounterWithValueType, LocalCounter, LocalCounterVec, LocalIntCounter, LocalIntCounterVec, 185 }; 186 pub use super::histogram::{LocalHistogram, LocalHistogramTimer, LocalHistogramVec}; 187 pub use super::metrics::{LocalMetric, MayFlush}; 188 189 pub use super::auto_flush::{ 190 AFLocalCounter, AFLocalHistogram, CounterDelegator, HistogramDelegator, 191 }; 192 } 193 194 pub mod core { 195 /*! 196 197 Core traits and types. 198 199 */ 200 201 pub use super::atomic64::*; 202 pub use super::counter::{ 203 GenericCounter, GenericCounterVec, GenericLocalCounter, GenericLocalCounterVec, 204 }; 205 pub use super::desc::{Desc, Describer}; 206 pub use super::gauge::{GenericGauge, GenericGaugeVec}; 207 pub use super::metrics::{Collector, Metric, Opts}; 208 pub use super::vec::{MetricVec, MetricVecBuilder}; 209 } 210 211 pub use self::counter::{Counter, CounterVec, IntCounter, IntCounterVec}; 212 pub use self::encoder::Encoder; 213 #[cfg(feature = "protobuf")] 214 pub use self::encoder::ProtobufEncoder; 215 pub use self::encoder::TextEncoder; 216 #[cfg(feature = "protobuf")] 217 pub use self::encoder::{PROTOBUF_FORMAT, TEXT_FORMAT}; 218 pub use self::errors::{Error, Result}; 219 pub use self::gauge::{Gauge, GaugeVec, IntGauge, IntGaugeVec}; 220 pub use self::histogram::DEFAULT_BUCKETS; 221 pub use self::histogram::{exponential_buckets, linear_buckets}; 222 pub use self::histogram::{Histogram, HistogramOpts, HistogramTimer, HistogramVec}; 223 pub use self::metrics::Opts; 224 #[cfg(feature = "push")] 225 pub use self::push::{ 226 hostname_grouping_key, push_add_collector, push_add_metrics, push_collector, push_metrics, 227 BasicAuthentication, 228 }; 229 pub use self::registry::Registry; 230 pub use self::registry::{default_registry, gather, register, unregister}; 231