includes.metrics.prometheus-exemplar-support.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2021, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
ifndef::rootdir[:rootdir: {docdir}/../..]
ifndef::flavor-lc[:flavor-lc: se]
ifdef::se-flavor[:metrics-endpoint: /observe/metrics]
ifndef::se-flavor[:metrics-endpoint: /metrics]
:description: Helidon metrics
:keywords: helidon, metrics, exemplar, prometheus, OpenMetrics
:feature-name: OpenMetrics exemplar support
:openmetrics-media-type: application/openmetrics-text
== Contents
- <>
- <>
- <>
- <>
- <>
== Overview
A meter typically reflects the usage of a _single_ point in your service which processes _multiple_ requests over time.
A value such as the total time consumed by a given REST endpoint which can be invoked multiple times underscores the aggregate nature of meter values; Helidon accumulates the time from all requests in the total duration.
// suppress inspection "GrazieInspection"
Tracing, on the other hand, captures the usage of _multiple_ parts of your code as your service responds to a _single_ request.
Metrics and tracing come together in Helidon's support for exemplars.
[NOTE]
--
link:https://www.merriam-webster.com/dictionary/exemplar[_exemplar_] - one that serves as a model or example
[.text-right]
-- Merriam-Webster Dictionary
--
In the context of metrics, an _exemplar_ for a given meter is a specific sample which, in some sense, made a typical contribution to the meter's value. For example, an exemplar for a `Counter` might be the most recent sample which updated the counter. The metrics output identifies the exemplar sample using the span and trace IDs of the span and trace which triggered that sample.
Exemplar support in Helidon relies on the exemplar support provided by the underlying metrics implementation. Currently, Helidon's Micrometer implementation supports exemplars as recorded by Micrometer's Prometheus meter registry and exposed by the OpenMetrics output (media type `{openmetrics-media-type}`).
include::{rootdir}/includes/dependencies.adoc[]
[source,xml,subs="verbatim,attributes"]
----
io.helidon.metrics
helidon-metrics-trace-exemplar
runtime
----
Also, include the Helidon integration module for a tracing implementation (such as
ifdef::se-flavor[]
xref:{rootdir}/se/tracing.adoc#zipkin-tracing[Helidon Zipkin])
endif::[]
ifdef::mp-flavor[]
xref:{rootdir}/mp/tracing.adoc#zipkin-tracing[Helidon Zipkin])
endif::[]
include::{rootdir}/includes/tracing/tracer-zipkin.adoc[tag=zipkin-dependency]
Add the Helidon tracing component itself:
ifdef::se-flavor[]
include::{rootdir}/se/tracing.adoc[tag=tracing-dependency]
endif::[]
ifdef::mp-flavor[]
include::{rootdir}/mp/tracing.adoc[tag=tracing-dependency]
endif::[]
== Usage
Once you add the appropriate dependencies to your project, exemplar support runs automatically as part of the Helidon metrics implementation using Micrometer. You do not need to change your application or configuration.
=== Interpreting Exemplars
Each exemplar reflects a sample described by a label, a value, and a timestamp.
When a client accesses the `{metrics-endpoint}` endpoint and specifies that it accepts the `{openmetrics-media-type}` media type, the label, value, and timestamp appear in the OpenMetrics response for meters that support exemplars.
The exemplar information in the output describes a single, actual sample that is representative of the statistical value as recorded by the underlying Micrometer Prometheus meter registry.
=== Output Format
In the OpenMetrics output, an exemplar actually appears as a comment appended to the normal OpenMetrics output.
.OpenMetrics format with exemplars
[source,subs="quotes"]
----
_meter-identifier_ _meter-value_ # _exemplar-label_ _sample-timestamp_
----
Even downstream consumers of OpenMetrics output that do not recognize the exemplar format should continue to work correctly (as long as they _do_ recognize comments).
But some consumers, such as trace collectors and their UIs, understand the exemplar format, and they allow you to browse meters and then navigate directly to the trace for the meter's exemplar.
== Examples
ifdef::se-flavor[]
Helidon includes an link:{helidon-github-examples-url}/metrics/exemplar[example application], based on the QuickStart application, which illustrates exemplar support.
endif::[]
Once you enable exemplar support you can see the exemplars in the metrics output.
.Exemplar output - `Counter`
[listing,subs="quotes"]
----
# TYPE counterForPersonalizedGreetings counter
# HELP counterForPersonalizedGreetings
counterForPersonalizedGreetings_total{scope="application"} 4.0 # {span_id="6b1fc9f9fd42fb0c",trace_id="6b1fc9f9fd42fb0c"} 1.0 1696889651.779
----
The exemplar (the portion following the `#`) is a sample corresponding to an update to the counter, showing the span and trace identifiers, the amount by which the counter was updated (`1.0`), and the timestamp recording when the update occurred expressed as seconds in the UNIX epoch (`1696889651.779`).
== Additional Information
Brief discussion of link:{openmetrics-exemplar-spec-url}[exemplars in the OpenMetrics spec]