Package org.forgerock.monitoring.api.instrument.config

Interface MeterFilter

public interface MeterFilter
As requests are made of a MeterRegistry 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. ForgeRock changes: - Removed @incubating annotations

  • Method Details

    • commonTags

      static MeterFilter commonTags(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(String meterNamePrefix, String fromTagKey, 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(String... tagKeys)
      Suppress tags with a given tag key.
      Parameters:
      tagKeys - Keys of tags that should be suppressed.
      Returns:
      A tag-suppressing filter.

    • replaceTagValues

      static MeterFilter replaceTagValues(String tagKey, Function<String,String> replacement, 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 made
      replacement - The value to replace with
      exceptions - All a matching tag with this value to retain its original value

    • accept

      static MeterFilter accept(Predicate<Meter.Id> iff)
      When the given predicate is true, 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(Predicate<Meter.Id> iff)
      When the given predicate is true, the meter should NOT be present in published metrics.
      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 like maximumAllowableTags(java.lang.String, java.lang.String, int, org.forgerock.monitoring.api.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 like maximumAllowableTags(java.lang.String, java.lang.String, int, org.forgerock.monitoring.api.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-cardiality metric costing too much.

      Parameters:
      maximumTimeSeries - The total number of unique name/tag permutations allowed before filtering kicks in.

    • maximumAllowableTags

      static MeterFilter maximumAllowableTags(String meterNamePrefix, 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(String prefix)
      Meters that start with the provided name 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.

    • accept

      default MeterFilterReply accept(Meter.Id id)
      Parameters:
      id - Id with map(org.forgerock.monitoring.api.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)
      Returns:
      Transformations to any part of the id.

    • configure

      @Nullable default HistogramConfig configure(Meter.Id id, HistogramConfig config)
      This is only called when filtering new timers and distribution summaries (i.e. those meter types that use HistogramConfig).
      Parameters:
      id - Id with map(org.forgerock.monitoring.api.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.