Crate prometheus_filtered

Expand description

Drop-in replacement for the prometheus crate with optional per-metric filtering.

Replace use prometheus::* with use prometheus_filtered::* to control which metrics are exposed. The active filter is one directive set, built by merging its inputs in precedence order — the node config’s directives, the METRICS_FILTER environment variable’s, and an optional runtime override: a higher-precedence directive replaces the directive with the same pattern, and otherwise the sets’ directives apply side by side (see Filter).

Filter syntax: comma-separated pattern=LEVEL directives, where LEVEL is one of off, warn, info, debug, trace. A bare LEVEL token (no pattern=) and its reserved default=LEVEL spelling both set the global default: the level for the metrics no other directive matches. The bare spelling additionally makes its source replace the lower-precedence sources’ directives instead of merging over them — METRICS_FILTER=trace exposes everything, whatever the config sets. A pattern matches if it is a prefix of the metric name OR is a component/prefix of the calling module path (e.g. traffic_controller matches iota_core::traffic_controller::metrics). When several directives match the same metric, the most specific one wins regardless of order: a metric-name match over a module match, then the longest pattern; among directives with the same pattern, the last one wins.

Examples:

METRICS_FILTER=off,authority=warn
METRICS_FILTER=authority=off

The directives act as exposure thresholds deciding which metrics Registry::gather includes in its output (off exposes none of the matched metrics). Metrics matched by no directive are exposed unconditionally, so with no filter configured the crate behaves exactly like plain prometheus; use a default=LEVEL directive to set a stricter global default.

Modules§

core: Core traits and types.
proto: Protocol buffers format of metrics. Generated file from proto_model.proto

Macros§

histogram_opts: Create a HistogramOpts.
opts: Create an Opts.
register_counter: register_counter!(name, help) - global prometheus registry, filtered.
register_counter_vec: register_counter_vec!(name, help, labels) - global registry, filtered.
register_counter_vec_with_registry: register_counter_vec_with_registry!(name, help, labels, registry)
register_counter_with_registry: register_counter_with_registry!(name, help, registry)
register_gauge_vec_with_registry: register_gauge_vec_with_registry!(name, help, labels, registry)
register_gauge_with_registry: register_gauge_with_registry!(name, help, registry)
register_histogram_vec: register_histogram_vec!(opts, labels) or (name, help, labels) or (name, help, labels, buckets) — global prometheus registry, filtered.
register_histogram_vec_with_registry: register_histogram_vec_with_registry!(name, help, labels, registry) register_histogram_vec_with_registry!(name, help, labels, buckets, registry)
register_histogram_with_registry: register_histogram_with_registry!(name, help, registry) register_histogram_with_registry!(name, help, buckets, registry)
register_int_counter_vec_with_registry: register_int_counter_vec_with_registry!(name, help, labels, registry)
register_int_counter_with_registry: register_int_counter_with_registry!(name, help, registry)
register_int_gauge_vec_with_registry: register_int_gauge_vec_with_registry!(name, help, labels, registry)
register_int_gauge_with_registry: register_int_gauge_with_registry!(name, help, registry)

Structs§

Filter: Filter holds two directive sets: the immutable startup directives (the node config’s with the METRICS_FILTER env var’s merged over them) and the directives currently in effect — the startup directives, with the runtime override merged over them while one is set.
FilterSource: The source strings for one filter input. directives is parsed for matching; display is what Filter::filter_string and Filter::startup_filter_string echo back (e.g. the group-form string a caller expanded before building the filter). Use FilterSource::new when the two are the same string.
Histogram: A Metric counts individual observations from an event or sample stream in configurable buckets. Similar to a Summary, it also provides a sum of observations and an observation count.
HistogramOpts: A struct that bundles the options for creating a Histogram metric. It is mandatory to set Name and Help to a non-empty string. All other fields are optional and can safely be left at their zero value.
HistogramTimer: Timer to measure and record the duration of an event.
Opts: A struct that bundles the options for creating most Metric types.
ProtobufEncoder: An implementation of an Encoder that converts a MetricFamily proto message into the binary wire format of protobuf.
Registry: Wraps prometheus::Registry with an embedded Filter so that register_*_with_registry! macros can decide whether a metric is exposed.
TextEncoder: An implementation of an Encoder that converts a MetricFamily proto message into text format.

Enums§

Error: The error types for prometheus.
MetricLevel: Verbosity level for a metric.

Constants§

DEFAULT_BUCKETS: The default Histogram buckets. The default buckets are tailored to broadly measure the response time (in seconds) of a network service. Most likely, however, you will be required to define buckets customized to your use case.
METRICS_FILTER_ENV: Environment variable holding filter directives, read by Filter::from_env.
PROTOBUF_FORMAT: The protocol buffer format of metric family.

Traits§

Encoder: An interface for encoding metric families into an underlying wire protocol.

Functions§

default_registry: Returns a reference to the global default Registry, wrapping the underlying prometheus::default_registry(). Metrics registered here appear in the standard prometheus default gather output.
directive_parts: Splits a METRICS_FILTER-style string into its non-empty, trimmed directive segments.
exponential_buckets: Create count buckets, where the lowest bucket has an upper bound of start and each following bucket’s upper bound is factor times the previous bucket’s upper bound. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts.
gather: Return all MetricFamily of DEFAULT_REGISTRY.
linear_buckets: Create count buckets, each width wide, where the lowest bucket has an upper bound of start. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts.
split_directive: Splits one directive into its (pattern, level) parts, rejecting an invalid level with an error describing the offending directive.

Type Aliases§

Counter: A Metric represents a single numerical value that only ever goes up.
CounterVec: A Collector that bundles a set of Counters that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. number of HTTP requests, partitioned by response code and method).
Gauge: A Metric represents a single numerical value that can arbitrarily go up and down.
GaugeVec: A Collector that bundles a set of Gauges that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. number of operations queued, partitioned by user and operation type).
HistogramVec: A Collector that bundles a set of Histograms that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. HTTP request latencies, partitioned by status code and method).
IntCounter: The integer version of Counter. Provides better performance if metric values are all positive integers (natural numbers).
IntCounterVec: The integer version of CounterVec. Provides better performance if metric are all positive integers (natural numbers).
IntGauge: The integer version of Gauge. Provides better performance if metric values are all integers.
IntGaugeVec: The integer version of GaugeVec. Provides better performance if metric values are all integers.
Result: A specialized Result type for prometheus.