Update docs

autometrics/README.md

@@ -49,7 +49,7 @@ pub async fn main() {
 - [🚨 Define alerts](https://docs.rs/autometrics/latest/autometrics/objectives/index.html) using SLO best practices directly in your source code
 - [📊 Grafana dashboards](https://github.com/autometrics-dev#5-configuring-prometheus) work out of the box to visualize the performance of instrumented functions & SLOs
 - [⚙️ Configurable](#metrics-libraries) metric collection library ([`opentelemetry`](https://crates.io/crates/opentelemetry), [`prometheus`](https://crates.io/crates/prometheus), [`prometheus-client`](https://crates.io/crates/prometheus-client) or [`metrics`](https://crates.io/crates/metrics))
-- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with distributed traces
+- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with traces
 - ⚡ Minimal runtime overhead
 
 See [Why Autometrics?](https://github.com/autometrics-dev#4-why-autometrics) for more details on the ideas behind autometrics.
@@ -106,11 +106,10 @@ fn main() {
 ### Feature flags
 
 - `prometheus-exporter` - exports a Prometheus metrics collector and exporter (compatible with any of the Metrics Libraries)
-- `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 due to lack of support in the other metrics libraries. 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)).
 
-#### Metrics Libraries
+#### Metrics libraries
 
 **Required:** Configure the crate that autometrics will use to produce metrics by using one of the following feature flags:
 
@@ -122,3 +121,10 @@ fn main() {
 - `metrics` - use the [metrics](https://crates.io/crates/metrics) crate for producing metrics
 - `prometheus` - use the [prometheus](https://crates.io/crates/prometheus) crate for producing metrics
 - `prometheus-client` - use the official [prometheus-client](https://crates.io/crates/prometheus-client) crate for producing metrics
+
+#### Exemplars (for integrating metrics with traces)
+
+See the crate docs for [exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) for details about these features.
+
+- `exemplars-tracing` - extract arbitrary fields from `tracing::Span`s
+- `exemplars-tracing-opentelemetry` - extract the `trace_id` and `span_id` from the `opentelemetry::Context`, which is attached to `tracing::Span`s by the `tracing-opentelemetry` crate

autometrics/src/exemplars/mod.rs

@@ -5,24 +5,70 @@
 //! to change by looking at individual examples that contributed to the metrics.
 //!
 //! Autometrics integrates with tracing libraries to extract details from the
-//! current span context and attach them as exemplars to the metrics it generates.
+//! current span context and automatically attach them as exemplars to the generated metrics.
 //!
-//! See each of the submodules for details on how to integrate with each tracing library.
-//!
-//! # Supported Metrics Libraries
+//! # Supported metrics libraries
 //!
 //! Exemplars are currently only supported with the `prometheus-client` metrics library,
 //! because that is the only one that currently supports producing metrics with exemplars.
 //!
-//! # Exposing Metrics to Prometheus with Exemplars
+//! # Exposing metrics to Prometheus with exemplars
 //!
 //! To enable Prometheus to scrape metrics with exemplars you must:
 //! 1. Run Prometheus with the [`--enable-feature=exemplar-storage`](https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage) flag
-//! 2. Export the metrics to Prometheus using [`prometheus_exporter::encode_http_response`] or
-//!   make sure to manually set the `Content-Type` header to indicate it is using the the OpenMetrics format:
+//! 2. Export the metrics to Prometheus using the provided [`prometheus_exporter::encode_http_response`] or
+//!   make sure to manually set the `Content-Type` header to indicate it is using the the OpenMetrics format,
+//!   rather than the default Prometheus format:
 //!   ```http
 //!   Content-Type: application/openmetrics-text; version=1.0.0; charset=utf-8
 //!   ```
+//!
+//! [`prometheus_exporter::encode_http_response`]: crate::prometheus_exporter::encode_http_response
+//!
+//! # Tracing libraries
+//!
+//! ## [`tracing`](https://crates.io/crates/tracing)
+//!
+//! See the [`tracing` submodule docs](tracing).
+//!
+//! ## [`tracing-opentelemetry`](https://crates.io/crates/tracing-opentelemetry)
+//!
+//! Extract exemplars from the OpenTelemetry Context attached to the current tracing Span.
+//!
+//! This works in the following way:
+//! 1. Add the [`tracing_opentelemetry::OpenTelemetryLayer`] to your tracing subscriber
+//! 2. That layer ensures that there is an [`opentelemetry::Context`] attached to every [`tracing::Span`]
+//! 3. Spans can be manually created or created for every function using the [`tracing::instrument`] macro
+//! 4. Autometrics extracts the `trace_id` and `span_id` from the `Context` and attaches them as exemplars to the generated metrics
+//!
+//! ### Example
+//!
+//! ```rust
+//! # use autometrics::autometrics;
+//! use tracing_subscriber::prelude::*;
+//! use tracing_opentelemetry::OpenTelemetryLayer;
+//!
+//! let tracer = opentelemetry_sdk::export::trace::stdout::new_pipeline().install_simple();
+//! let otel_layer = OpenTelemetryLayer::new(tracer);
+//!
+//! // Create a tracing subscriber with the OpenTelemetry layer
+//! tracing_subscriber::fmt()
+//!   .finish()
+//!   .with(otel_layer)
+//!   .init();
+//!
+//! #[autometrics]
+//! #[tracing::instrument]
+//! async fn my_function() {
+//!   // This function produces metrics with exemplars
+//!   // that contain a trace_id and span_id
+//! }
+//! ```
+//!
+//! [`tracing_opentelemetry::OpenTelemetryLayer`]: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/struct.OpenTelemetryLayer.html
+//! [`opentelemetry::Context`]: https://docs.rs/opentelemetry/latest/opentelemetry/struct.Context.html
+//! [`tracing::Span`]: https://docs.rs/tracing/latest/tracing/struct.Span.html
+//! [`tracing::instrument`]: https://docs.rs/tracing/latest/tracing/attr.instrument.html
 
 use std::collections::HashMap;
 
@@ -32,6 +78,7 @@ pub mod tracing;
 mod tracing_opentelemetry;
 
 #[cfg(all(
+    not(doc),
     feature = "exemplars-tracing-opentelemetry",
     feature = "exemplars-tracing"
 ))]

autometrics/src/lib.rs

@@ -191,6 +191,7 @@ pub use autometrics_macros::ResultLabels;
     since = "0.5.0",
     note = "Use autometrics::prometheus_exporter::encode_to_string instead. This will be removed in v0.6"
 )]
+/// Replaced by [`prometheus_exporter::encode_to_string`]
 pub fn encode_global_metrics() -> Result<String, prometheus_exporter::EncodingError> {
     prometheus_exporter::encode_to_string()
 }
@@ -199,6 +200,7 @@ pub fn encode_global_metrics() -> Result<String, prometheus_exporter::EncodingEr
     since = "0.5.0",
     note = "Use autometrics::prometheus_exporter::init instead. This will be removed in v0.6"
 )]
+/// Replaced by [`prometheus_exporter::init`]
 pub fn global_metrics_exporter() -> prometheus_exporter::GlobalPrometheus {
     prometheus_exporter::init();
     prometheus_exporter::GLOBAL_EXPORTER.clone()

autometrics/src/prometheus_exporter.rs

@@ -1,4 +1,4 @@
-//! Helper functions for easily collecting and exporting metrics to Prometheus.
+//! Helper functions for easily collecting and exporting metrics to Prometheus
 //!
 //! You do not need this module if you are already collecting custom metrics and exporting them to Prometheus.
 //!