Hdrhistogram.md

Hdrhistogram

Metrics-scala supports transparent use of hdrhistogram. Hdrhistogram provides alternative high quality reservoir implementations which can be used in histograms and timers. Hdrhistogram-metrics-reservoir is used to bridge the two worlds.

Use these steps to start using hdrhistogram:

Step 1: Add dependency

Include the metrics4-scala-hdr artifact in your build. For SBT use:

libraryDependencies += "nl.grons" %% "metrics4-scala-hdr" % "4.1.5"

See the README to see which version(s) you can use.

Step 2: override the metric builder

Then create a trait Instrumented that overrides the metric builder:

import nl.grons.metrics4.scala._

trait Instrumented extends DefaultInstrumented {
  override lazy protected val metricBuilder =
    new HdrMetricBuilder(metricBaseName, metricRegistry, resetAtSnapshot = false)
}

Step 3: use

Your application can now use the Instrumented trait instead of DefaultInstrumented. For example:

package com.example.proj
import scala.concurrent.duration._

class UserRepository(db: Database) extends Instrumented {
  val resultCounts: Histogram = metrics.histogram("result-counts")

  def users(): Seq[User] = {
    val results = ???
    resultCounts += results.size()
    results
  }
}

When to use resetAtSnapshot?

HdrMetricBuilder accepts parameter resetAtSnapshot.

Set resetAtSnapshot to true when you regularly ship snapshots to an external system like Graphite. With this setting, the reservoirs are reset at every snapshot creation. You should make sure that only the graphite exporter reads the timer/histogram's values, otherwise you may loose data.

In all other cases, set resetAtSnapshot to false. Your metrics will then represent a longer history, similar to Dropwizard's default exponentially decaying reservoir.

See this article for more information.

Previous: Testing Up: Manual Next: Miscellaneous