Summary

Summary metric, to track the size of events.

The quantiles are calculated over a sliding window of time. There are two options to configure this time window:

• maxAgeSeconds: Long - The duration of the time window, i.e. how long observations are kept before they are discarded. Default is 10 minutes.

• ageBuckets: Int - The number of buckets used to implement the sliding time window. If your time window is 10 minutes, and you have ageBuckets=5, buckets will be switched every 2 minutes. The value is a trade-off between resources (memory and cpu for maintaining the bucket) and how smooth the time window is moved. Default value is 5.

Similar to a histogram, a Summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.

A summary with a base metric name of <basename> exposes multiple time series during a scrape:

• Streaming φ-quantiles (0 ≤ φ ≤ 1) of observed events, exposed as <basename>{quantile="<φ>"}
• The total sum of all observed values, exposed as <basename>_sum
• The count of events that have been observed, exposed as <basename>_count

See https://prometheus.io/docs/practices/histograms/ for more info on quantiles.

Imports

import io.chrisdavenport.epimetheus._
import cats.effect._

import cats.effect.unsafe.implicits.global

And Example of a Summary with no labels:

val noLabelsSummaryExample = {
  for {
    pr <- PrometheusRegistry.build[IO]
    s <- Summary.noLabels(
      pr,
      Name("example_summary"),
      "Example Summary",
      Summary.quantile(0.5,0.05)
    )
    _ <- s.observe(0.1)
    _ <- s.observe(0.2)
    _ <- s.observe(1.0)
    currentMetrics <- pr.write004
    _ <- IO(println(currentMetrics))
  } yield ()
}
// noLabelsSummaryExample: IO[Unit] = FlatMap(
//   ioe = Delay(
//     thunk = io.chrisdavenport.epimetheus.PrometheusRegistry$$$Lambda$11197/0x00007fa08dea8210@2bf75933,
//     event = cats.effect.tracing.TracingEvent$StackTrace
//   ),
//   f = <function1>,
//   event = cats.effect.tracing.TracingEvent$StackTrace
// )

noLabelsSummaryExample.unsafeRunSync()
// # HELP example_summary Example Summary
// # TYPE example_summary summary
// example_summary{quantile="0.5"} 0.2
// example_summary_count 3
// example_summary_sum 1.3
//

An Example of a Summary with labels:

val withLabelsSummaryExample = {
  for {
    pr <- PrometheusRegistry.build[IO]
    s <- Summary.labelled(
      pr,
      Name("example_summary"),
      "Example Summary",
      Sized(Label("foo")),
      {s: String => Sized(s)},
      Summary.quantile(0.5,0.05)
    )
    _ <- s.label("bar").observe(0.1)
    _ <- s.label("baz").observe(0.2)
    _ <- s.label("baz").observe(1.0)
    currentMetrics <- pr.write004
    _ <- IO(println(currentMetrics))
  } yield ()
}
// withLabelsSummaryExample: IO[Unit] = FlatMap(
//   ioe = Delay(
//     thunk = io.chrisdavenport.epimetheus.PrometheusRegistry$$$Lambda$11197/0x00007fa08dea8210@42f5393f,
//     event = cats.effect.tracing.TracingEvent$StackTrace
//   ),
//   f = <function1>,
//   event = cats.effect.tracing.TracingEvent$StackTrace
// )

withLabelsSummaryExample.unsafeRunSync()
// # HELP example_summary Example Summary
// # TYPE example_summary summary
// example_summary{foo="bar",quantile="0.5"} 0.1
// example_summary_count{foo="bar"} 1
// example_summary_sum{foo="bar"} 0.1
// example_summary{foo="baz",quantile="0.5"} 0.2
// example_summary_count{foo="baz"} 2
// example_summary_sum{foo="baz"} 1.2
//