From 69b0c5c4d588c483173c99a44eec51ab7a633500 Mon Sep 17 00:00:00 2001 From: Tim Spence Date: Wed, 1 Feb 2023 11:26:04 +0000 Subject: [PATCH 1/2] Add docs on testing MetricRegistry implementation --- build.sbt | 2 +- docs/interface/metric-factory.md | 7 ++++--- docs/interface/metric-registry.md | 34 +++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 4 deletions(-) diff --git a/build.sbt b/build.sbt index 150964f2..212a083f 100644 --- a/build.sbt +++ b/build.sbt @@ -204,7 +204,7 @@ lazy val docs = project ), scalacOptions := Seq() ) - .dependsOn(core, java) + .dependsOn(core, java, testing) .enablePlugins(TypelevelSitePlugin) lazy val unidocs = project diff --git a/docs/interface/metric-factory.md b/docs/interface/metric-factory.md index 09345f2b..2dd1ed98 100644 --- a/docs/interface/metric-factory.md +++ b/docs/interface/metric-factory.md @@ -43,9 +43,9 @@ MetricFactory.WithCallbacks.noop[IO] MetricFactory.builder.noop[IO] ``` -### Constructing from a `MetricRegitry` +### Constructing from a `MetricRegistry` -`MetricRegitry` provides a builder with a fluent API that allows you to create an instance that adds an optional +`MetricRegistry` provides a builder with a fluent API that allows you to create an instance that adds an optional prefix and/or common label set to all metrics. ```scala mdoc @@ -65,6 +65,7 @@ MetricFactory ``` Common labels are a set of labels that are checked at runtime so that the label names conform to the [OpenMetrics] + format and no more than ten are defined at any one time, which helps to reduce cardinality. There is no compile time checking of these labels as it is assumed they will come from the runtime environment. @@ -159,7 +160,7 @@ val factoryWithCallbacksG = factoryWithCallbacksF.imapK(fk, gk) It is also possible to construct a `MetricsFactory.WithCallbacks` from a `MetricsFactory` and [`CallbackRegistry`]: -```scala +```scala mdoc val callbackRegistryG: CallbackRegistry[G] = CallbackRegistry.noop[G] MetricFactory.builder.build(factoryG, callbackRegistryG) diff --git a/docs/interface/metric-registry.md b/docs/interface/metric-registry.md index e6d4514b..3528771b 100644 --- a/docs/interface/metric-registry.md +++ b/docs/interface/metric-registry.md @@ -4,6 +4,40 @@ The `MetricRegistry` is an interface that may be implemented by different backen metrics. This is not designed for use by users of the API directly, they should use it with the [`MetricFactory`] to create metrics using the [DSL](../interface/dsl.md). +### Testing Registry + +There exists a testing `MetricRegistry` implementation which allows you to check the value +history of any created metrics. For `Histogram` and `Summary` this is a `Chain` of all +the values that have been `observe`d for that metric. For `Counter` and `Gauge` this is +the history of the current value of the metric over time. + +```scala mdoc:silent +import cats.syntax.all._ +import cats.data.Chain +import cats.effect._ +import prometheus4cats._ +import prometheus4cats.testing._ + +TestingMetricRegistry[IO].flatMap { reg => + val factory = MetricFactory.builder.build(reg) + factory + .counter("counter_total") + .ofDouble + .help("Describe what this metric does") + .build + .use { counter => + counter.inc >> counter.inc(2.0) + reg.counterHistory( + Counter.Name("counter_total"), + Metric.CommonLabels.empty + ).flatMap { hist => + IO(hist === Some(Chain(0.0, 1.0, 3.0))) + } + } +} +``` + + ### Development Notes All methods on `MetricRegistry` return the desired [primitive metric] contained in a Cats-Effect `Resource`. This From 089b42156775fbfee5de86f0451ea161d7d851b6 Mon Sep 17 00:00:00 2001 From: Tim Spence Date: Wed, 1 Feb 2023 16:51:56 +0000 Subject: [PATCH 2/2] Move testing registry docs --- docs/implementations/testing.md | 34 +++++++++++++++++++++++++++++++ docs/interface/metric-registry.md | 34 ------------------------------- 2 files changed, 34 insertions(+), 34 deletions(-) create mode 100644 docs/implementations/testing.md diff --git a/docs/implementations/testing.md b/docs/implementations/testing.md new file mode 100644 index 00000000..2f86e520 --- /dev/null +++ b/docs/implementations/testing.md @@ -0,0 +1,34 @@ +# Testing Registry + +There exists a testing `MetricRegistry` implementation which allows you to check the value +history of any created metrics. For `Histogram` and `Summary` this is a `Chain` of all +the values that have been `observe`d for that metric. For `Counter` and `Gauge` this is +the history of the current value of the metric over time. + +```scala mdoc:silent +import cats.syntax.all._ +import cats.data.Chain +import cats.effect._ +import prometheus4cats._ +import prometheus4cats.testing._ + +TestingMetricRegistry[IO].flatMap { reg => + val factory = MetricFactory.builder.build(reg) + factory + .counter("counter_total") + .ofDouble + .help("Describe what this metric does") + .build + .use { counter => + counter.inc >> counter.inc(2.0) + reg.counterHistory( + Counter.Name("counter_total"), + Metric.CommonLabels.empty + ).flatMap { hist => + IO(hist === Some(Chain(0.0, 1.0, 3.0))) + } + } +} +``` + + diff --git a/docs/interface/metric-registry.md b/docs/interface/metric-registry.md index 3528771b..e6d4514b 100644 --- a/docs/interface/metric-registry.md +++ b/docs/interface/metric-registry.md @@ -4,40 +4,6 @@ The `MetricRegistry` is an interface that may be implemented by different backen metrics. This is not designed for use by users of the API directly, they should use it with the [`MetricFactory`] to create metrics using the [DSL](../interface/dsl.md). -### Testing Registry - -There exists a testing `MetricRegistry` implementation which allows you to check the value -history of any created metrics. For `Histogram` and `Summary` this is a `Chain` of all -the values that have been `observe`d for that metric. For `Counter` and `Gauge` this is -the history of the current value of the metric over time. - -```scala mdoc:silent -import cats.syntax.all._ -import cats.data.Chain -import cats.effect._ -import prometheus4cats._ -import prometheus4cats.testing._ - -TestingMetricRegistry[IO].flatMap { reg => - val factory = MetricFactory.builder.build(reg) - factory - .counter("counter_total") - .ofDouble - .help("Describe what this metric does") - .build - .use { counter => - counter.inc >> counter.inc(2.0) - reg.counterHistory( - Counter.Name("counter_total"), - Metric.CommonLabels.empty - ).flatMap { hist => - IO(hist === Some(Chain(0.0, 1.0, 3.0))) - } - } -} -``` - - ### Development Notes All methods on `MetricRegistry` return the desired [primitive metric] contained in a Cats-Effect `Resource`. This