Java Registry

The Java registry implements both MetricRegistry and CallbackRegistry, wrapping the Prometheus Java library. This provides interoperability with anything that depends on the Java library.

ℹ️ As of version 1.1.0 of Prometheus4Cats, the Java registry now supports Exemplars

ℹ️ The Java Registry does add a runtime constraint that go beyond constraints that Prometheus itself imposes: You cannot have two metrics of the same name with different labels. This issue describes the problem.

We have actually worked around this issue for callbacks, where metrics and metric collections can have the same metric name with different labels, which is fine for Prometheus to scrape.

See the example below on how to use the Java Registry:

import cats.effect.IO
import cats.effect.Resource

import io.prometheus.client.CollectorRegistry

import org.typelevel.log4cats.Logger
import org.typelevel.log4cats.noop.NoOpLogger

import prometheus4cats.MetricFactory
import prometheus4cats.javasimpleclient.JavaMetricRegistry

// a logger is required to construct the Java registry
implicit val logger: Logger[IO] = NoOpLogger.impl[IO] 

// Construct a Java regisitry using the default collector registry
val default: Resource[IO, JavaMetricRegistry[IO]] =
  JavaMetricRegistry.Builder().build[IO]

// Construct a Java registry using a custom collector registry
val custom: Resource[IO, JavaMetricRegistry[IO]] =
  JavaMetricRegistry.Builder().withRegistry(new CollectorRegistry()).build[IO]

// Use the registry to get a factory
val factory: Resource[IO, MetricFactory.WithCallbacks[IO]] =
  custom.map(MetricFactory.builder.build(_))

Built-in Metrics

The Java registry provides some metrics related to its internals, these can used when investigating a callback that may not be functioning probably:

Metric Name	Metric Type	Labels	Description
prometheus4cats_registered_metrics	Gauge		Number of metrics registered in the Prometheus Java registry by Prometheus4Cats
prometheus4cats_registered_metric_claims	Gauge	metric_name, metric_type	Number of claims on each metric registered in the Prometheus Java registry by Prometheus4Cats; i.e. how many references there are for each metric
prometheus4cats_registered_callback_metrics	Gauge		Number of callback metrics registered in the Prometheus Java registry by Prometheus4Cats
prometheus4cats_registered_callbacks_per_metric	Gauge	metric_name, metric_type	Number of callbacks per metric callback registered with the Prometheus4Cats Java registry. Multiple callbacks may be registered per metric name.
prometheus4cats_combined_callback_metric_total	Counter	metric_name, status	Number of times all callbacks for a metric have been executed, with a status (success, error, timeout)
prometheus4cats_callback_total	Counter	metric_name, status	Number of times each metric callback has been executed, with a status (success, error, timeout)
prometheus4cats_collection_callback_duplicates	Gauge	duplicate_type, metric_prefix	Duplicate metrics with different types detected in metric collections callbacks
prometheus4cats_collection_callback_duration	Histogram		Time it takes to run all metric collection callbacks
prometheus4cats_combined_collection_callback_total	Counter	status	Number of times all of the metric collection callbacks have been executed, with a status (success, error, timeout)
prometheus4cats_collection_callback_total	Counter	status	Number of times a metric collection callback has been executed, with a status (success, error, timeout)

Implementation Notes

As per the MetricRegistry and CallbackRegistry interface, this implementation returns Cats-Effect Resources to indicate a metric being registered and ultimately de-registered. Requesting a metric of the same name (and labels) multiple times will not result in an error, instead you will be returned the currently registered metric. The Java registry wrapper implements reference counting to ensure that a metric or callback will only be de-registered when there are no more references to it or when the wrapper's surrounding Resource is finalized.