Skip to content

Commit 73b8d37

Browse files
brunobatbrunobat
committed
Docs
1 parent fc4ee8a commit 73b8d37

File tree

3 files changed

+113
-2
lines changed

3 files changed

+113
-2
lines changed

‎docs/src/main/asciidoc/telemetry-micrometer-to-opentelemetry.adoc‎

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,14 @@ This extension provides support for both `Micrometer` and `OpenTelemetry` in Qua
2020
- The xref:opentelemetry.adoc[OpenTelemetry Guide] provides information about the OpenTelemetry extension.
2121
====
2222

23-
The bridge is much more than the simple OTLP registry found in Quarkiverse. In this extension, the OpenTelemetry SDK provides a Micrometer registry implementation.
23+
The bridge is more than the simple OTLP registry found in Quarkiverse. In this extension, the OpenTelemetry SDK provides a Micrometer registry implementation.
2424

2525
This allows the normal use of the Micrometer API, but have the metrics handled by the OpenTelemetry extension. All the configurations of the OpenTelemetry extension are available for this bridge.
2626

2727
The bridge enables to forward to OpenTelemetry all the automatic instrumentation metrics generated by Micrometer in Quarkus, as well as custom user metrics.
2828

29+
The bridge is based on the https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/library[`micrometer/micrometer-1.5`] OpenTelemetry instrumentation library.
30+
2931
== Usage
3032

3133
If you already have your Quarkus project configured, you can add the `quarkus-micrometer-opentelemetry` extension to your project by running the following command in your project base directory:
@@ -50,4 +52,110 @@ This will add the following to your build file:
5052
implementation("io.quarkus:quarkus-micrometer-opentelemetry")
5153
----
5254

55+
== Metric differences between Micrometer and OpenTelemetry
56+
57+
=== API differences
58+
The metrics produced with each framework follow different APIs and the mapping is not 1:1.
59+
60+
One fundamental API difference is that Micrometer uses a https://docs.micrometer.io/micrometer/reference/concepts/timers.html[Timer] and OpenTelemetry uses a https://opentelemetry.io/docs/specs/otel/metrics/data-model/#histogram[Histogram] to record latency (execution time) metrics and the frequency of the events.
61+
62+
When using the `Timed` with Micrometer, 2 different metrics are https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/324fdbdd452ddffaf2da2c5bf004d8bb3fdfa1dd/instrumentation/micrometer/micrometer-1.5/library/src/main/java/io/opentelemetry/instrumentation/micrometer/v1_5/OpenTelemetryTimer.java#L31[created on the OpenTelemetry side], one `Gauge` for the `max` value and one `Histogram`.
63+
64+
The `DistributionSummary` from Micrometer is transformed into a `histogram` represented by a `DoubleGauge' with data points matching the buckets, another `DoubleGauge` for the `max` value and finally an actually OpenTelemetry `Histogram`. There is data duplication that might be optimized in the future.
65+
66+
|===
67+
|Micrometer |OpenTelemetry
68+
69+
|DistributionSummary
70+
|`<Metric name>` (Histogram), `<Metric name>.max` (DoubleGauge)
71+
72+
|DistributionSummary with SLOs
73+
|`<Metric name>` (Histogram), `<Metric name>.max` (DoubleGauge), `<Metric name>.histogram` (DoubleGauge)
74+
75+
|LongTaskTimer
76+
|`<Metric name>.active` (ObservableLongUpDownCounter), `<Metric name>.duration` (ObservableDoubleUpDownCounter)
77+
78+
|Timer
79+
|`<Metric name>` (Histogram), `<Metric name>.max` (ObservableDoubleGauge)
80+
|===
81+
82+
83+
84+
=== Semantic convention differences
85+
86+
The following table shows some differences between the two frameworks. This list is not exhaustive and only shows some examples, for reference.
87+
88+
When `quarkus.micrometer.binder.jvm=true` is set, the JVM metrics are collected by Micrometer. Here we show a subset related with `Threads`.
89+
90+
91+
|===
92+
|Micrometer Meter |Quarkus Micrometer Prometheus output | This bridge OpenTelemetry output name | Related OpenTelemetry Semantic Convention (not applied)
93+
94+
|Using the @Timed interceptor.
95+
|
96+
|method.timed (Histogram), method.timed.max (DoubleGauge)
97+
|NA
98+
99+
|Using the @Counted interceptor.
100+
|
101+
|method.counted (DoubleSum)
102+
|NA
103+
104+
|`http.server.active.requests` (Gauge)
105+
|`http_server_active_requests` (Gauge)
106+
|`http.server.active.requests` (DoubleGauge)
107+
|https://opentelemetry.io/docs/specs/semconv/http/http-metrics/#metric-httpserveractive_requests[`http.server.active_requests`] (UpDownCounter)
108+
109+
|`http.server.requests` (Timer)
110+
|`http_server_requests_seconds_count`, `http_server_requests_seconds_sum`, `http_server_requests_seconds_max` (Gauge)
111+
|`http.server.requests` (Histogram), `http.server.requests.max` (DoubleGauge)
112+
|https://opentelemetry.io/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestduration[`http.server.request.duration`] (Histogram)
113+
114+
|`http.server.bytes.read` (DistributionSummary)
115+
|`http_server_bytes_read_count`, `http_server_bytes_read_sum` , `http_server_bytes_read_max` (Gauge)
116+
|`http.server.bytes.read` (Histogram), `http.server.bytes.read.max` (DoubleGauge)
117+
|https://opentelemetry.io/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestbodysize[`http.server.request.body.size`] (Histogram)
118+
119+
|`http.server.bytes.write` (DistributionSummary)
120+
|`http_server_bytes_write_count`, `http_server_bytes_write_sum` , `http_server_bytes_write_max` (Gauge)
121+
|`http.server.bytes.write` (Histogram), `http.server.bytes.write.max` (DoubleGauge)
122+
|https://opentelemetry.io/docs/specs/semconv/http/http-metrics/#metric-httpserverresponsebodysize[`http.server.response.body.size`] (Histogram)
123+
124+
|`http.server.connections` (LongTaskTimer)
125+
|`http_server_connections_seconds_active_count`, `http_server_connections_seconds_duration_sum` `http_server_connections_seconds_max` (Gauge)
126+
|`http.server.connections.active` (LongSum), `http.server.connections.duration` (DoubleGauge)
127+
| N/A
128+
129+
|`jvm.threads.live` (Gauge)
130+
|`jvm_threads_live_threads` (Gauge)
131+
|`jvm.threads.live` (DoubleGauge)
132+
|https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmthreadcount[`jvm.threads.live`] (UpDownCounter)
133+
134+
|`jvm.threads.started` (FunctionCounter)
135+
|`jvm_threads_started_threads_total` (Counter)
136+
|`jvm.threads.started` (DoubleSum)
137+
|https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmthreadcount[`jvm.threads.live`] (UpDownCounter)
138+
139+
|`jvm.threads.daemon` (Gauge)
140+
|`jvm_threads_daemon_threads` (Gauge)
141+
|`jvm.threads.daemon` (DoubleGauge)
142+
|https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmthreadcount[`jvm.threads.live`] (UpDownCounter)
143+
144+
|`jvm.threads.peak` (Gauge)
145+
|`jvm_threads_peak_threads` (Gauge)
146+
|`jvm.threads.peak` (DoubleGauge)
147+
|N/A
148+
149+
|`jvm.threads.states` (Gauge per state)
150+
|`jvm_threads_states_threads` (Gauge)
151+
|`jvm.threads.states` (DoubleGauge)
152+
|https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmthreadcount[`jvm.threads.live`] (UpDownCounter)
153+
|===
154+
155+
156+
[NOTE]
157+
====
158+
- Some metrics might be absent of the output if they contain no data.
159+
====
53160

161+
== See output

‎extensions/micrometer-opentelemetry/deployment/src/test/java/io/quarkus/micrometer/opentelemetry/deployment/DistributionSummaryTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ void histogramTest() {
7777
.hasValue(500)
7878
.hasAttributes(attributeEntry("tag", "value"))));
7979

80-
MetricData testSummaryHistogram = exporter.getFinishedMetricItem("testSummary.histogram");
80+
MetricData testSummaryHistogram = exporter.getFinishedMetricItem("testSummary.histogram"); // present when SLOs are set
8181
assertNotNull(testSummaryHistogram);
8282
assertThat(testSummaryHistogram)
8383
.hasDoubleGaugeSatisfying(

‎extensions/micrometer-opentelemetry/runtime/src/main/resources/application.properties‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Don't instrument with OTel
2+
quarkus.otel.instrument.http-server-metrics=false
3+
quarkus.otel.instrument.jvm-metrics=false

0 commit comments

Comments
 (0)