Fix docs

autometrics/Cargo.toml

@@ -51,7 +51,7 @@ prometheus-client = { version = "0.21.1", optional = true }
 
 # Used for exemplars-tracing feature
 tracing = { version = "0.1", optional = true }
-tracing-subscriber = { version = "0.3", default-features = false, optional = true }
+tracing-subscriber = { version = "0.3", default-features = false, features = ["registry"], optional = true }
 
 [dev-dependencies]
 axum = { version = "0.6", features = ["tokio"] }

autometrics/README.md

@@ -110,7 +110,7 @@ fn main() {
 ### Feature flags
 
 - `prometheus-exporter` - exports a Prometheus metrics collector and exporter (compatible with any of the Metrics Libraries)
-- `exemplars-tracing` - extract the `trace_id` field from [`tracing::Span`](https://docs.rs/tracing/latest/tracing/struct.Span.html)s and attach it as an [exemplar](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/) for the metrics produced by Autometrics. This is currently only supported with the `prometheus-client` feature, because only that crate has support for exemplars. Note that Prometheus must be specifically [configured](https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage) to use the experimental exemplars feature.
+- `exemplars-tracing` - extract fields from [`tracing::Span`](https://docs.rs/tracing/latest/tracing/struct.Span.html)s and attach them as [exemplars](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/) for the metrics produced by Autometrics. This is currently only supported with the `prometheus-client` feature, because only that crate has support for exemplars. Note that Prometheus must be specifically [configured](https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage) to enable the exemplars feature.
 - `custom-objective-latency` - by default, Autometrics only supports a fixed set of latency thresholds for objectives. Enable this to use custom latency thresholds. Note, however, that the custom latency **must** match one of the buckets configured for your histogram or the alerts will not work. This is not currently compatible with the `prometheus` or `prometheus-exporter` feature.
 - `custom-objective-percentile` by default, Autometrics only supports a fixed set of objective percentiles. Enable this to use a custom percentile. Note, however, that using custom percentiles requires generating a different recording and alerting rules file using the CLI + Sloth (see [here](https://github.com/autometrics-dev/autometrics-rs/tree/main/autometrics-cli)).
 

autometrics/src/integrations/mod.rs

@@ -1,3 +1,8 @@
+//! Functionality that is specific to an optional dependency
+
+/// Access the [`Registry`] used to collect metrics when the `prometheus-client` feature is enabled
+///
+/// [`Registry`]: ::prometheus_client::registry::Registry
 #[cfg(feature = "prometheus-client")]
 pub mod prometheus_client {
     pub use crate::tracker::prometheus_client::REGISTRY;

autometrics/src/integrations/tracing.rs

@@ -1,19 +1,22 @@
-//! Tracing integration for autometrics
+//! Extract fields from [`tracing::Span`]s as exemplars.
+//!
+//! This module enables autometrics to use fields such as `trace_id` from the current [`Span`] as exemplars.
 //!
-//! This module enables autometrics to use the `trace_id` field from the current span as an exemplar.
 //! Exemplars are a newer Prometheus / OpenMetrics / OpenTelemetry feature that allows you to associate
-//! specific traces with a given metric. This enables you to dig into the specifics that produced
-//! a certain metric by looking at a detailed example.
+//! specific traces or samples with a given metric. This enables you to investigate what caused metrics
+//! to change by looking at individual examples that contributed to the metrics.
 //!
 //! # Example
+//!
 //! ```rust
-//! use autometrics::{autometrics, integrations::tracing::AutometricsExemplarExtractor};
+//! use autometrics::autometrics;
+//! use autometrics::integrations::tracing::AutometricsExemplarExtractor:
 //! use tracing::{instrument, trace};
 //! use tracing_subscriber::prelude::*;
 //! use uuid::Uuid;
 //!
 //! #[autometrics]
-//! #[instrument(fields(trace_id = %Uuid::new_v4())]
+//! #[instrument(fields(trace_id = %Uuid::new_v4()))]
 //! fn my_function() {
 //!     trace!("Hello world!");
 //! }
@@ -25,6 +28,8 @@
 //!         .init();
 //! }
 //! ```
+//!
+//! [`Span`]: tracing::Span
 
 use std::collections::HashMap;
 use tracing::field::{Field, Visit};
@@ -49,7 +54,7 @@ pub(crate) fn get_exemplar() -> Option<TraceLabels> {
     .flatten()
 }
 
-/// A tracing [`Layer`] that enables autometrics to use fields from the current span as exemplars for
+/// A [`tracing_subscriber::Layer`] that enables autometrics to use fields from the current span as exemplars for
 /// the metrics it produces.
 ///
 /// By default, it will look for a field called `trace_id` in the current span scope and use that
@@ -75,12 +80,16 @@ pub struct AutometricsExemplarExtractor {
 impl AutometricsExemplarExtractor {
     /// Create a new [`AutometricsExemplarExtractor`] that will extract the given field from the current [`Span`] scope
     /// to use as the labels for the exemplars.
+    ///
+    /// [`Span`]: tracing::Span
     pub const fn from_field(field: &'static str) -> Self {
         Self { fields: &[field] }
     }
 
     /// Create a new [`AutometricsExemplarExtractor`] that will extract the given fields from the current [`Span`] scope
     /// to use as the labels for the exemplars.
+    ///
+    /// [`Span`]: tracing::Span
     pub const fn from_fields(fields: &'static [&'static str]) -> Self {
         Self { fields }
     }

autometrics/src/lib.rs

@@ -6,7 +6,6 @@
 #![doc = include_str!("../README.md")]
 
 mod constants;
-/// Functionality specific to the libraries used to collect metrics
 pub mod integrations;
 mod labels;
 pub mod objectives;

autometrics/src/tracker/mod.rs

@@ -18,20 +18,23 @@ pub use self::prometheus::PrometheusTracker;
 #[cfg(feature = "prometheus-client")]
 pub use self::prometheus_client::PrometheusClientTracker;
 
-#[cfg(any(
-    all(
-        feature = "metrics",
-        any(
+#[cfg(all(
+    not(doc),
+    any(
+        all(
+            feature = "metrics",
+            any(
+                feature = "opentelemetry",
+                feature = "prometheus",
+                feature = "prometheus-client"
+            )
+        ),
+        all(
             feature = "opentelemetry",
-            feature = "prometheus",
-            feature = "prometheus-client"
-        )
-    ),
-    all(
-        feature = "opentelemetry",
-        any(feature = "prometheus", feature = "prometheus-client")
-    ),
-    all(feature = "prometheus", feature = "prometheus-client")
+            any(feature = "prometheus", feature = "prometheus-client")
+        ),
+        all(feature = "prometheus", feature = "prometheus-client")
+    )
 ))]
 compile_error!("Only one of the metrics, opentelemetry, prometheus, or prometheus-client features can be enabled at a time");