Move example onto the Exemplar docs

Signed-off-by: Adam Chalmers <[email protected]>

Author: adamchalmers

Cargo.toml

@@ -38,9 +38,6 @@ actix-web = "4"
 [build-dependencies]
 prost-build = { version = "0.9.0", optional = true }
 
-[[example]]
-name = "families-exemplars"
-
 [[bench]]
 name = "family"
 harness = false

examples/families-exemplars.rs

@@ -32,6 +32,36 @@ pub struct Exemplar<S, V> {
 /// counter_with_exemplar.inc_by(1, Some(vec![("user_id".to_string(), "42".to_string())]));
 /// let _value: (u64, _) = counter_with_exemplar.get();
 /// ```
+/// You can also use exemplars with families. Just wrap the exemplar in a Family.
+/// ```
+/// # use prometheus_client::metrics::exemplar::CounterWithExemplar;
+/// # use prometheus_client::metrics::histogram::exponential_buckets;
+/// # use prometheus_client::metrics::family::Family;
+/// # use prometheus_client_derive_encode::Encode;
+/// #[derive(Clone, Hash, PartialEq, Eq, Encode, Debug, Default)]
+/// pub struct ResultLabel {
+///     pub result: String,
+/// }
+///
+/// #[derive(Clone, Hash, PartialEq, Eq, Encode, Debug, Default)]
+/// pub struct TraceLabel {
+///     pub trace_id: String,
+/// }
+///
+/// let latency: Family<ResultLabel, CounterWithExemplar<TraceLabel>> =
+///     Family::default();
+///
+/// latency
+/// .get_or_create(&ResultLabel {
+///     result: "success".to_owned(),
+/// })
+/// .inc_by(
+///     1,
+///     Some(TraceLabel {
+///         trace_id: "3a2f90c9f80b894f".to_owned(),
+///     }),
+/// );
+/// ```
 #[cfg(not(any(target_arch = "mips", target_arch = "powerpc")))]
 #[derive(Debug)]
 pub struct CounterWithExemplar<S, N = u64, A = AtomicU64> {
@@ -127,6 +157,38 @@ impl<S, N: Clone, A: counter::Atomic<N>> CounterWithExemplar<S, N, A> {
 /// let histogram = HistogramWithExemplars::new(exponential_buckets(1.0, 2.0, 10));
 /// histogram.observe(4.2, Some(vec![("user_id".to_string(), "42".to_string())]));
 /// ```
+/// You can also use exemplars with families. Just wrap the exemplar in a Family.
+/// ```
+/// # use prometheus_client::metrics::exemplar::HistogramWithExemplars;
+/// # use prometheus_client::metrics::histogram::exponential_buckets;
+/// # use prometheus_client::metrics::family::Family;
+/// # use prometheus_client_derive_encode::Encode;
+/// #[derive(Clone, Hash, PartialEq, Eq, Encode, Debug, Default)]
+/// pub struct ResultLabel {
+///     pub result: String,
+/// }
+///
+/// #[derive(Clone, Hash, PartialEq, Eq, Encode, Debug, Default)]
+/// pub struct TraceLabel {
+///     pub trace_id: String,
+/// }
+///
+/// let latency: Family<ResultLabel, HistogramWithExemplars<TraceLabel>> =
+///     Family::new_with_constructor(|| {
+///         HistogramWithExemplars::new(exponential_buckets(1.0, 2.0, 10))
+///     });
+///
+/// latency
+/// .get_or_create(&ResultLabel {
+///     result: "success".to_owned(),
+/// })
+/// .observe(
+///     0.001345422,
+///     Some(TraceLabel {
+///         trace_id: "3a2f90c9f80b894f".to_owned(),
+///     }),
+/// );
+/// ```
 #[derive(Debug)]
 pub struct HistogramWithExemplars<S> {
     // TODO: Not ideal, as Histogram has a Mutex as well.