Interface MetricProvider

All Known Implementing Classes:
MetricProviderImpl, OSGiMetricProvider, PrometheusMetricProvider, TestMetricProviderImpl

public interface MetricProvider
Factory to obtain a new metric for use by application code.

This API is a mix of (parts of) the Coda Hale's Dropwizard's MetricRegistry, and Prometheus' API. ODL application wanting to expose metrics are strongly encouraged to obtain new metric instances through this factory, instead of directly using Dropwizard new MetricRegistry themselves. This allows infrautils.metrics to expose all applications' metrics together through current and future reporters. This API also includes some convenience such as preventing accidental re-use of Metric IDs by different ODL applications, as well as (perhaps more importantly) isolating ODL applications from each other and preventing one from grabbing and reading or worse modifying another application's metric. Metrics should only be used to expose from an application to reporters registered centrally by infrautils.metrics, and are never exposed between applications.

The anchor Object parameter in each method is used to record which bundle registered the meter, and you almost always just use this for that argument. This is used in error messages if another bundle tries to register a duplicate ID, and could be used in the future to un-register metrics on bundle reload automatically instead of explicitly.

The id String parameter in each method must be globally unique; an IllegalArgumentException is thrown if it has previously already been used. The convention is to use odl.<projectName>.<moduleName>.<metricName>, so e.g. odl.infrautils.jobcoordinator.jobsPending.

Implementations of this interface are required to be thread-safe.

Author:
Michael Vorburger.ch
  • Method Details

    • newMeter

      @Deprecated(forRemoval=true) Meter newMeter(Object anchor, String id)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Create new Meter metric.
    • newMeter

      Meter newMeter(MetricDescriptor descriptor)
      Create new Meter metric without labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      Returns:
      the Meter
    • newMeter

      Labeled<Meter> newMeter(MetricDescriptor descriptor, String labelName)
      Create new Meter metric with 1 label.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      labelName - name of the (only) label of this metric
      Returns:
      an object from which a Meter can be obtained, given 1 label value
    • newMeter

      Labeled<Labeled<Meter>> newMeter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName)
      Create new Meter metric with 2 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      Returns:
      an object from which a Meter can be obtained, given 2 label values
    • newMeter

      Labeled<Labeled<Labeled<Meter>>> newMeter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName)
      Create new Meter metric with 3 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      Returns:
      an object from which a Meter can be obtained, given 3 label values
    • newMeter

      Labeled<Labeled<Labeled<Labeled<Meter>>>> newMeter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName, String fourthLabelName)
      Create new Meter metric with 4 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      fourthLabelName - name of the 4th label of this metric
      Returns:
      an object from which a Meter can be obtained, given 3 label values
    • newMeter

      Labeled<Labeled<Labeled<Labeled<Labeled<Meter>>>>> newMeter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName, String fourthLabelName, String fifthLabelName)
      Create new Meter metric with 5 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      fourthLabelName - name of the 4th label of this metric
      fifthLabelName - name of the 5th label of this metric
      Returns:
      an object from which a Meter can be obtained, given 3 label values
    • newCounter

      @Deprecated(forRemoval=true) Counter newCounter(Object anchor, String id)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Create new Counter metric.
    • newCounter

      Counter newCounter(MetricDescriptor descriptor)
      Create new Counter metric without labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      Returns:
      the Counter
    • newCounter

      Labeled<Counter> newCounter(MetricDescriptor descriptor, String labelName)
      Create new Counter metric with 1 label.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      labelName - name of the (only) label of this metric
      Returns:
      an object from which a Counter can be obtained, given 1 label value
    • newCounter

      Labeled<Labeled<Counter>> newCounter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName)
      Create new Counter metric with 2 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      Returns:
      an object from which a Counter can be obtained, given 2 label values
    • newCounter

      Labeled<Labeled<Labeled<Counter>>> newCounter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName)
      Create new Counter metric with 3 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      Returns:
      an object from which a Counter can be obtained, given 3 label values
    • newCounter

      Labeled<Labeled<Labeled<Labeled<Counter>>>> newCounter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName, String fourthLabelName)
      Create new Counter metric with 4 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      fourthLabelName - name of the 4th label of this metric
      Returns:
      an object from which a Counter can be obtained, given 4 label values
    • newCounter

      Labeled<Labeled<Labeled<Labeled<Labeled<Counter>>>>> newCounter(MetricDescriptor descriptor, String firstLabelName, String secondLabelName, String thirdLabelName, String fourthLabelName, String fifthLabelName)
      Create new Counter metric with 5 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      thirdLabelName - name of the 3rd label of this metric
      fourthLabelName - name of the 4th label of this metric
      fifthLabelName - name of the 5th label of this metric
      Returns:
      an object from which a Counter can be obtained, given 5 label values
    • newTimer

      @Deprecated(forRemoval=true) Timer newTimer(Object anchor, String id)
      Deprecated, for removal: This API element is subject to removal in a future version.
    • newTimer

      Timer newTimer(MetricDescriptor descriptor)
      Create new Timer metric without labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      Returns:
      the Timer
    • newTimer

      Labeled<Timer> newTimer(MetricDescriptor descriptor, String labelName)
      Create new Timer metric with 1 label.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      labelName - name of the (only) label of this metric
      Returns:
      an object from which a Timer can be obtained, given 1 label value
    • newTimer

      Labeled<Labeled<Timer>> newTimer(MetricDescriptor descriptor, String firstLabelName, String secondLabelName)
      Create new Timer metric with 2 labels.
      Parameters:
      descriptor - a MetricDescriptor, typically created via MetricDescriptor.builder().anchor(this) .project("<projectName>").module("<moduleName>").id("<metricName>").build()
      firstLabelName - name of the 1st label of this metric
      secondLabelName - name of the 2nd label of this metric
      Returns:
      an object from which a Timer can be obtained, given 2 label values