Coda Hale metrics configuration

This section describes the available Coda Hale metrics configuration.

Coda Hale metric registry

Cinnamon automatically adds the internal registry of metrics to Coda Hale’s SharedMetricRegistries. The key used is cinnamon-registry, but it can be overridden by config:

copycinnamon.chmetrics.registry-name = "someCustomName"

Histogram reservoirs

The type of histogram reservoir used by the Coda Hale Metrics backend can be configured. The built-in reservoir types are described in the Coda Hale Metrics documentation for histograms. The default reservoir is the Exponentially Decaying Reservoir.

To configure the reservoir use the histogram.reservoir setting. The available built-in reservoirs are default (exponentially-decaying), exponentially-decaying, uniform, sliding-window, and sliding-time-window.

The sliding-window reservoir also has a window size that can be configured, and the sliding-time-window reservoir has a time period that can be configured.

For example, to change the reservoir type to the Sliding Window reservoir and set a size, use the following configuration:

copycinnamon.chmetrics {
  histogram {
    reservoir = sliding-window
    sliding-window {
      size = 4096
    }
  }
}

Or to change the reservoir type to the Sliding Time Window reservoir and set a time period:

copycinnamon.chmetrics {
  histogram {
    reservoir = sliding-time-window
    sliding-time-window {
      time = 2 seconds
    }
  }
}

Custom histogram reservoirs

A custom histogram reservoir can also be configured. To do this, a ReservoirFactory class needs to be implemented and configuration added to use this factory.

For example, if we have reservoir class called CustomReservoir, we can create a factory for this.

copyimport com.lightbend.cinnamon.chmetrics.histogram.ReservoirFactory
import com.typesafe.config.Config

class CustomReservoirFactory(config: Config) extends ReservoirFactory {
  def create: Reservoir = new CustomReservoir(config.getInt("some-custom-setting"))
}

ReservoirFactory constructors can optionally take a Config object, with settings specific to this reservoir.

We can then configure the Coda Hale Metrics backend to use this reservoir with:

copycinnamon.chmetrics {
  histogram {
    reservoir = my-custom-reservoir
    my-custom-reservoir {
      factory-class = "histogram.sample.CustomReservoirFactory"
      some-custom-setting = 42
    }
  }
}

HDR histogram reservoirs

Coda Hale Metrics can be configured to use High Dynamic Range Histograms.

First add this extra dependency to your build, which integrates HdrHistogram as a Coda Hale Metrics histogram reservoir:

sbt

copylibraryDependencies += Cinnamon.library.cinnamonCHMetricsHdrHistogram

Maven

copy<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics-hdrhistogram</artifactId>
    <version>2.20.3</version>
</dependency>

Gradle

copydependencies {
  implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics-hdrhistogram', version: '2.20.3'
}

You can then configure the Coda Hale Metrics backend to use the HdrHistogram reservoir with:

copycinnamon.chmetrics {
  histogram {
    reservoir = hdr
  }
}

The HdrHistogram can also be configured. The value precision, lowest discernible value, and highest trackable value can be set.

The histogram can also be configured to reset on snapshots, when a Coda Hale Metrics reporter uses the snapshot to report current values. Note that this means that only a single reporter can be used. Reset on snapshot is the default behaviour for HdrHistogram. If reset on snapshot is disabled, then the histogram represents the entire lifetime of the metric rather than the reporting interval.

As an example, if the histogram is used to observe times recorded in nanoseconds, that could range up to 5 minutes (highest trackable value of 300,000,000,000 nanoseconds), where the minimal accuracy required is a millisecond (lowest discernible value of 1,000,000 nanoseconds), and while maintaining a value precision of 3 significant digits across the range, then the following configuration might be used:

Example

copycinnamon.chmetrics {
  histogram {
    reservoir = hdr
    hdr {
      reset-on-snapshot = on
      significant-value-digits = 3
      lowest-discernible-value = 1000000
      highest-trackable-value = 300000000000
    }
  }
}

Reference

copycinnamon.chmetrics {
  histogram {
    hdr {

      # Whether to reset the histogram each time a snapshot is taken.
      # If enabled, then the histogram represents the snapshot interval,
      # which will be based on the reporting frequency. Note: only a single
      # reporter can be used when reset-on-snapshot is enabled.
      # If disabled, then the histogram represents the entire lifetime.
      reset-on-snapshot = on

      # Specifies the precision to use. This is the number of significant
      # decimal digits to which the histogram will maintain value resolution
      # and separation. Must be a non-negative integer between 0 and 5.
      significant-value-digits = 2

      # The lowest value that can be tracked (distinguished from 0) by the histogram.
      # Must be a positive integer that is >= 1. If set, requires highest-trackable-value.
      # If set to 0, then use the default (of 1).
      lowest-discernible-value = 0

      # The highest value to be tracked by the histogram.
      # Must be a positive integer that is >= (2 * lowest-discernible-value).
      # If set to 0, then an auto-adjusting highest-trackable-value is used,
      # and it can auto-resize to track values up to (Long.MAX_VALUE / 2).
      highest-trackable-value = 0
    }
  }
}

Note

These settings are defined in the reference.conf. You only need to specify any of these settings when you want to override the defaults.

Metric hints

Metrics, either created by Cinnamon instrumentation or custom metrics, can be given hints that will passed to the metric backend. These hints allow particular metrics to be configured differently from the default configuration.

The Recorder metric type is backed by a Histogram in Coda Hale Metrics. If you need a particular recorder to always use a specially configured HDR histogram, then you can do this by labelling the recorder with a hint and specifying the histogram reservoir configuration.

For example, using the custom metrics API you can pass in the hint when creating a custom recorder within an actor:

Scala

copyval recorder = CinnamonMetrics(context).createRecorder("recorder", hints = Set("custom-hdr"))

Java

copyfinal Set<String> hints = ImmutableSet.of("custom-hdr");
final Recorder recorder = CinnamonMetrics.get(getContext()).createRecorder("recorder", hints);

You can then configure this hint in the cinnamon.chmetrics.hints section using the name of the hint.

For example, here’s the same custom configuration for a histogram used to observe times (as described above in HDR histogram reservoirs) but scoped just for this hint:

copycinnamon.chmetrics {
  hints {
    custom-hdr {
      histogram {
        reservoir = hdr
        hdr {
          reset-on-snapshot = on
          significant-value-digits = 3
          lowest-discernible-value = 1000000
          highest-trackable-value = 300000000000
        }
      }
    }
  }
}