From a299d10c0d9e78a8aa0d89aa3a519ebd445edb90 Mon Sep 17 00:00:00 2001 From: Carsten Brachem Date: Wed, 7 Aug 2024 04:04:41 +0200 Subject: [PATCH] Make more explicit that recording a metric is safe to call (#5365) Adds a TIP block to the docs to make it more explicit what happens when operations on Meters like increment are called, which will make it clear that such operations are safe to call from regular code. --- docs/modules/ROOT/nav.adoc | 2 +- docs/modules/ROOT/pages/concepts/meters.adoc | 5 +++++ docs/modules/ROOT/pages/concepts/registry.adoc | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 27d5824623..32dc4e381f 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,8 +2,8 @@ * xref:installing.adoc[Installing] * xref:concepts.adoc[Concepts] ** xref:concepts/implementations.adoc[Supported Monitoring Systems] -** xref:concepts/registry.adoc[Registry] ** xref:concepts/meters.adoc[Meters] +** xref:concepts/registry.adoc[Registry] ** xref:concepts/naming.adoc[Naming Meters] ** xref:concepts/meter-filters.adoc[Meter Filters] ** xref:concepts/rate-aggregation.adoc[Rate Aggregation] diff --git a/docs/modules/ROOT/pages/concepts/meters.adoc b/docs/modules/ROOT/pages/concepts/meters.adoc index 911a5685a1..a29770e1ad 100644 --- a/docs/modules/ROOT/pages/concepts/meters.adoc +++ b/docs/modules/ROOT/pages/concepts/meters.adoc @@ -1,6 +1,11 @@ [[meters]] = Meters +A `Meter` is the interface for collecting a set of measurements (which we individually call metrics) about your application. + Micrometer supports a set of `Meter` primitives, including `Timer`, `Counter`, `Gauge`, `DistributionSummary`, `LongTaskTimer`, `FunctionCounter`, `FunctionTimer`, and `TimeGauge`. Different meter types result in a different number of time series metrics. For example, while there is a single metric that represents a `Gauge`, a `Timer` measures both the count of timed events and the total time of all timed events. +TIP: Recording a measurement for a `Meter` is expected to be a relatively cheap operation and should not throw any exception. +If the xref:./registry.adoc[registry] supports publishing metrics to a monitoring system, this is done in a separate thread snd should not affect recording metrics. + A meter is uniquely identified by its name and dimensions. We use the terms, "`dimensions`" and "`tags,`" interchangeably, and the Micrometer interface is `Tag` simply because it is shorter. As a general rule, it should be possible to use the name as a pivot. Dimensions let a particular named metric be sliced to drill down and reason about the data. This means that, if only the name is selected, you can drill down by using other dimensions and reason about the value being shown. diff --git a/docs/modules/ROOT/pages/concepts/registry.adoc b/docs/modules/ROOT/pages/concepts/registry.adoc index eae8732d6d..476f2d9e72 100644 --- a/docs/modules/ROOT/pages/concepts/registry.adoc +++ b/docs/modules/ROOT/pages/concepts/registry.adoc @@ -1,7 +1,7 @@ [[registry]] = Registry -A `Meter` is the interface for collecting a set of measurements (which we individually call metrics) about your application. Meters in Micrometer are created from and held in a `MeterRegistry`. Each supported monitoring system has an implementation of `MeterRegistry`. How a registry is created varies for each implementation. +Meters in Micrometer are created from and held in a `MeterRegistry`. Each supported monitoring system has an implementation of `MeterRegistry`. How a registry is created varies for each implementation. Micrometer includes a `SimpleMeterRegistry` that holds the latest value of each meter in memory and does not export the data anywhere. If you do not yet have a preferred monitoring system, you can get started playing with metrics by using the simple registry: