Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

prometheus: update docs to highlight requirements around upkeep #537

Merged
merged 2 commits into from
Oct 30, 2024
Merged

prometheus: update docs to highlight requirements around upkeep #537

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
29d36f4
prometheus: update docs to highlight requirements around upkeep
tobz Oct 30, 2024
b0c9e64
update changelog
tobz Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions metrics-exporter-prometheus/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased] - ReleaseDate

### Changed

- Updated the crate-level documentation, and the documentation for `PrometheusBuilder::build_recorder` and
`PrometheusBuilder::install_recorder`, to call out the requirements around running upkeep periodically.
([#537](https://github.com/metrics-rs/metrics/pull/537))

## [0.16.0] - 2024-10-12

### Added
Expand Down
157 changes: 78 additions & 79 deletions metrics-exporter-prometheus/src/exporter/builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,8 @@ impl PrometheusBuilder {
///
/// The HTTP listener that is spawned will respond to GET requests on any request path.
///
/// Running in HTTP listener mode is mutually exclusive with the push gateway i.e. enabling the
/// HTTP listener will disable the push gateway, and vise versa.
/// Running in HTTP listener mode is mutually exclusive with the push gateway i.e. enabling the HTTP listener will
/// disable the push gateway, and vise versa.
///
/// Defaults to enabled, listening at `0.0.0.0:9000`.
///
Expand All @@ -105,15 +105,14 @@ impl PrometheusBuilder {

/// Configures the exporter to push periodic requests to a Prometheus [push gateway].
///
/// Running in push gateway mode is mutually exclusive with the HTTP listener i.e. enabling the
/// push gateway will disable the HTTP listener, and vise versa.
/// Running in push gateway mode is mutually exclusive with the HTTP listener i.e. enabling the push gateway will
/// disable the HTTP listener, and vise versa.
///
/// Defaults to disabled.
///
/// ## Errors
///
/// If the given endpoint cannot be parsed into a valid URI, an error variant will be
/// returned describing the error.
/// If the given endpoint cannot be parsed into a valid URI, an error variant will be returned describing the error.
///
/// [push gateway]: https://prometheus.io/docs/instrumenting/pushing/
#[cfg(feature = "push-gateway")]
Expand All @@ -139,13 +138,13 @@ impl PrometheusBuilder {
Ok(self)
}

/// Configures the exporter to expose an HTTP listener that functions as a [scrape endpoint],
/// listening on a Unix Domain socket at the given path
/// Configures the exporter to expose an HTTP listener that functions as a [scrape endpoint], listening on a Unix
/// Domain socket at the given path
///
/// The HTTP listener that is spawned will respond to GET requests on any request path.
///
/// Running in HTTP listener mode is mutually exclusive with the push gateway i.e. enabling the
/// HTTP listener will disable the push gateway, and vise versa.
/// Running in HTTP listener mode is mutually exclusive with the push gateway i.e. enabling the HTTP listener will
/// disable the push gateway, and vise versa.
///
/// Defaults to disabled.
///
Expand All @@ -162,22 +161,21 @@ impl PrometheusBuilder {

/// Adds an IP address or subnet to the allowlist for the scrape endpoint.
///
/// If a client makes a request to the scrape endpoint and their IP is not present in the
/// allowlist, either directly or within any of the allowed subnets, they will receive a 403
/// Forbidden response.
/// If a client makes a request to the scrape endpoint and their IP is not present in the allowlist, either directly
/// or within any of the allowed subnets, they will receive a 403 Forbidden response.
///
/// Defaults to allowing all IPs.
///
/// ## Security Considerations
///
/// On its own, an IP allowlist is insufficient for access control, if the exporter is running
/// in an environment alongside applications (such as web browsers) that are susceptible to [DNS
/// On its own, an IP allowlist is insufficient for access control, if the exporter is running in an environment
/// alongside applications (such as web browsers) that are susceptible to [DNS
/// rebinding](https://en.wikipedia.org/wiki/DNS_rebinding) attacks.
///
/// ## Errors
///
/// If the given address cannot be parsed into an IP address or subnet, an error variant will be
/// returned describing the error.
/// If the given address cannot be parsed into an IP address or subnet, an error variant will be returned describing
/// the error.
#[cfg(feature = "http-listener")]
#[cfg_attr(docsrs, doc(cfg(feature = "http-listener")))]
pub fn add_allowed_address<A>(mut self, address: A) -> Result<Self, BuildError>
Expand All @@ -195,15 +193,15 @@ impl PrometheusBuilder {

/// Sets the quantiles to use when rendering histograms.
///
/// Quantiles represent a scale of 0 to 1, where percentiles represent a scale of 1 to 100, so
/// a quantile of 0.99 is the 99th percentile, and a quantile of 0.99 is the 99.9th percentile.
/// Quantiles represent a scale of 0 to 1, where percentiles represent a scale of 1 to 100, so a quantile of 0.99 is
/// the 99th percentile, and a quantile of 0.99 is the 99.9th percentile.
///
/// Defaults to a hard-coded set of quantiles: 0.0, 0.5, 0.9, 0.95, 0.99, 0.999, and 1.0. This means
/// that all histograms will be exposed as Prometheus summaries.
/// Defaults to a hard-coded set of quantiles: 0.0, 0.5, 0.9, 0.95, 0.99, 0.999, and 1.0. This means that all
/// histograms will be exposed as Prometheus summaries.
///
/// If buckets are set (via [`set_buckets`][Self::set_buckets] or
/// [`set_buckets_for_metric`][Self::set_buckets_for_metric]) then all histograms will be exposed
/// as summaries instead.
/// [`set_buckets_for_metric`][Self::set_buckets_for_metric]) then all histograms will be exposed as summaries
/// instead.
///
/// ## Errors
///
Expand All @@ -219,17 +217,16 @@ impl PrometheusBuilder {

/// Sets the bucket width when using summaries.
///
/// Summaries are rolling, which means that they are divided into buckets of a fixed duration
/// (width), and older buckets are dropped as they age out. This means data from a period as
/// large as the width will be dropped at a time.
/// Summaries are rolling, which means that they are divided into buckets of a fixed duration (width), and older
/// buckets are dropped as they age out. This means data from a period as large as the width will be dropped at a
/// time.
///
/// The total amount of data kept for a summary is the number of buckets times the bucket width.
/// For example, a bucket count of 3 and a bucket width of 20 seconds would mean that 60 seconds
/// of data is kept at most, with the oldest 20 second chunk of data being dropped as the
/// summary rolls forward.
/// The total amount of data kept for a summary is the number of buckets times the bucket width. For example, a
/// bucket count of 3 and a bucket width of 20 seconds would mean that 60 seconds of data is kept at most, with the
/// oldest 20 second chunk of data being dropped as the summary rolls forward.
///
/// Use more buckets with a smaller width to roll off smaller amounts of data at a time, or
/// fewer buckets with a larger width to roll it off in larger chunks.
/// Use more buckets with a smaller width to roll off smaller amounts of data at a time, or fewer buckets with a
/// larger width to roll it off in larger chunks.
///
/// Defaults to 20 seconds.
///
Expand All @@ -247,17 +244,16 @@ impl PrometheusBuilder {

/// Sets the bucket count when using summaries.
///
/// Summaries are rolling, which means that they are divided into buckets of a fixed duration
/// (width), and older buckets are dropped as they age out. This means data from a period as
/// large as the width will be dropped at a time.
/// Summaries are rolling, which means that they are divided into buckets of a fixed duration (width), and older
/// buckets are dropped as they age out. This means data from a period as large as the width will be dropped at a
/// time.
///
/// The total amount of data kept for a summary is the number of buckets times the bucket width.
/// For example, a bucket count of 3 and a bucket width of 20 seconds would mean that 60 seconds
/// of data is kept at most, with the oldest 20 second chunk of data being dropped as the
/// summary rolls forward.
/// The total amount of data kept for a summary is the number of buckets times the bucket width. For example, a
/// bucket count of 3 and a bucket width of 20 seconds would mean that 60 seconds of data is kept at most, with the
/// oldest 20 second chunk of data being dropped as the summary rolls forward.
///
/// Use more buckets with a smaller width to roll off smaller amounts of data at a time, or
/// fewer buckets with a larger width to roll it off in larger chunks.
/// Use more buckets with a smaller width to roll off smaller amounts of data at a time, or fewer buckets with a
/// larger width to roll it off in larger chunks.
///
/// Defaults to 3.
#[must_use]
Expand All @@ -268,8 +264,8 @@ impl PrometheusBuilder {

/// Sets the buckets to use when rendering histograms.
///
/// Buckets values represent the higher bound of each buckets. If buckets are set, then all
/// histograms will be rendered as true Prometheus histograms, instead of summaries.
/// Buckets values represent the higher bound of each buckets. If buckets are set, then all histograms will be
/// rendered as true Prometheus histograms, instead of summaries.
///
/// ## Errors
///
Expand All @@ -285,16 +281,16 @@ impl PrometheusBuilder {

/// Sets the bucket for a specific pattern.
///
/// The match pattern can be a full match (equality), prefix match, or suffix match. The
/// matchers are applied in that order if two or more matchers would apply to a single metric.
/// That is to say, if a full match and a prefix match applied to a metric, the full match would
/// win, and if a prefix match and a suffix match applied to a metric, the prefix match would win.
/// The match pattern can be a full match (equality), prefix match, or suffix match. The matchers are applied in
/// that order if two or more matchers would apply to a single metric. That is to say, if a full match and a prefix
/// match applied to a metric, the full match would win, and if a prefix match and a suffix match applied to a
/// metric, the prefix match would win.
///
/// Buckets values represent the higher bound of each buckets. If buckets are set, then any
/// histograms that match will be rendered as true Prometheus histograms, instead of summaries.
/// Buckets values represent the higher bound of each buckets. If buckets are set, then any histograms that match
/// will be rendered as true Prometheus histograms, instead of summaries.
///
/// This option changes the observer's output of histogram-type metric into summaries.
/// It only affects matching metrics if [`set_buckets`][Self::set_buckets] was not used.
/// This option changes the observer's output of histogram-type metric into summaries. It only affects matching
/// metrics if [`set_buckets`][Self::set_buckets] was not used.
///
/// ## Errors
///
Expand All @@ -315,18 +311,17 @@ impl PrometheusBuilder {

/// Sets the idle timeout for metrics.
///
/// If a metric hasn't been updated within this timeout, it will be removed from the registry
/// and in turn removed from the normal scrape output until the metric is emitted again. This
/// behavior is driven by requests to generate rendered output, and so metrics will not be
/// removed unless a request has been made recently enough to prune the idle metrics.
/// If a metric hasn't been updated within this timeout, it will be removed from the registry and in turn removed
/// from the normal scrape output until the metric is emitted again. This behavior is driven by requests to
/// generate rendered output, and so metrics will not be removed unless a request has been made recently enough to
/// prune the idle metrics.
///
/// Further, the metric kind "mask" configures which metrics will be considered by the idle
/// timeout. If the kind of a metric being considered for idle timeout is not of a kind
/// represented by the mask, it will not be affected, even if it would have othered been removed
/// for exceeding the idle timeout.
/// Further, the metric kind "mask" configures which metrics will be considered by the idle timeout. If the kind of
/// a metric being considered for idle timeout is not of a kind represented by the mask, it will not be affected,
/// even if it would have otherwise been removed for exceeding the idle timeout.
///
/// Refer to the documentation for [`MetricKindMask`](metrics_util::MetricKindMask) for more
/// information on defining a metric kind mask.
/// Refer to the documentation for [`MetricKindMask`](metrics_util::MetricKindMask) for more information on defining
/// a metric kind mask.
#[must_use]
pub fn idle_timeout(mut self, mask: MetricKindMask, timeout: Option<Duration>) -> Self {
self.idle_timeout = timeout;
Expand All @@ -336,8 +331,8 @@ impl PrometheusBuilder {

/// Sets the upkeep interval.
///
/// The upkeep task handles periodic maintenance operations, such as draining histogram data,
/// to ensure that all recorded data is up-to-date and prevent unbounded memory growth.
/// The upkeep task handles periodic maintenance operations, such as draining histogram data, to ensure that all
/// recorded data is up-to-date and prevent unbounded memory growth.
#[must_use]
pub fn upkeep_timeout(mut self, timeout: Duration) -> Self {
self.upkeep_timeout = timeout;
Expand All @@ -346,9 +341,8 @@ impl PrometheusBuilder {

/// Adds a global label to this exporter.
///
/// Global labels are applied to all metrics. Labels defined on the metric key itself have precedence
/// over any global labels. If this method is called multiple times, the latest value for a given label
/// key will be used.
/// Global labels are applied to all metrics. Labels defined on the metric key itself have precedence over any
/// global labels. If this method is called multiple times, the latest value for a given label key will be used.
#[must_use]
pub fn add_global_label<K, V>(mut self, key: K, value: V) -> Self
where
Expand All @@ -362,14 +356,13 @@ impl PrometheusBuilder {

/// Builds the recorder and exporter and installs them globally.
///
/// When called from within a Tokio runtime, the exporter future is spawned directly
/// into the runtime. Otherwise, a new single-threaded Tokio runtime is created
/// on a background thread, and the exporter is spawned there.
/// When called from within a Tokio runtime, the exporter future is spawned directly into the runtime. Otherwise, a
/// new single-threaded Tokio runtime is created on a background thread, and the exporter is spawned there.
///
/// ## Errors
///
/// If there is an error while either building the recorder and exporter, or installing the
/// recorder and exporter, an error variant will be returned describing the error.
/// If there is an error while either building the recorder and exporter, or installing the recorder and exporter,
/// an error variant will be returned describing the error.
#[cfg(any(feature = "http-listener", feature = "push-gateway"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "http-listener", feature = "push-gateway"))))]
pub fn install(self) -> Result<(), BuildError> {
Expand Down Expand Up @@ -415,10 +408,13 @@ impl PrometheusBuilder {
///
/// The handle can be used to generate valid Prometheus scrape endpoint payloads directly.
///
/// The caller is responsible for ensuring that upkeep is run periodically. See the **Upkeep and maintenance**
/// section in the top-level crate documentation for more information.
///
/// ## Errors
///
/// If there is an error while building the recorder, or installing the recorder, an error
/// variant will be returned describing the error.
/// If there is an error while building the recorder, or installing the recorder, an error variant will be returned
/// describing the error.
pub fn install_recorder(self) -> Result<PrometheusHandle, BuildError> {
let recorder = self.build_recorder();
let handle = recorder.handle();
Expand All @@ -430,19 +426,19 @@ impl PrometheusBuilder {

/// Builds the recorder and exporter and returns them both.
///
/// In most cases, users should prefer to use [`install`][PrometheusBuilder::install] to create
/// and install the recorder and exporter automatically for them. If a caller is combining
/// recorders, or needs to schedule the exporter to run in a particular way, this method, or
/// [`build_recorder`][PrometheusBuilder::build_recorder], provide the flexibility to do so.
/// In most cases, users should prefer to use [`install`][PrometheusBuilder::install] to create and install the
/// recorder and exporter automatically for them. If a caller is combining recorders, or needs to schedule the
/// exporter to run in a particular way, this method, or [`build_recorder`][PrometheusBuilder::build_recorder],
/// provide the flexibility to do so.
///
/// ## Panics
///
/// This method must be called from within an existing Tokio runtime or it will panic.
///
/// ## Errors
///
/// If there is an error while building the recorder and exporter, an error variant will be
/// returned describing the error.
/// If there is an error while building the recorder and exporter, an error variant will be returned describing the
/// error.
#[warn(clippy::too_many_lines)]
#[cfg(any(feature = "http-listener", feature = "push-gateway"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "http-listener", feature = "push-gateway"))))]
Expand Down Expand Up @@ -495,6 +491,9 @@ impl PrometheusBuilder {
}

/// Builds the recorder and returns it.
///
/// The caller is responsible for ensuring that upkeep is run periodically. See the **Upkeep and maintenance**
/// section in the top-level crate documentation for more information.
pub fn build_recorder(self) -> PrometheusRecorder {
self.build_with_clock(Clock::new())
}
Expand Down
Loading
Loading