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