Skip to content

Commit 3538175

Browse files
zeitlingerzeitlinger
authored
Add OTel support module and make examples standalone (#1868)
Inspired by #1854 (comment) ## Summary - Add `prometheus-metrics-otel-support` POM module that bundles the OTel SDK and Prometheus exporter as a single dependency, with the OTel instrumentation BOM imported for automatic version management - Add `prometheus-metrics-otel-support` to the BOM so users can manage it via `dependencyManagement` - Make all example projects standalone (no parent POM) — each example has its own `groupId`, `version`, and imports `prometheus-metrics-bom` directly, so users can copy-paste an example and build it without the parent chain - Add docs page for the OTel Support module (`docs/content/otel/support.md`) - Replace hardcoded `1.5.0` versions in OTel docs with `$version` placeholder and update `set-release-version-github-pages.sh` to process all markdown files under `docs/content` ## Test plan - [ ] `mise run build` passes - [ ] `mise run lint:super-linter` passes - [ ] `mise run test` passes - [ ] Verify `set-release-version-github-pages.sh` replaces `$version` in both `quickstart.md` and OTel docs --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
1 parent 7e472c7 commit 3538175

File tree

19 files changed

+342
-140
lines changed

19 files changed

+342
-140
lines changed

‎.mise/tasks/set-release-version-github-pages.sh‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
#!/usr/bin/env bash
22

3-
#MISE description="Set release version in GitHub Pages quickstart.md"
3+
#MISE description="Set release version in all GitHub Pages docs"
44

55
set -euox pipefail
66

77
version=$(git tag -l | grep 'v' | sort | tail -1 | sed 's/v//')
8-
marker="\$version"
9-
sed -i "s/$marker/$version/g" docs/content/getting-started/quickstart.md
8+
otelVersion=$(grep -oP '<otel.instrumentation.version>\K[^<]+' pom.xml | sed 's/-alpha$//')
9+
10+
find ./docs/content -name '*.md' \
11+
-exec sed -i "s/\$version/$version/g" {} + \
12+
-exec sed -i "s/\$otelVersion/$otelVersion/g" {} +

‎CLAUDE.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ mise run lint:super-linter
119119
- Integration tests are in `integration-tests/` and run during `verify` phase
120120
- Acceptance tests use OATs framework: `mise run acceptance-test`
121121

122+
## Documentation
123+
124+
- Docs live under `docs/content/` and use `$version` as a placeholder for the library version
125+
- When publishing GitHub Pages, `mise run set-release-version-github-pages` replaces `$version` with the latest git tag across all `docs/content/**/*.md` files (the published site is not versioned)
126+
- Use `$version` for the Prometheus client version and `$otelVersion-alpha` for the OTel instrumentation version — never hardcode them
127+
122128
## Java Version
123129

124130
Source compatibility: Java 8. Tests run on Java 25 (configured in `mise.toml`).

‎docs/content/otel/jvm-runtime-metrics.md‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,44 +24,47 @@ OTel SDK wiring shown below.
2424

2525
## Dependencies
2626

27+
Use the [OTel Support]({{< relref "support.md" >}}) module
28+
to pull in the OTel SDK and Prometheus exporter, then add
29+
the runtime-telemetry instrumentation:
30+
2731
{{< tabs "jvm-runtime-deps" >}}
2832
{{< tab "Gradle" >}}
2933

3034
```groovy
31-
implementation 'io.opentelemetry:opentelemetry-sdk'
32-
implementation 'io.opentelemetry:opentelemetry-exporter-prometheus'
33-
34-
// Pick ONE of the following:
35-
// Java 8+:
36-
implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8'
37-
// Java 17+ (adds JFR-based metrics):
38-
// implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java17'
35+
implementation 'io.prometheus:prometheus-metrics-otel-support:$version'
36+
37+
// Use opentelemetry-runtime-telemetry-java8 (Java 8+)
38+
// or opentelemetry-runtime-telemetry-java17 (Java 17+, JFR-based)
39+
implementation(
40+
'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8:$otelVersion-alpha'
41+
)
3942
```
4043

4144
{{< /tab >}}
4245
{{< tab "Maven" >}}
4346

4447
```xml
4548
<dependency>
46-
<groupId>io.opentelemetry</groupId>
47-
<artifactId>opentelemetry-sdk</artifactId>
48-
</dependency>
49-
<dependency>
50-
<groupId>io.opentelemetry</groupId>
51-
<artifactId>opentelemetry-exporter-prometheus</artifactId>
49+
<groupId>io.prometheus</groupId>
50+
<artifactId>prometheus-metrics-otel-support</artifactId>
51+
<version>$version</version>
52+
<type>pom</type>
5253
</dependency>
5354

5455
<!-- Pick ONE of the following -->
5556
<!-- Java 8+ -->
5657
<dependency>
5758
<groupId>io.opentelemetry.instrumentation</groupId>
5859
<artifactId>opentelemetry-runtime-telemetry-java8</artifactId>
60+
<version>$otelVersion-alpha</version>
5961
</dependency>
6062
<!-- Java 17+ (adds JFR-based metrics) -->
6163
<!--
6264
<dependency>
6365
<groupId>io.opentelemetry.instrumentation</groupId>
6466
<artifactId>opentelemetry-runtime-telemetry-java17</artifactId>
67+
<version>$otelVersion-alpha</version>
6568
</dependency>
6669
-->
6770
```

‎docs/content/otel/support.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: OTel Support
3+
weight: 2
4+
---
5+
6+
The `prometheus-metrics-otel-support` module bundles the
7+
OpenTelemetry SDK and the Prometheus exporter into a single
8+
POM dependency.
9+
10+
Use this module when you want to combine OpenTelemetry
11+
instrumentations (e.g. JVM runtime metrics) with the
12+
Prometheus Java client on one `/metrics` endpoint.
13+
14+
## Dependencies
15+
16+
{{< tabs "otel-support-deps" >}}
17+
{{< tab "Gradle" >}}
18+
19+
```groovy
20+
implementation 'io.prometheus:prometheus-metrics-otel-support:$version'
21+
```
22+
23+
{{< /tab >}}
24+
{{< tab "Maven" >}}
25+
26+
```xml
27+
<dependency>
28+
<groupId>io.prometheus</groupId>
29+
<artifactId>prometheus-metrics-otel-support</artifactId>
30+
<version>$version</version>
31+
<type>pom</type>
32+
</dependency>
33+
```
34+
35+
{{< /tab >}}
36+
{{< /tabs >}}
37+
38+
This single dependency replaces:
39+
40+
- `io.opentelemetry:opentelemetry-sdk`
41+
- `io.opentelemetry:opentelemetry-exporter-prometheus`
42+
43+
## Use Cases
44+
45+
See [JVM Runtime Metrics]({{< relref "jvm-runtime-metrics.md" >}})
46+
for a concrete example of combining OTel JVM metrics with
47+
the Prometheus Java client.

‎examples/example-custom-buckets/pom.xml‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,44 @@
33
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
44
<modelVersion>4.0.0</modelVersion>
55

6-
<parent>
7-
<groupId>io.prometheus</groupId>
8-
<artifactId>examples</artifactId>
9-
<version>1.5.0-SNAPSHOT</version>
10-
</parent>
11-
6+
<groupId>io.prometheus</groupId>
127
<artifactId>example-custom-buckets</artifactId>
8+
<version>1.0-SNAPSHOT</version>
9+
10+
<properties>
11+
<maven.compiler.release>8</maven.compiler.release>
12+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
13+
</properties>
1314

1415
<name>Example - Custom Buckets</name>
1516
<description>
1617
End-to-End example of Native Histograms with Custom Buckets (NHCB): Java app -&gt; Prometheus -&gt; Grafana
1718
</description>
1819

20+
<dependencyManagement>
21+
<dependencies>
22+
<dependency>
23+
<groupId>io.prometheus</groupId>
24+
<artifactId>prometheus-metrics-bom</artifactId>
25+
<version>1.5.0-SNAPSHOT</version>
26+
<type>pom</type>
27+
<scope>import</scope>
28+
</dependency>
29+
</dependencies>
30+
</dependencyManagement>
31+
1932
<dependencies>
2033
<dependency>
2134
<groupId>io.prometheus</groupId>
2235
<artifactId>prometheus-metrics-core</artifactId>
23-
<version>${project.version}</version>
2436
</dependency>
2537
<dependency>
2638
<groupId>io.prometheus</groupId>
2739
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
28-
<version>${project.version}</version>
2940
</dependency>
3041
<dependency>
3142
<groupId>io.prometheus</groupId>
3243
<artifactId>prometheus-metrics-exporter-httpserver</artifactId>
33-
<version>${project.version}</version>
3444
</dependency>
3545
</dependencies>
3646

‎examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,39 +4,45 @@
44
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
55
<modelVersion>4.0.0</modelVersion>
66

7-
<parent>
8-
<groupId>io.prometheus</groupId>
9-
<artifactId>example-exemplars-tail-sampling</artifactId>
10-
<version>1.5.0-SNAPSHOT</version>
11-
</parent>
12-
7+
<groupId>io.prometheus</groupId>
138
<artifactId>example-greeting-service</artifactId>
9+
<version>1.0-SNAPSHOT</version>
10+
11+
<properties>
12+
<maven.compiler.release>17</maven.compiler.release>
13+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
14+
</properties>
1415

1516
<name>Example - OpenTelemetry Exemplars - Greeting Service</name>
1617
<description>
1718
Part of a distributed "Hello, World" REST service to show Exemplars with OpenTelemetry's distributed
1819
tracing
1920
</description>
2021

21-
<properties>
22-
<java.version>25</java.version>
23-
</properties>
22+
<dependencyManagement>
23+
<dependencies>
24+
<dependency>
25+
<groupId>io.prometheus</groupId>
26+
<artifactId>prometheus-metrics-bom</artifactId>
27+
<version>1.5.0-SNAPSHOT</version>
28+
<type>pom</type>
29+
<scope>import</scope>
30+
</dependency>
31+
</dependencies>
32+
</dependencyManagement>
2433

2534
<dependencies>
2635
<dependency>
2736
<groupId>io.prometheus</groupId>
2837
<artifactId>prometheus-metrics-core</artifactId>
29-
<version>${project.version}</version>
3038
</dependency>
3139
<dependency>
3240
<groupId>io.prometheus</groupId>
3341
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
34-
<version>${project.version}</version>
3542
</dependency>
3643
<dependency>
3744
<groupId>io.prometheus</groupId>
3845
<artifactId>prometheus-metrics-exporter-servlet-jakarta</artifactId>
39-
<version>${project.version}</version>
4046
</dependency>
4147
<dependency>
4248
<groupId>org.apache.tomcat.embed</groupId>

‎examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,39 +4,45 @@
44
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
55
<modelVersion>4.0.0</modelVersion>
66

7-
<parent>
8-
<groupId>io.prometheus</groupId>
9-
<artifactId>example-exemplars-tail-sampling</artifactId>
10-
<version>1.5.0-SNAPSHOT</version>
11-
</parent>
12-
7+
<groupId>io.prometheus</groupId>
138
<artifactId>example-hello-world-app</artifactId>
9+
<version>1.0-SNAPSHOT</version>
10+
11+
<properties>
12+
<maven.compiler.release>17</maven.compiler.release>
13+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
14+
</properties>
1415

1516
<name>Example - OpenTelemetry Exemplars - Hello World App</name>
1617
<description>
1718
Part of a distributed "Hello, World" REST service to show Exemplars with OpenTelemetry's distributed
1819
tracing
1920
</description>
2021

21-
<properties>
22-
<java.version>25</java.version>
23-
</properties>
22+
<dependencyManagement>
23+
<dependencies>
24+
<dependency>
25+
<groupId>io.prometheus</groupId>
26+
<artifactId>prometheus-metrics-bom</artifactId>
27+
<version>1.5.0-SNAPSHOT</version>
28+
<type>pom</type>
29+
<scope>import</scope>
30+
</dependency>
31+
</dependencies>
32+
</dependencyManagement>
2433

2534
<dependencies>
2635
<dependency>
2736
<groupId>io.prometheus</groupId>
2837
<artifactId>prometheus-metrics-core</artifactId>
29-
<version>${project.version}</version>
3038
</dependency>
3139
<dependency>
3240
<groupId>io.prometheus</groupId>
3341
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
34-
<version>${project.version}</version>
3542
</dependency>
3643
<dependency>
3744
<groupId>io.prometheus</groupId>
3845
<artifactId>prometheus-metrics-exporter-servlet-jakarta</artifactId>
39-
<version>${project.version}</version>
4046
</dependency>
4147
<dependency>
4248
<groupId>org.apache.tomcat.embed</groupId>

‎examples/example-exemplars-tail-sampling/pom.xml‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,16 @@
44
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
55
<modelVersion>4.0.0</modelVersion>
66

7-
<parent>
8-
<groupId>io.prometheus</groupId>
9-
<artifactId>examples</artifactId>
10-
<version>1.5.0-SNAPSHOT</version>
11-
</parent>
12-
7+
<groupId>io.prometheus</groupId>
138
<artifactId>example-exemplars-tail-sampling</artifactId>
9+
<version>1.0-SNAPSHOT</version>
1410
<packaging>pom</packaging>
1511

1612
<name>Example - Exemplars with OpenTelemetry's Tail Sampling</name>
1713
<description>
1814
Example project showing Exemplars with OpenTelemetry's Tail Sampling.
1915
</description>
2016

21-
<properties>
22-
<java.version>11</java.version>
23-
</properties>
24-
2517
<modules>
2618
<module>example-greeting-service</module>
2719
<module>example-hello-world-app</module>

‎examples/example-exporter-httpserver/pom.xml‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,34 +4,44 @@
44
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
55
<modelVersion>4.0.0</modelVersion>
66

7-
<parent>
8-
<groupId>io.prometheus</groupId>
9-
<artifactId>examples</artifactId>
10-
<version>1.5.0-SNAPSHOT</version>
11-
</parent>
12-
7+
<groupId>io.prometheus</groupId>
138
<artifactId>example-exporter-httpserver</artifactId>
9+
<version>1.0-SNAPSHOT</version>
10+
11+
<properties>
12+
<maven.compiler.release>8</maven.compiler.release>
13+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
14+
</properties>
1415

1516
<name>Example - HTTPServer Exporter</name>
1617
<description>
1718
Prometheus Metrics Example using the HTTPServer for exposing the metrics endpoint
1819
</description>
1920

21+
<dependencyManagement>
22+
<dependencies>
23+
<dependency>
24+
<groupId>io.prometheus</groupId>
25+
<artifactId>prometheus-metrics-bom</artifactId>
26+
<version>1.5.0-SNAPSHOT</version>
27+
<type>pom</type>
28+
<scope>import</scope>
29+
</dependency>
30+
</dependencies>
31+
</dependencyManagement>
32+
2033
<dependencies>
2134
<dependency>
2235
<groupId>io.prometheus</groupId>
2336
<artifactId>prometheus-metrics-core</artifactId>
24-
<version>${project.version}</version>
2537
</dependency>
2638
<dependency>
2739
<groupId>io.prometheus</groupId>
2840
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
29-
<version>${project.version}</version>
3041
</dependency>
3142
<dependency>
3243
<groupId>io.prometheus</groupId>
3344
<artifactId>prometheus-metrics-exporter-httpserver</artifactId>
34-
<version>${project.version}</version>
3545
</dependency>
3646
</dependencies>
3747

0 commit comments

Comments
 (0)