Package org.microproxy.stats

Class StatsRegistry

java.lang.Object
org.microproxy.stats.StatsRegistry
public final class StatsRegistry extends Object
The proxy's metrics, by Envoy's flat stat names (http.<prefix>.downstream_rq_total, cluster.<name>.upstream_cx_connect_ms, ...), each with the tags its name carries (TagExtractor), for StatsFormatter and StatsdSink to show.

Metrics are made once and then kept: the proxy resolves its own when it starts, per listener, per cluster and per connection, and keeps them in fields, so counting a request is an add to a LongAdder, never a lookup by name. Registering a name again returns the metric already there (of the same kind, or an IllegalArgumentException is thrown). Nothing here takes a lock of its own.

NOOP is the registry of a proxy without metrics (the default): its metrics do nothing and it keeps none, so the proxy counts unconditionally at no cost. Enable metrics with HttpProxyServerBootstrap.withMetrics(boolean), or with a registry of your own, HttpProxyServerBootstrap.withStats(StatsRegistry).

The registry also bounds how many metrics the proxy makes for things whose number is not fixed: the clusters requests go to (StatsRegistry.Builder.maxClusters, StatsRegistry.Builder.clusterOverflow, StatsRegistry.Builder.perHostClusters) and the stats scripts make (StatsRegistry.Builder.maxScriptStats).

  • Field Details

    • NOOP

      public static final StatsRegistry NOOP
      A registry whose metrics do nothing and that keeps none; the default of every proxy.

    • OTHER_CLUSTER

      public static final String OTHER_CLUSTER
      The name of the cluster that clusters over StatsRegistry.Builder.maxClusters share.
      See Also:

  • Method Details

    • create

      public static StatsRegistry create()
      Returns a registry with the default settings.
      Returns:
      a registry with the default settings

    • builder

      public static StatsRegistry.Builder builder()
      Returns a builder with the default settings.
      Returns:
      a builder with the default settings

    • enabled

      public boolean enabled()
      Returns whether this registry keeps metrics; false only for NOOP.
      Returns:
      whether this registry keeps metrics; false only for NOOP

    • prefix

      public String prefix()
      Returns the prefix of exported names, without separator: envoy by default, as in envoy_cluster_upstream_rq_total (Prometheus) and envoy.cluster.direct... (statsd).
      Returns:
      the prefix of exported names, without separator: envoy by default, as in envoy_cluster_upstream_rq_total (Prometheus) and envoy.cluster.direct... (statsd)

    • tagExtractor

      public TagExtractor tagExtractor()
      Returns what takes the tags out of flat names.
      Returns:
      what takes the tags out of flat names

    • maxClusters

      public int maxClusters()
      Returns how many clusters may have stats of their own.
      Returns:
      how many clusters may have stats of their own

    • clusterOverflow

      public StatsRegistry.Overflow clusterOverflow()
      Returns what happens to clusters beyond maxClusters().
      Returns:
      what happens to clusters beyond maxClusters()

    • perHostClusters

      public boolean perHostClusters()
      Returns whether a direct connection's cluster is its server (host_port) rather than direct.
      Returns:
      whether a direct connection's cluster is its server (host_port) rather than direct

    • maxScriptStats

      public int maxScriptStats()
      Returns how many stats scripts may make.
      Returns:
      how many stats scripts may make

    • histogramBounds

      public double[] histogramBounds()
      Returns a copy of the bucket bounds of histograms registered without bounds of their own.
      Returns:
      a copy of the bucket bounds of histograms registered without bounds of their own

    • counter

      public Counter counter(String name)
      The counter named name, made the first time.
      Parameters:
      name - the flat name
      Returns:
      the counter
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • counter

      public Counter counter(String name, String help)
      The counter named name, made the first time with help.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      Returns:
      the counter
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • counter

      public Counter counter(String name, String help, LongSupplier value)
      A counter named name whose count is read from value, for counts kept elsewhere (such as HttpCache.stats()); it cannot be added to.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      value - reads the count; called whenever the metrics are shown
      Returns:
      the counter (the one already registered under name, if any)
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • gauge

      public Gauge gauge(String name)
      The gauge named name, made the first time.
      Parameters:
      name - the flat name
      Returns:
      the gauge
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • gauge

      public Gauge gauge(String name, String help)
      The gauge named name, made the first time with help.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      Returns:
      the gauge
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • gauge

      public Gauge gauge(String name, String help, LongSupplier value)
      A gauge named name whose value is read from value, for values kept elsewhere (a pool's size, the heap's); it cannot be changed through the gauge.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      value - reads the value; called whenever the metrics are shown
      Returns:
      the gauge (the one already registered under name, if any)
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • histogram

      public Histogram histogram(String name)
      The histogram named name, made the first time with the registry's bounds (StatsRegistry.Builder.histogramBounds, Envoy's by default).
      Parameters:
      name - the flat name
      Returns:
      the histogram
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • histogram

      public Histogram histogram(String name, String help)
      The histogram named name, made the first time with help and the registry's bounds.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      Returns:
      the histogram
      Throws:
      IllegalArgumentException - if the name is not valid, or names a metric of another kind

    • histogram

      public Histogram histogram(String name, String help, double... bounds)
      The histogram named name, made the first time with help and bounds.
      Parameters:
      name - the flat name
      help - a one-line description for Prometheus's # HELP
      bounds - the buckets' upper bounds, ascending and finite
      Returns:
      the histogram (the one already registered under name, with its bounds, if any)
      Throws:
      IllegalArgumentException - if the name is not valid, names a metric of another kind, or the bounds are not ascending and finite

    • scope

      public StatsScope scope(String prefix, int maxStats)
      The scope of metrics named prefix.<name>, which makes at most maxStats of them: for metrics whose names come from outside, such as scripts'. The same prefix gives the same scope (with the limit it was first asked with).
      Parameters:
      prefix - the names' prefix, without the dot
      maxStats - how many metrics the scope may make
      Returns:
      the scope
      Throws:
      IllegalArgumentException - if the prefix is not a valid name or the limit is negative

    • get

      public Metric get(String name)
      The metric named name, if registered.
      Parameters:
      name - the flat name
      Returns:
      the metric, or null

    • remove

      public boolean remove(String name)
      Forgets the metric named name: it is shown no more, and registering the name again makes a new one. Whoever holds the old one may still use it, to no effect.
      Parameters:
      name - the flat name
      Returns:
      whether there was such a metric

    • metrics

      public List<Metric> metrics()
      Returns the metrics, sorted by flat name.
      Returns:
      the metrics, sorted by flat name

    • size

      public int size()
      Returns how many metrics there are.
      Returns:
      how many metrics there are

    • toString

      public String toString()
      Overrides:
      toString in class Object