diff --git a/.mise/tasks/set-release-version-github-pages.sh b/.mise/tasks/set-release-version-github-pages.sh index 142d0eb82..2016373c8 100755 --- a/.mise/tasks/set-release-version-github-pages.sh +++ b/.mise/tasks/set-release-version-github-pages.sh @@ -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 '\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" {} + diff --git a/CLAUDE.md b/CLAUDE.md index 9c1c60571..406194944 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`). diff --git a/docs/content/otel/jvm-runtime-metrics.md b/docs/content/otel/jvm-runtime-metrics.md index 9015f7772..d61da1861 100644 --- a/docs/content/otel/jvm-runtime-metrics.md +++ b/docs/content/otel/jvm-runtime-metrics.md @@ -24,18 +24,21 @@ 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 >}} @@ -43,12 +46,10 @@ implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry ```xml - io.opentelemetry - opentelemetry-sdk - - - io.opentelemetry - opentelemetry-exporter-prometheus + io.prometheus + prometheus-metrics-otel-support + $version + pom @@ -56,12 +57,14 @@ implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry io.opentelemetry.instrumentation opentelemetry-runtime-telemetry-java8 + $otelVersion-alpha ``` diff --git a/docs/content/otel/support.md b/docs/content/otel/support.md new file mode 100644 index 000000000..e3b8cbe3a --- /dev/null +++ b/docs/content/otel/support.md @@ -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 + + io.prometheus + prometheus-metrics-otel-support + $version + pom + +``` + +{{< /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. diff --git a/examples/example-custom-buckets/pom.xml b/examples/example-custom-buckets/pom.xml index b7e104e5a..52ae60627 100644 --- a/examples/example-custom-buckets/pom.xml +++ b/examples/example-custom-buckets/pom.xml @@ -3,34 +3,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-custom-buckets + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - Custom Buckets End-to-End example of Native Histograms with Custom Buckets (NHCB): Java app -> Prometheus -> Grafana + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml b/examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml index b2e1006a4..532b7290b 100644 --- a/examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml +++ b/examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml @@ -4,13 +4,14 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - example-exemplars-tail-sampling - 1.5.0-SNAPSHOT - - + io.prometheus example-greeting-service + 1.0-SNAPSHOT + + + 17 + UTF-8 + Example - OpenTelemetry Exemplars - Greeting Service @@ -18,25 +19,30 @@ tracing - - 25 - + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-servlet-jakarta - ${project.version} org.apache.tomcat.embed diff --git a/examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml b/examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml index bccd6cb43..4c1702bbe 100644 --- a/examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml +++ b/examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml @@ -4,13 +4,14 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - example-exemplars-tail-sampling - 1.5.0-SNAPSHOT - - + io.prometheus example-hello-world-app + 1.0-SNAPSHOT + + + 17 + UTF-8 + Example - OpenTelemetry Exemplars - Hello World App @@ -18,25 +19,30 @@ tracing - - 25 - + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-servlet-jakarta - ${project.version} org.apache.tomcat.embed diff --git a/examples/example-exemplars-tail-sampling/pom.xml b/examples/example-exemplars-tail-sampling/pom.xml index 49b168955..ac4c6ccf5 100644 --- a/examples/example-exemplars-tail-sampling/pom.xml +++ b/examples/example-exemplars-tail-sampling/pom.xml @@ -4,13 +4,9 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-exemplars-tail-sampling + 1.0-SNAPSHOT pom Example - Exemplars with OpenTelemetry's Tail Sampling @@ -18,10 +14,6 @@ Example project showing Exemplars with OpenTelemetry's Tail Sampling. - - 11 - - example-greeting-service example-hello-world-app diff --git a/examples/example-exporter-httpserver/pom.xml b/examples/example-exporter-httpserver/pom.xml index f9ee206f0..ac9ed5e10 100644 --- a/examples/example-exporter-httpserver/pom.xml +++ b/examples/example-exporter-httpserver/pom.xml @@ -4,34 +4,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-exporter-httpserver + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - HTTPServer Exporter Prometheus Metrics Example using the HTTPServer for exposing the metrics endpoint + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/examples/example-exporter-multi-target/pom.xml b/examples/example-exporter-multi-target/pom.xml index ac13ff2a1..3b736ae36 100644 --- a/examples/example-exporter-multi-target/pom.xml +++ b/examples/example-exporter-multi-target/pom.xml @@ -4,34 +4,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-exporter-multi-target + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - HTTPServer Exporter Multi Target Prometheus Metrics Example for multi-target pattern implementation + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/examples/example-exporter-opentelemetry/pom.xml b/examples/example-exporter-opentelemetry/pom.xml index 8e8fa6891..a94e82ce4 100644 --- a/examples/example-exporter-opentelemetry/pom.xml +++ b/examples/example-exporter-opentelemetry/pom.xml @@ -4,34 +4,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-exporter-opentelemetry + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - OpenTelemetry Metrics Exporter Example of exposing metrics in OpenTelemetry format and pushing them to an OpenTelemetry collector + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-opentelemetry - ${project.version} diff --git a/examples/example-exporter-servlet-tomcat/pom.xml b/examples/example-exporter-servlet-tomcat/pom.xml index 26da0ae97..65b91b5ed 100644 --- a/examples/example-exporter-servlet-tomcat/pom.xml +++ b/examples/example-exporter-servlet-tomcat/pom.xml @@ -3,38 +3,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-exporter-servlet-tomcat + 1.0-SNAPSHOT + + + 17 + UTF-8 + Example - Servlet Exporter with Tomcat Prometheus Metrics Example using Embedded Tomcat and the Exporter Servlet - - 25 - + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-servlet-jakarta - ${project.version} org.apache.tomcat.embed diff --git a/examples/example-native-histogram/pom.xml b/examples/example-native-histogram/pom.xml index 5324ffb91..eedadf6fe 100644 --- a/examples/example-native-histogram/pom.xml +++ b/examples/example-native-histogram/pom.xml @@ -3,34 +3,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-native-histogram + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - Native Histogram End-to-End example of a Native histogram: Java app -> Prometheus -> Grafana + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/examples/example-otel-jvm-runtime-metrics/pom.xml b/examples/example-otel-jvm-runtime-metrics/pom.xml index 276a58f2f..6e7ad8213 100644 --- a/examples/example-otel-jvm-runtime-metrics/pom.xml +++ b/examples/example-otel-jvm-runtime-metrics/pom.xml @@ -4,13 +4,14 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-otel-jvm-runtime-metrics + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - OTel JVM Runtime Metrics @@ -19,10 +20,17 @@ + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + io.opentelemetry.instrumentation opentelemetry-instrumentation-bom-alpha - ${otel.instrumentation.version} + 2.24.0-alpha pom import @@ -33,20 +41,15 @@ io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} - - - io.opentelemetry - opentelemetry-sdk - io.opentelemetry - opentelemetry-exporter-prometheus + io.prometheus + prometheus-metrics-otel-support + pom io.opentelemetry.instrumentation diff --git a/examples/example-prometheus-properties/pom.xml b/examples/example-prometheus-properties/pom.xml index b02b8fa03..ac0279853 100644 --- a/examples/example-prometheus-properties/pom.xml +++ b/examples/example-prometheus-properties/pom.xml @@ -3,34 +3,44 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-prometheus-properties + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - prometheus.properties Example of runtime configuration with prometheus.properties + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus prometheus-metrics-core - ${project.version} io.prometheus prometheus-metrics-instrumentation-jvm - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/examples/example-simpleclient-bridge/pom.xml b/examples/example-simpleclient-bridge/pom.xml index f6d2c4207..82459eb0c 100644 --- a/examples/example-simpleclient-bridge/pom.xml +++ b/examples/example-simpleclient-bridge/pom.xml @@ -3,19 +3,32 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - - io.prometheus - examples - 1.5.0-SNAPSHOT - - + io.prometheus example-simpleclient-bridge + 1.0-SNAPSHOT + + + 8 + UTF-8 + Example - Simpleclient Bridge Prometheus Metrics Example of the Simpleclient Backwards Compatibility module + + + + io.prometheus + prometheus-metrics-bom + 1.5.0-SNAPSHOT + pom + import + + + + io.prometheus @@ -25,12 +38,10 @@ io.prometheus prometheus-metrics-simpleclient-bridge - ${project.version} io.prometheus prometheus-metrics-exporter-httpserver - ${project.version} diff --git a/pom.xml b/pom.xml index 30ebd46bc..a67440fef 100644 --- a/pom.xml +++ b/pom.xml @@ -60,6 +60,7 @@ prometheus-metrics-instrumentation-dropwizard prometheus-metrics-instrumentation-guava prometheus-metrics-simpleclient-bridge + prometheus-metrics-otel-support diff --git a/prometheus-metrics-bom/pom.xml b/prometheus-metrics-bom/pom.xml index a13398228..d8e9d7ada 100644 --- a/prometheus-metrics-bom/pom.xml +++ b/prometheus-metrics-bom/pom.xml @@ -119,6 +119,12 @@ prometheus-metrics-model ${project.version} + + io.prometheus + prometheus-metrics-otel-support + ${project.version} + pom + io.prometheus prometheus-metrics-simpleclient-bridge diff --git a/prometheus-metrics-otel-support/pom.xml b/prometheus-metrics-otel-support/pom.xml new file mode 100644 index 000000000..bea2ce649 --- /dev/null +++ b/prometheus-metrics-otel-support/pom.xml @@ -0,0 +1,52 @@ + + + 4.0.0 + + + io.prometheus + client_java + 1.5.0-SNAPSHOT + + + prometheus-metrics-otel-support + pom + + Prometheus Metrics OpenTelemetry Support + + Bundles the OpenTelemetry SDK and Prometheus exporter so that users + who want to combine OTel instrumentations with the Prometheus Java + client only need a single dependency. + + + + true + true + true + true + + + + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-bom-alpha + ${otel.instrumentation.version} + pom + import + + + + + + + io.opentelemetry + opentelemetry-sdk + + + io.opentelemetry + opentelemetry-exporter-prometheus + + +