1pub use crate::counter::*;
2use crate::labels::MetricLabel;
3use crate::registry::StreamingCollector;
4pub use crate::sharded::{CountAndSize, ShardedCountAndSize};
5use async_stream::stream;
6use futures::stream::BoxStream;
7use futures::StreamExt;
8use parking_lot::{RwLock, RwLockUpgradableReadGuard};
9pub use pastey as paste;
10use serde::Serialize;
11use std::borrow::Borrow;
12use std::collections::HashMap;
13use std::hash::Hash;
14use std::sync::{Arc, LazyLock};
15
16mod counter;
17pub mod counter_bundle;
18
19#[macro_use]
20pub mod labels;
21pub mod parser;
22pub mod registry;
23mod sharded;
24pub use prometheus;
25
26struct CounterRegistryInner<K, V: AtomicCounterEntry> {
27 map: RwLock<HashMap<K, V>>,
28 name: &'static str,
29 help: String,
30 metric_type: MetricType,
31}
32
33const CHUNK_SIZE: usize = 4 * 1024;
36
37impl<K: Clone + MetricLabel + Send + Sync, V: AtomicCounterEntry> StreamingCollector
38 for CounterRegistryInner<K, V>
39{
40 fn stream_text(&'_ self, prefix: &Option<String>) -> BoxStream<'_, String> {
41 let mut buffer = String::with_capacity(CHUNK_SIZE);
49 buffer.push_str("# HELP ");
50 let prefix = prefix.as_deref().unwrap_or("").to_string();
51 buffer.push_str(&prefix);
52 buffer.push_str(self.name);
53 buffer.push(' ');
54 buffer.push_str(&self.help);
55 buffer.push_str("\n# TYPE ");
56 buffer.push_str(&prefix);
57 buffer.push_str(self.name);
58 buffer.push(' ');
59 buffer.push_str(self.metric_type.label());
60 buffer.push('\n');
61
62 let mut buffer = Some(buffer);
63
64 let counters = {
65 let map = self.map.read();
66 let mut pairs = Vec::with_capacity(map.len());
67 for (key, weak) in map.iter() {
68 if let Some(strong) = weak.resolve() {
69 pairs.push((key.clone(), strong));
70 }
71 }
72 pairs
73 };
74
75 stream! {
76 for (key, counter) in counters {
77 let Some(buf) = buffer.as_mut() else {break;};
78
79 buf.push_str(&prefix);
80 buf.push_str(self.name);
81 key.emit_text_value(buf, &counter.get().to_string());
82 buf.push('\n');
83
84 let need_flush = buf.len() >= CHUNK_SIZE;
85
86 if need_flush {
87 yield buffer.take().expect("always have buffer");
88 buffer.replace(String::with_capacity(CHUNK_SIZE));
89 }
90 }
91
92 if let Some(buf) = buffer.take() {
93 if !buf.is_empty(){
94 yield buf;
95 }
96 }
97
98 }
99 .boxed()
100 }
101
102 fn stream_json(&'_ self) -> BoxStream<'_, String> {
103 let mut target = String::with_capacity(CHUNK_SIZE);
104 target.push_str(",\n\"");
105 target.push_str(self.name);
106 target.push_str("\":{");
107 if !self.help.is_empty() {
108 target.push_str("\"help\":\"");
109 target.push_str(&self.help);
110 target.push_str("\",");
111 }
112 target.push_str("\"type\":\"");
113 target.push_str(self.metric_type.label());
114 target.push_str("\",\"value\":");
115
116 let counters = {
117 let map = self.map.read();
118 let mut pairs = Vec::with_capacity(map.len());
119 for (key, weak) in map.iter() {
120 if let Some(strong) = weak.resolve() {
121 pairs.push((key.clone(), strong));
122 }
123 }
124 pairs
125 };
126
127 stream! {
128 if counters.is_empty() {
129 target.push_str("null}");
130 yield target;
131 return;
132 }
133
134 let labels = K::label_names();
135
136 if labels.len() == 1 {
137 target.push_str("{\"");
138 target.push_str(labels[0]);
139 target.push_str("\":{");
140 } else {
141 target.push('[');
142 }
143
144 let mut buffer = Some(target);
145
146 for (i, (key, counter)) in counters.iter().enumerate() {
147 let Some(target) = buffer.as_mut() else {break;};
148 if i > 0 {
149 target.push_str(",\n");
150 }
151
152 let value = counter.get().to_string();
153 key.emit_json_value(target,&value);
154
155 let need_flush = target.len() >= CHUNK_SIZE;
156
157 if need_flush {
158 yield buffer.take().expect("always have buffer");
159 buffer.replace(String::with_capacity(CHUNK_SIZE));
160 }
161 }
162
163 let Some(mut target) = buffer.take() else {return;};
164 if labels.len() == 1 {
165 target.push_str("}}}");
166 } else {
167 target.push_str("]}");
168 }
169
170 yield target;
171 }
172 .boxed()
173 }
174
175 fn prune(&self) {
176 if !V::needs_pruning() {
177 return;
178 }
179
180 let mut map = self.map.write();
181 map.retain(|_key, entry| entry.resolve().is_some());
182 }
183}
184
185pub struct CounterRegistry<K, V: AtomicCounterEntry = AtomicCounter> {
199 inner: Arc<CounterRegistryInner<K, V>>,
200}
201
202impl<K, V: AtomicCounterEntry> CounterRegistry<K, V> {
203 pub fn metric_type(&self) -> MetricType {
204 self.inner.metric_type
205 }
206}
207
208pub type PruningCounterRegistry<K> = CounterRegistry<K, WeakAtomicCounter>;
209
210#[derive(Serialize, Clone, Copy)]
211pub enum MetricType {
212 Counter,
213 Gauge,
214 Histogram,
215}
216
217impl MetricType {
218 pub fn label(&self) -> &'static str {
219 match self {
220 Self::Counter => "counter",
221 Self::Gauge => "gauge",
222 Self::Histogram => "histogram",
223 }
224 }
225}
226
227#[derive(Serialize, Clone, Copy)]
228pub enum MetricPrune {
229 Pruning,
230 NonPruning,
231}
232
233#[derive(Serialize, Clone)]
234pub struct CounterDescription {
235 pub name: String,
237 pub help: String,
239 pub doc: Option<String>,
241 pub metric_type: MetricType,
243 pub label_names: Vec<String>,
245 pub buckets: Vec<f64>,
247 pub pruning: MetricPrune,
249}
250
251#[linkme::distributed_slice]
253pub static COUNTER_METADATA: [fn() -> CounterDescription];
254
255fn compute_metadata() -> Vec<CounterDescription> {
256 let mut metadata = vec![];
257
258 for func in COUNTER_METADATA.iter() {
259 let desc = (func)();
260 metadata.push(desc);
261 }
262
263 metadata.sort_by(|a, b| a.name.cmp(&b.name));
264 metadata
265}
266
267static METADATA: LazyLock<Vec<CounterDescription>> = LazyLock::new(compute_metadata);
268
269pub fn export_metadata() -> Vec<CounterDescription> {
270 let rt = tokio::runtime::Builder::new_current_thread()
274 .build()
275 .expect("failed to make single thread runtime for export_metadata call");
276 let _guard = rt.enter();
277 METADATA.clone()
278}
279
280#[macro_export]
290macro_rules! mandatory_doc {
291 ($doc:expr) => {
292 $doc
293 };
294 ($($doc:expr)+) => {
295 concat!($($doc, "\n",)+)
297 };
298 () => {
299 compile_error!("doc comments are mandatory")
300 };
301}
302
303pub fn one_line(s: &str) -> String {
305 s.replace("\n", " ").trim().to_string()
306}
307
308pub fn split_help(help: &str) -> (String, Option<String>) {
313 let normalized = help.trim().replace("\n ", "\n");
317
318 match normalized.split_once("\n\n") {
319 Some((a, b)) => (a.to_string(), Some(b.to_string())),
320 None => (normalized, None),
321 }
322}
323
324#[doc(hidden)]
325#[macro_export]
326macro_rules! __histogram_buckets {
327 () => {
328 $crate::prometheus::DEFAULT_BUCKETS.to_vec()
329 };
330 ($buckets:expr) => {
331 $buckets
332 };
333}
334
335#[doc(hidden)]
336#[macro_export]
337macro_rules! __register_metric {
338 (
339 $sym:ident,
340 $name:expr,
341 $($doc:expr)+,
342 $metric:expr,
343 $labels:expr,
344 $pruning:expr
345 ) => {
346 $crate::__register_metric!($sym, $name, $($doc)+, $metric, $labels, $pruning, vec![]);
347 };
348
349 (
350 $sym:ident,
351 $name:expr,
352 $($doc:expr)+,
353 $metric:expr,
354 $labels:expr,
355 $pruning:expr,
356 $buckets:expr
357 ) => {
358 $crate::paste::paste! {
360 #[linkme::distributed_slice($crate::COUNTER_METADATA)]
361 static [<VIVIFY_ $sym>]: fn() -> $crate::CounterDescription = || {
362 ::std::sync::LazyLock::force(&$sym);
363 let (help, doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
364 let labels : &[&str] = $labels;
365 $crate::CounterDescription {
366 name: $name.to_string(),
367 help,
368 doc,
369 metric_type: $metric,
370 label_names: labels.iter().map(|s| s.to_string()).collect(),
371 buckets: $buckets,
372 pruning: $pruning,
373 }
374 };
375 }
376 }
377}
378
379#[macro_export]
403macro_rules! declare_metric {
404 (
405 $(#[doc = $doc:expr])*
406 $vis:vis
407 static $sym:ident:
408 CounterRegistry<$key:ty>(
409 $name:expr $(,)?
410 );
411 ) => {
412 $(#[doc = $doc])*
413 $vis static $sym: ::std::sync::LazyLock<$crate::CounterRegistry<$key>> =
414 ::std::sync::LazyLock::new(
415 || {
416 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
417 let help = $crate::one_line(&help);
418 $crate::CounterRegistry::register($name, help)
419 });
420
421 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
422 <$key as $crate::labels::MetricLabel>::label_names(),
423 $crate::MetricPrune::NonPruning
424 );
425 };
426
427 (
428 $(#[doc = $doc:expr])*
429 $vis:vis
430 static $sym:ident:
431 PruningCounterRegistry<$key:ty>(
432 $name:expr $(,)?
433 );
434 ) => {
435 $(#[doc = $doc])*
436 $vis static $sym: ::std::sync::LazyLock<$crate::PruningCounterRegistry<$key>> =
437 ::std::sync::LazyLock::new(
438 || {
439 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
440 let help = $crate::one_line(&help);
441 $crate::PruningCounterRegistry::register($name, help)
442 });
443
444 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
445 <$key as $crate::labels::MetricLabel>::label_names(),
446 $crate::MetricPrune::Pruning
447 );
448 };
449
450 (
451 $(#[doc = $doc:expr])*
452 $vis:vis
453 static $sym:ident:
454 PruningGaugeRegistry<$key:ty>(
455 $name:expr $(,)?
456 );
457 ) => {
458 $(#[doc = $doc])*
459 $vis static $sym: ::std::sync::LazyLock<$crate::PruningCounterRegistry<$key>> =
460 ::std::sync::LazyLock::new(
461 || {
462 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
463 let help = $crate::one_line(&help);
464 $crate::PruningCounterRegistry::register_gauge($name, help)
465 });
466
467 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Gauge,
468 <$key as $crate::labels::MetricLabel>::label_names(),
469 $crate::MetricPrune::Pruning
470 );
471 };
472
473
474 (
475 $(#[doc = $doc:expr])*
476 $vis:vis
477 static $sym:ident:
478 IntGaugeVec(
479 $name:expr,
480 $labels:expr $(,)*
481 );
482 ) => {
483 $(#[doc = $doc])*
484 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntGaugeVec> =
485 ::std::sync::LazyLock::new(
486 || {
487 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
488 let help = $crate::one_line(&help);
489
490 $crate::prometheus::register_int_gauge_vec!(
491 $name,
492 help,
493 $labels
494 ).unwrap()
495 });
496
497 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Gauge,
498 $labels, $crate::MetricPrune::NonPruning);
499 };
500 (
501 $(#[doc = $doc:expr])*
502 $vis:vis
503 static $sym:ident:
504 IntCounterVec(
505 $name:expr,
506 $labels:expr $(,)*
507 );
508 ) => {
509 $(#[doc = $doc])*
510 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntCounterVec> =
511 ::std::sync::LazyLock::new(
512 || {
513 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
514 let help = $crate::one_line(&help);
515
516 $crate::prometheus::register_int_counter_vec!(
517 $name,
518 help,
519 $labels
520 ).unwrap()
521 });
522
523 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
524 &$labels[..], $crate::MetricPrune::NonPruning);
525 };
526 (
527 $(#[doc = $doc:expr])*
528 $vis:vis
529 static $sym:ident:
530 CounterVec(
531 $name:expr,
532 $labels:expr $(,)*
533 );
534 ) => {
535 $(#[doc = $doc])*
536 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::CounterVec> =
537 ::std::sync::LazyLock::new(
538 || {
539 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
540 let help = $crate::one_line(&help);
541
542 $crate::prometheus::register_counter_vec!(
543 $name,
544 help,
545 $labels
546 ).unwrap()
547 });
548
549 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
550 &$labels[..], $crate::MetricPrune::NonPruning);
551 };
552 (
553 $(#[doc = $doc:expr])*
554 $vis:vis
555 static $sym:ident:
556 HistogramVec(
557 $name:expr,
558 $labels:expr
559 $(, $buckets:expr)?
560 $(,)*
561 );
562 ) => {
563 $(#[doc = $doc])*
564 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::HistogramVec> =
565 ::std::sync::LazyLock::new(
566 || {
567 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
568 let help = $crate::one_line(&help);
569
570 $crate::prometheus::register_histogram_vec!(
571 $name,
572 help,
573 $labels
574 $(,$buckets)?
575 ).unwrap()
576 });
577
578 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Histogram,
579 &$labels[..],
580 $crate::MetricPrune::NonPruning,
581 $crate::__histogram_buckets!($($buckets)?)
582 );
583 };
584
585 (
586 $(#[doc = $doc:expr])*
587 $vis:vis
588 static $sym:ident:
589 Histogram($name:expr $(, $buckets:expr)?);
590 ) => {
591 $(#[doc = $doc])*
592 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::Histogram> =
593 ::std::sync::LazyLock::new(
594 || {
595 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
596 let help = $crate::one_line(&help);
597
598 $crate::prometheus::register_histogram!(
599 $name,
600 help,
601 $($buckets)?
602 ).unwrap()
603 });
604
605 $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Histogram, &[],
606 $crate::MetricPrune::NonPruning,
607 $crate::__histogram_buckets!($($buckets)?)
608 );
609 };
610
611 (
612 $(#[doc = $doc:expr])*
613 $vis:vis
614 static $sym:ident:
615 IntCounter($name:expr);
616 ) => {
617 $(#[doc = $doc])*
618 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntCounter> =
619 ::std::sync::LazyLock::new(
620 || {
621 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
622 let help = $crate::one_line(&help);
623
624 $crate::prometheus::register_int_counter!(
625 $name,
626 help,
627 ).unwrap()
628 });
629
630 $crate::__register_metric!($sym, $name, $($doc)*,
631 $crate::MetricType::Counter, &[], $crate::MetricPrune::NonPruning);
632 };
633
634 (
635 $(#[doc = $doc:expr])*
636 $vis:vis
637 static $sym:ident:
638 IntGauge($name:expr);
639 ) => {
640 $(#[doc = $doc])*
641 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntGauge> =
642 ::std::sync::LazyLock::new(
643 || {
644 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
645 let help = $crate::one_line(&help);
646
647 $crate::prometheus::register_int_gauge!(
648 $name,
649 help,
650 ).unwrap()
651 });
652
653 $crate::__register_metric!($sym, $name, $($doc)*,
654 $crate::MetricType::Gauge, &[], $crate::MetricPrune::NonPruning);
655 };
656 (
657 $(#[doc = $doc:expr])*
658 $vis:vis
659 static $sym:ident:
660 Gauge($name:expr);
661 ) => {
662 $(#[doc = $doc])*
663 $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::Gauge> =
664 ::std::sync::LazyLock::new(
665 || {
666 let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
667 let help = $crate::one_line(&help);
668
669 $crate::prometheus::register_gauge!(
670 $name,
671 help,
672 ).unwrap()
673 });
674
675 $crate::__register_metric!($sym, $name, $($doc)*,
676 $crate::MetricType::Gauge, &[], $crate::MetricPrune::NonPruning);
677 };
678}
679
680impl<K, V: AtomicCounterEntry> Clone for CounterRegistry<K, V> {
681 fn clone(&self) -> Self {
682 Self {
683 inner: Arc::clone(&self.inner),
684 }
685 }
686}
687
688impl<K: Clone + Send + Sync + MetricLabel + 'static, V: AtomicCounterEntry + 'static>
689 CounterRegistry<K, V>
690{
691 pub fn register(name: &'static str, help: String) -> Self {
694 Self::register_impl(name, help, MetricType::Counter)
695 }
696
697 pub fn register_gauge(name: &'static str, help: String) -> Self {
699 Self::register_impl(name, help, MetricType::Gauge)
700 }
701
702 fn register_impl(name: &'static str, help: String, metric_type: MetricType) -> Self {
703 let me = Self {
704 inner: Arc::new(CounterRegistryInner {
705 map: Default::default(),
706 name,
707 help,
708 metric_type,
709 }),
710 };
711
712 crate::registry::Registry::register(me.inner.clone());
713
714 me
715 }
716}
717
718impl<K, V> CounterRegistry<K, V>
719where
720 V: AtomicCounterEntry,
721 K: Eq + Hash + MetricLabel,
722{
723 pub fn get<Q: ?Sized>(&self, key: &Q) -> Option<AtomicCounter>
726 where
727 K: Borrow<Q>,
728 Q: Hash + Eq,
729 {
730 let map = self.inner.map.read();
731 map.get(key).and_then(|weak| weak.resolve())
732 }
733
734 pub fn get_or_create<'a, Q: ?Sized>(&self, key: &'a Q) -> AtomicCounter
737 where
738 K: Borrow<Q> + From<&'a Q>,
739 Q: Hash + Eq,
740 {
741 let map = self.inner.map.upgradable_read();
742 if let Some(weak) = map.get(key) {
743 if let Some(strong) = weak.resolve() {
744 return strong;
745 }
746 }
747
748 let mut map = RwLockUpgradableReadGuard::upgrade(map);
749
750 if let Some(weak) = map.get(key) {
752 if let Some(strong) = weak.resolve() {
753 return strong;
754 }
755 }
756
757 let result = AtomicCounter::new();
758 map.insert(key.into(), V::make_storable(&result));
759
760 result
761 }
762}
763
764#[cfg(test)]
765mod tests {
766 use super::*;
767
768 #[test]
769 fn split_help_single_line() {
770 let (help, doc) = split_help(" A single line of help.");
771 k9::assert_equal!(help, "A single line of help.");
772 k9::assert_equal!(doc, None);
773 }
774
775 #[test]
776 fn split_help_multi_line_first_paragraph() {
777 let (help, doc) = split_help(" First line,\n second line.");
778 k9::assert_equal!(help, "First line,\nsecond line.");
779 k9::assert_equal!(doc, None);
780 k9::assert_equal!(one_line(&help), "First line, second line.");
781 }
782
783 #[test]
784 fn split_help_with_exposition() {
785 let (help, doc) = split_help(
786 " First line,\n second line.\n\n Exposition line one.\n Exposition line two.",
787 );
788 k9::assert_equal!(help, "First line,\nsecond line.");
789 k9::assert_equal!(
790 doc,
791 Some("Exposition line one.\nExposition line two.".to_string())
792 );
793 }
794
795 #[test]
796 fn split_help_preserves_internal_blank_lines_in_doc() {
797 let (help, doc) = split_help(" Help.\n\n Para one.\n\n Para two.");
798 k9::assert_equal!(help, "Help.");
799 k9::assert_equal!(doc, Some("Para one.\n\nPara two.".to_string()));
800 }
801}