You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:writing-code-content: code which explicitly invokes the metrics API to register {metrics}, retrieve previously-registered {metrics}, and update {metric} values.
26
+
ifdef::se-flavor[:prom-output-scope-prefix: ]
27
+
ifdef::mp-flavor[:prom-output-scope-prefix: mp_]
26
28
27
29
* a unified way for
28
30
ifdef::mp-flavor[MicroProfile]
@@ -73,16 +75,66 @@ Later sections of this document describe how to do
73
75
ifdef::mp-flavor[each of these.]
74
76
ifdef::se-flavor[this.]
75
77
78
+
// tag::meter-types-summary[]
79
+
=== {metric_uc} Types
80
+
81
+
Helidon supports meters
82
+
ifdef::se-flavor[inspired by link:{micrometer-url}[Micrometer]]
83
+
ifdef::mp-flavor[described by the link:{microprofile-metrics-spec-url}[MicroProfile Metrics] spec]
| Summary of samples each with a `long` value. Reports aggregate information over all samples (count, total, mean, max) as well as the distribution of sample values using percentiles and bucket counts. |
| Accumulation of short-duration (typically under a minute) intervals. Typically updated using a Java link:{jdk-javadoc-url}/java.base/java/time/Duration.html[`Duration`] or by recording the time taken by a method invocation or lambda. Reports the count, total time, max, and mean; provides a
| View of a value that is assignment-compatible with a subtype of Java link:{jdk-javadoc-url}/java.base/java.lang.Number.html[`Number`]. The underlying value is updated by code elsewhere in the system, not by invoking methods on the gauge itself. |
Helidon distinguishes among _scopes_, or types, of
129
+
Helidon distinguishes among _scopes_, or categories, of
78
130
ifdef::se-flavor[{metrics}.]
79
131
ifdef::mp-flavor[{metrics} as described in the link:{microprofile-metrics-spec-url}[MP metrics specification].]
80
132
81
133
Helidon includes {metrics} in the built-in scopes described below.
82
134
Applications often register their own {metrics} in the `application` scope but can create their own scopes and register {metrics} within them.
83
135
84
136
.Built-in {metric} scopes
85
-
[%autowidth]
137
+
[cols="2,8"]
86
138
|====
87
139
| Built-in Scope | Typical Usage
88
140
@@ -134,12 +186,13 @@ Further, clients can narrow down to a specific metric name by adding the name as
134
186
curl -s -H 'Accept: text/plain' -X GET http://localhost:8080{metrics-endpoint}
135
187
----
136
188
137
-
[source,text]
189
+
[source,text,subs="attributes+"]
138
190
----
139
-
# TYPE base:classloader_total_loaded_class_count counter
140
-
# HELP base:classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution.
141
-
base:classloader_total_loaded_class_count 3157
191
+
# HELP classloader_loadedClasses_count Displays the number of classes that are currently loaded in the Java virtual machine.
In addition to your application {metrics}, the reports contain other
162
215
{metrics} of interest such as system and VM information.
163
216
217
+
==== OpenMetrics and Prometheus Format
218
+
The link:{openmetrics-format-doc-url}[OpenMetrics format] and the link:{prometheus-exposition-format-doc-url}[Prometheus exposition format] are very similar in most important respects but are not identical. This brief summary treats them as the same.
219
+
220
+
The OpenMetrics/Prometheus format represents each {metric} using three lines of output as summarized in the following table.
221
+
222
+
.OpenMetrics/Prometheus format
223
+
[cols="1,6,6"]
224
+
|====
225
+
| Line prefix | Purpose | Format
226
+
227
+
| `# TYPE` | Displays the scope, name, and type of the {metric} | `TYPE <scope>:<output-name> <{metric}-type>`
228
+
| `# HELP` | Displays the scope, name, and description of the {metric} | `HELP <scope>:<output-name> <registered description>`
229
+
| (none) | Displays the scope, {metric} ID, and current value of the {metric} | `<scope>:<output-name> <current value>`
230
+
|====
231
+
The OpenMetrics/Prometheus output converts {metric} IDs in these ways:
232
+
233
+
* Names in camel case are converted to "snake case" and dots are converted to underscores.
234
+
* Names include any units specified for the {metric}.
235
+
* For percentiles, the ID includes a tag identifying which percentile the line of output describes.
236
+
237
+
As the earlier example output showed, for a {metric} with multiple values, such as a timer or a
238
+
ifdef::se-flavor[distribution summary,]
239
+
ifdef::mp-flavor[histogram,]
240
+
(with, among others, `max`, `mean`, and `count`), the OpenMetrics/Prometheus output reports a "metric family" which includes a separate family member {metric} for each of the multiple values. The name for each member in the family is derived from the registered name for the {metric} plus a suffix indicating which one of the {metric}'s multiple values the line refers to.
241
+
242
+
The following table summarizes the naming for each {metric} type.
243
+
244
+
.OpenMetrics/Prometheus {metric_uc} Naming
245
+
|====
246
+
| {metric_uc} Type | Example registered name | {metric_uc} family member | Name Suffix | Example displayed name
| Frequency of invocations and the distribution of how long the invocations take.
95
+
| Automatically registers a `Timer` and updates it with each invocation of the annotated constructor or method. ^1^
96
96
97
97
|====
98
-
99
-
Place annotations on constructors or methods to measure those specific executables. If you annotate the class instead, Helidon applies that annotation to all constructors and methods which the class declares.
98
+
^1^ Place annotations on constructors or methods to measure those specific executables. If you annotate the class instead, Helidon applies that annotation to all constructors and methods which the class declares.
100
99
101
100
==== Metric-referencing Annotations
102
101
To get a reference to a specific metric, use a metric-referencing annotation in any bean, including your REST resource classes.
0 commit comments