Interface MeterFilter
-
public interface MeterFilter
As requests are made of aMeterRegistry
to create new metrics, allow for filtering out the metric altogether, transforming its ID (name or tags) in some way, and transforming its configuration.All new metrics should pass through each
MeterFilter
in the order in which they were added.
-
-
Method Summary
All Methods Static Methods Instance Methods Default Methods Modifier and Type Method Description static MeterFilter
accept()
Include a meter in published metrics.default MeterFilterReply
accept(Meter.Id id)
static MeterFilter
accept(java.util.function.Predicate<Meter.Id> iff)
When the given predicate istrue
, the meter should be present in published metrics.static MeterFilter
acceptNameStartsWith(java.lang.String prefix)
Meters that start with the provided name should be present in published metrics.static MeterFilter
commonTags(java.lang.Iterable<Tag> tags)
Add common tags that are applied to every meter created afterward.default DistributionStatisticConfig
configure(Meter.Id id, DistributionStatisticConfig config)
This is only called when filtering new timers and distribution summaries (i.e.static MeterFilter
deny()
Reject a meter in published metrics.static MeterFilter
deny(java.util.function.Predicate<Meter.Id> iff)
When the given predicate istrue
, the meter should NOT be present in published metrics.static MeterFilter
denyNameStartsWith(java.lang.String prefix)
Meters that start with the provided name prefix should NOT be present in published metrics.static MeterFilter
denyUnless(java.util.function.Predicate<Meter.Id> iff)
Can be used to build a whitelist of metrics matching certain criteria.static MeterFilter
ignoreTags(java.lang.String... tagKeys)
Suppress tags with given tag keys.default Meter.Id
map(Meter.Id id)
static MeterFilter
maxExpected(java.lang.String prefix, long max)
Set a maximum expected value on anyDistributionSummary
whose name begins with the given prefix.static MeterFilter
maxExpected(java.lang.String prefix, java.time.Duration max)
Set a maximum expected value on anyTimer
whose name begins with the given prefix.static MeterFilter
maximumAllowableMetrics(int maximumTimeSeries)
Useful for cost-control in monitoring systems which charge directly or indirectly by the total number of time series you generate.static MeterFilter
maximumAllowableTags(java.lang.String meterNamePrefix, java.lang.String tagKey, int maximumTagValues, MeterFilter onMaxReached)
Places an upper bound on the number of tags produced by matching metrics.static MeterFilter
minExpected(java.lang.String prefix, long min)
Set a minimum expected value on anyDistributionSummary
whose name begins with the given prefix.static MeterFilter
minExpected(java.lang.String prefix, java.time.Duration min)
Set a minimum expected value on anyTimer
whose name begins with the given prefix.static MeterFilter
renameTag(java.lang.String meterNamePrefix, java.lang.String fromTagKey, java.lang.String toTagKey)
Rename a tag key for every metric beginning with a given prefix.static MeterFilter
replaceTagValues(java.lang.String tagKey, java.util.function.Function<java.lang.String,java.lang.String> replacement, java.lang.String... exceptions)
Replace tag values according to the provided mapping for all matching tag keys.
-
-
-
Method Detail
-
commonTags
static MeterFilter commonTags(java.lang.Iterable<Tag> tags)
Add common tags that are applied to every meter created afterward.- Parameters:
tags
- Common tags.- Returns:
- A common tag filter.
-
renameTag
static MeterFilter renameTag(java.lang.String meterNamePrefix, java.lang.String fromTagKey, java.lang.String toTagKey)
Rename a tag key for every metric beginning with a given prefix.- Parameters:
meterNamePrefix
- Apply filter to metrics that begin with this name.fromTagKey
- Rename tags matching this key.toTagKey
- Rename to this key.- Returns:
- A tag-renaming filter.
-
ignoreTags
static MeterFilter ignoreTags(java.lang.String... tagKeys)
Suppress tags with given tag keys.- Parameters:
tagKeys
- Keys of tags that should be suppressed.- Returns:
- A tag-suppressing filter.
-
replaceTagValues
static MeterFilter replaceTagValues(java.lang.String tagKey, java.util.function.Function<java.lang.String,java.lang.String> replacement, java.lang.String... exceptions)
Replace tag values according to the provided mapping for all matching tag keys. This can be used to reduce the total cardinality of a tag by mapping some portion of tag values to something else.- Parameters:
tagKey
- The tag key for which replacements should be madereplacement
- The value to replace withexceptions
- All matching tags with this value to retain its original value- Returns:
- A filter that replaces tag values.
-
denyUnless
static MeterFilter denyUnless(java.util.function.Predicate<Meter.Id> iff)
Can be used to build a whitelist of metrics matching certain criteria. Opposite ofdeny(Predicate)
.- Parameters:
iff
- When a meter id matches, allow its inclusion, otherwise deny.- Returns:
- A meter filter that whitelists metrics matching a predicate.
-
accept
static MeterFilter accept(java.util.function.Predicate<Meter.Id> iff)
When the given predicate istrue
, the meter should be present in published metrics.- Parameters:
iff
- When a meter id matches, guarantee its inclusion in published metrics.- Returns:
- A filter that guarantees the inclusion of matching meters.
-
deny
static MeterFilter deny(java.util.function.Predicate<Meter.Id> iff)
When the given predicate istrue
, the meter should NOT be present in published metrics. Opposite ofdenyUnless(Predicate)
.- Parameters:
iff
- When a meter id matches, guarantee its exclusion in published metrics.- Returns:
- A filter that guarantees the exclusion of matching meters.
-
accept
static MeterFilter accept()
Include a meter in published metrics. Can be used as a subordinate action on another filter likemaximumAllowableTags(java.lang.String, java.lang.String, int, io.micrometer.core.instrument.config.MeterFilter)
.- Returns:
- A filter that guarantees the inclusion of all meters.
-
deny
static MeterFilter deny()
Reject a meter in published metrics. Can be used as a subordinate action on another filter likemaximumAllowableTags(java.lang.String, java.lang.String, int, io.micrometer.core.instrument.config.MeterFilter)
.- Returns:
- A filter that guarantees the exclusion of all meters.
-
maximumAllowableMetrics
static MeterFilter maximumAllowableMetrics(int maximumTimeSeries)
Useful for cost-control in monitoring systems which charge directly or indirectly by the total number of time series you generate.While this filter doesn't discriminate between your most critical and less useful metrics in deciding what to drop (all the metrics you intend to use should fit below this threshold), it can effectively cap your risk of an accidentally high-cardinality metric costing too much.
- Parameters:
maximumTimeSeries
- The total number of unique name/tag permutations allowed before filtering kicks in.- Returns:
- A filter that globally limits the number of unique name and tag combinations.
-
maximumAllowableTags
static MeterFilter maximumAllowableTags(java.lang.String meterNamePrefix, java.lang.String tagKey, int maximumTagValues, MeterFilter onMaxReached)
Places an upper bound on the number of tags produced by matching metrics.- Parameters:
meterNamePrefix
- Apply filter to metrics that begin with this name.tagKey
- The tag to place an upper bound on.maximumTagValues
- The total number of tag values that are allowable.onMaxReached
- After the maximum number of tag values have been seen, apply this filter.- Returns:
- A meter filter that limits the number of tags produced by matching metrics.
-
denyNameStartsWith
static MeterFilter denyNameStartsWith(java.lang.String prefix)
Meters that start with the provided name prefix should NOT be present in published metrics.- Parameters:
prefix
- When a meter name starts with the prefix, guarantee its exclusion in published metrics.- Returns:
- A filter that guarantees the exclusion of matching meters.
-
acceptNameStartsWith
static MeterFilter acceptNameStartsWith(java.lang.String prefix)
Meters that start with the provided name should be present in published metrics.- Parameters:
prefix
- When a meter name starts with the prefix, guarantee its inclusion in published metrics.- Returns:
- A filter that guarantees the inclusion of matching meters.
- Since:
- 1.2.0
-
maxExpected
static MeterFilter maxExpected(java.lang.String prefix, java.time.Duration max)
Set a maximum expected value on anyTimer
whose name begins with the given prefix.- Parameters:
prefix
- Apply the maximum only to timers whose name begins with this prefix.max
- The maximum expected value of the timer.- Returns:
- A filter that applies a maximum expected value to a timer.
-
maxExpected
static MeterFilter maxExpected(java.lang.String prefix, long max)
Set a maximum expected value on anyDistributionSummary
whose name begins with the given prefix.- Parameters:
prefix
- Apply the maximum only to distribution summaries whose name begins with this prefix.max
- The maximum expected value of the distribution summary.- Returns:
- A filter that applies a maximum expected value to a distribution summary.
-
minExpected
static MeterFilter minExpected(java.lang.String prefix, java.time.Duration min)
Set a minimum expected value on anyTimer
whose name begins with the given prefix.- Parameters:
prefix
- Apply the minimum only to timers whose name begins with this prefix.min
- The minimum expected value of the timer.- Returns:
- A filter that applies a minimum expected value to a timer.
-
minExpected
static MeterFilter minExpected(java.lang.String prefix, long min)
Set a minimum expected value on anyDistributionSummary
whose name begins with the given prefix.- Parameters:
prefix
- Apply the minimum only to distribution summaries whose name begins with this prefix.min
- The minimum expected value of the distribution summary.- Returns:
- A filter that applies a minimum expected value to a distribution summary.
-
accept
default MeterFilterReply accept(Meter.Id id)
- Parameters:
id
- Id withmap(io.micrometer.core.instrument.Meter.Id)
transformations applied.- Returns:
- After all transformations, should a real meter be registered for this id, or should it be no-op'd.
-
map
default Meter.Id map(Meter.Id id)
- Parameters:
id
- Id to transform.- Returns:
- Transformations to any part of the id.
-
configure
@Nullable default DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config)
This is only called when filtering new timers and distribution summaries (i.e. those meter types that useDistributionStatisticConfig
).- Parameters:
id
- Id withmap(io.micrometer.core.instrument.Meter.Id)
transformations applied.config
- A histogram configuration guaranteed to be non-null.- Returns:
- Overrides to any part of the histogram config, when applicable.
-
-