Skip to content

Add OTel support module and make examples standalone #1868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zeitlinger merged 5 commits into from
Feb 13, 2026
Merged

Add OTel support module and make examples standalone #1868

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a9cb65d
Make example projects standalone (no parent POM)
zeitlinger Feb 12, 2026
eb58b80
add bom
zeitlinger Feb 12, 2026
67e1e3e
add pom
zeitlinger Feb 12, 2026
00b0456
Address PR review comments
zeitlinger Feb 13, 2026
f7b98b9
Replace hardcoded OTel version with $otelVersion-alpha marker
zeitlinger Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .mise/tasks/set-release-version-github-pages.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
#!/usr/bin/env bash

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

set -euox pipefail

version=$(git tag -l | grep 'v' | sort | tail -1 | sed 's/v//')
marker="\$version"
sed -i "s/$marker/$version/g" docs/content/getting-started/quickstart.md
otelVersion=$(grep -oP '<otel.instrumentation.version>\K[^<]+' pom.xml | sed 's/-alpha$//')

find ./docs/content -name '*.md' \
-exec sed -i "s/\$version/$version/g" {} + \
-exec sed -i "s/\$otelVersion/$otelVersion/g" {} +
6 changes: 6 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,12 @@ mise run lint:super-linter
- Integration tests are in `integration-tests/` and run during `verify` phase
- Acceptance tests use OATs framework: `mise run acceptance-test`

## Documentation

- Docs live under `docs/content/` and use `$version` as a placeholder for the library version
- 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)
- Use `$version` for the Prometheus client version and `$otelVersion-alpha` for the OTel instrumentation version — never hardcode them

## Java Version

Source compatibility: Java 8. Tests run on Java 25 (configured in `mise.toml`).
31 changes: 17 additions & 14 deletions docs/content/otel/jvm-runtime-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,44 +24,47 @@ OTel SDK wiring shown below.

## Dependencies

Use the [OTel Support]({{< relref "support.md" >}}) module
to pull in the OTel SDK and Prometheus exporter, then add
the runtime-telemetry instrumentation:

{{< tabs "jvm-runtime-deps" >}}
{{< tab "Gradle" >}}

```groovy
implementation 'io.opentelemetry:opentelemetry-sdk'
implementation 'io.opentelemetry:opentelemetry-exporter-prometheus'

// Pick ONE of the following:
// Java 8+:
implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8'
// Java 17+ (adds JFR-based metrics):
// implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java17'
implementation 'io.prometheus:prometheus-metrics-otel-support:$version'

// Use opentelemetry-runtime-telemetry-java8 (Java 8+)
// or opentelemetry-runtime-telemetry-java17 (Java 17+, JFR-based)
implementation(
'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8:$otelVersion-alpha'
)
```

{{< /tab >}}
{{< tab "Maven" >}}

```xml
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-prometheus</artifactId>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-otel-support</artifactId>
<version>$version</version>
<type>pom</type>
</dependency>

<!-- Pick ONE of the following -->
<!-- Java 8+ -->
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-runtime-telemetry-java8</artifactId>
<version>$otelVersion-alpha</version>
</dependency>
<!-- Java 17+ (adds JFR-based metrics) -->
<!--
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-runtime-telemetry-java17</artifactId>
<version>$otelVersion-alpha</version>
</dependency>
-->
```
Expand Down
47 changes: 47 additions & 0 deletions docs/content/otel/support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: OTel Support
weight: 2
---

The `prometheus-metrics-otel-support` module bundles the
OpenTelemetry SDK and the Prometheus exporter into a single
POM dependency.

Use this module when you want to combine OpenTelemetry
instrumentations (e.g. JVM runtime metrics) with the
Prometheus Java client on one `/metrics` endpoint.

## Dependencies

{{< tabs "otel-support-deps" >}}
{{< tab "Gradle" >}}

```groovy
implementation 'io.prometheus:prometheus-metrics-otel-support:$version'
```

{{< /tab >}}
{{< tab "Maven" >}}

```xml
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-otel-support</artifactId>
<version>$version</version>
<type>pom</type>
</dependency>
```

{{< /tab >}}
{{< /tabs >}}

This single dependency replaces:

- `io.opentelemetry:opentelemetry-sdk`
- `io.opentelemetry:opentelemetry-exporter-prometheus`

## Use Cases

See [JVM Runtime Metrics]({{< relref "jvm-runtime-metrics.md" >}})
for a concrete example of combining OTel JVM metrics with
the Prometheus Java client.
28 changes: 19 additions & 9 deletions examples/example-custom-buckets/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,44 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.prometheus</groupId>
<artifactId>examples</artifactId>
<version>1.5.0-SNAPSHOT</version>
</parent>

<groupId>io.prometheus</groupId>
<artifactId>example-custom-buckets</artifactId>
<version>1.0-SNAPSHOT</version>

<properties>
<maven.compiler.release>8</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

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

<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-bom</artifactId>
<version>1.5.0-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-exporter-httpserver</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>

Expand Down
30 changes: 18 additions & 12 deletions examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,45 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.prometheus</groupId>
<artifactId>example-exemplars-tail-sampling</artifactId>
<version>1.5.0-SNAPSHOT</version>
</parent>

<groupId>io.prometheus</groupId>
<artifactId>example-greeting-service</artifactId>
<version>1.0-SNAPSHOT</version>

<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

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

<properties>
<java.version>25</java.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-bom</artifactId>
<version>1.5.0-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-exporter-servlet-jakarta</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
Expand Down
30 changes: 18 additions & 12 deletions examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,45 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.prometheus</groupId>
<artifactId>example-exemplars-tail-sampling</artifactId>
<version>1.5.0-SNAPSHOT</version>
</parent>

<groupId>io.prometheus</groupId>
<artifactId>example-hello-world-app</artifactId>
<version>1.0-SNAPSHOT</version>

<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

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

<properties>
<java.version>25</java.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-bom</artifactId>
<version>1.5.0-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-exporter-servlet-jakarta</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
Expand Down
12 changes: 2 additions & 10 deletions examples/example-exemplars-tail-sampling/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,16 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.prometheus</groupId>
<artifactId>examples</artifactId>
<version>1.5.0-SNAPSHOT</version>
</parent>

<groupId>io.prometheus</groupId>
<artifactId>example-exemplars-tail-sampling</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>

<name>Example - Exemplars with OpenTelemetry's Tail Sampling</name>
<description>
Example project showing Exemplars with OpenTelemetry's Tail Sampling.
</description>

<properties>
<java.version>11</java.version>
</properties>

<modules>
<module>example-greeting-service</module>
<module>example-hello-world-app</module>
Expand Down
28 changes: 19 additions & 9 deletions examples/example-exporter-httpserver/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,44 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.prometheus</groupId>
<artifactId>examples</artifactId>
<version>1.5.0-SNAPSHOT</version>
</parent>

<groupId>io.prometheus</groupId>
<artifactId>example-exporter-httpserver</artifactId>
<version>1.0-SNAPSHOT</version>

<properties>
<maven.compiler.release>8</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<name>Example - HTTPServer Exporter</name>
<description>
Prometheus Metrics Example using the HTTPServer for exposing the metrics endpoint
</description>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-bom</artifactId>
<version>1.5.0-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>prometheus-metrics-exporter-httpserver</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>

Expand Down
Loading