Skip to main content
A Histogram instrument that records values of type A. Histogram metric data points convey a population of recorded measurements in a compressed format. A histogram bundles a set of events into divided populations with an overall event count and aggregate sum for all events.

​
Type Signature

trait Histogram[F[_], A]
Type Parameters:
  • F[_] - the higher-kinded type of a polymorphic effect
  • A - the type of values to record. Must have a MeasurementValue instance. Long and Double are supported out of the box.

​
Creating a Histogram

Histograms are created using the Meter API: 
val meter: Meter[IO] = ???

val histogram: IO[Histogram[IO, Double]] =
  meter.histogram[Double]("http.server.duration")
    .withUnit("ms")
    .withDescription("HTTP server request duration")
    .withExplicitBucketBoundaries(BucketBoundaries(Vector(10, 50, 100, 500, 1000)))
    .create

​
Backend Methods

​
record

Records a value with a set of attributes.
​
value
A
required
The value to record.
​
attributes
immutable.Iterable[Attribute[_]]
required
The set of attributes to associate with the value.
Returns: F[Unit] Example: 
histogram.flatMap { h =>
  h.record(
    156.0,
    Attribute(AttributeKey.string("http.method"), "GET"),
    Attribute(AttributeKey.long("http.status_code"), 200L)
  )
}

​
recordDuration

Records the duration of a given effect.
​
timeUnit
TimeUnit
required
The time unit of the duration measurement.
​
attributes
Resource.ExitCase => immutable.Iterable[Attribute[_]]
required
A function to build the set of attributes based on the exit case.
Returns: Resource[F, Unit] Example: 
val histogram: Histogram[IO, Double] = ???
val attributeKey = AttributeKey.string("query_name")

def findUser(name: String) =
  histogram.recordDuration(
    TimeUnit.MILLISECONDS,
    _ => List(Attribute(attributeKey, "find_user"))
  ).use { _ =>
    db.findUser(name)
  }

​
Builder Methods

​
withUnit

Sets the unit of measure for this histogram.
​
unit
String
required
The measurement unit. Must be 63 or fewer ASCII characters.
Returns: Histogram.Builder[F, A] Reference: Instrument Unit

​
withDescription

Sets the description for this histogram.
​
description
String
required
The description of the histogram.
Returns: Histogram.Builder[F, A] Reference: Instrument Description

​
withExplicitBucketBoundaries

Sets the explicit bucket boundaries for this histogram.
​
boundaries
BucketBoundaries
required
The bucket boundaries to use for the histogram.
Returns: Histogram.Builder[F, A] Reference: Explicit Bucket Boundaries

​
create

Creates a Histogram with the configured unit, description, and bucket boundaries. Returns: F[Histogram[F, A]]

​
Helper Methods

​
causeAttributes

Utility function to extract cause attributes from a Resource.ExitCase. Type Signature: 
def causeAttributes(ec: Resource.ExitCase): List[Attribute[String]]
Returns:
  • Empty list for ExitCase.Succeeded
  • Attribute("cause", className) for ExitCase.Errored
  • Attribute("cause", "canceled") for ExitCase.Canceled

Build docs developers (and LLMs) love

Get started for freeTalk to us