From 7757e9d1eae544606dc0ac7ab10879d7e60d8cc7 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Mon, 11 Nov 2024 19:49:04 +0100 Subject: [PATCH] document how to use the BOM (#1198) * document how to use the BOM Signed-off-by: Gregor Zeitlinger * set latest release Signed-off-by: Gregor Zeitlinger * set latest release Signed-off-by: Gregor Zeitlinger --------- Signed-off-by: Gregor Zeitlinger --- .github/workflows/github-pages.yaml | 4 + docs/content/getting-started/quickstart.md | 98 +++++++++++++++++++-- scripts/set-release-version-github-pages.sh | 7 ++ 3 files changed, 102 insertions(+), 7 deletions(-) create mode 100755 scripts/set-release-version-github-pages.sh diff --git a/.github/workflows/github-pages.yaml b/.github/workflows/github-pages.yaml index 4e91f37f9..5082780ac 100644 --- a/.github/workflows/github-pages.yaml +++ b/.github/workflows/github-pages.yaml @@ -34,12 +34,16 @@ jobs: HUGO_VERSION: 0.115.4 steps: - uses: actions/checkout@v4 + with: + fetch-tags: 'true' - name: Set up JDK uses: actions/setup-java@v4 with: java-version: 17 distribution: temurin cache: 'maven' + - name: Set release version + run: ./scripts/set-release-version-github-pages.sh - name: Install Hugo CLI run: | wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ diff --git a/docs/content/getting-started/quickstart.md b/docs/content/getting-started/quickstart.md index 3bf5364d9..78ba388ee 100644 --- a/docs/content/getting-started/quickstart.md +++ b/docs/content/getting-started/quickstart.md @@ -1,6 +1,6 @@ --- title: Quickstart -weight: 1 +weight: 0 --- This tutorial shows the quickest way to get started with the Prometheus Java metrics library. @@ -15,9 +15,9 @@ We use the following dependencies: {{< tabs "uniqueid" >}} {{< tab "Gradle" >}} ``` -implementation 'io.prometheus:prometheus-metrics-core:1.0.0' -implementation 'io.prometheus:prometheus-metrics-instrumentation-jvm:1.0.0' -implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:1.0.0' +implementation 'io.prometheus:prometheus-metrics-core:$version' +implementation 'io.prometheus:prometheus-metrics-instrumentation-jvm:$version' +implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:$version' ``` {{< /tab >}} {{< tab "Maven" >}} @@ -25,17 +25,17 @@ implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:1.0.0' io.prometheus prometheus-metrics-core - 1.0.0 + $version io.prometheus prometheus-metrics-instrumentation-jvm - 1.0.0 + $version io.prometheus prometheus-metrics-exporter-httpserver - 1.0.0 + $version ``` {{< /tab >}} @@ -43,6 +43,90 @@ implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:1.0.0' There are alternative exporters as well, for example if you are using a Servlet container like Tomcat or Undertow you might want to use `prometheus-exporter-servlet-jakarta` rather than a standalone HTTP server. +# Dependency management + +A Bill of Material +([BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms)) +ensures that versions of dependencies (including transitive ones) are aligned. +This is especially important when using Spring Boot, which manages some of the dependencies of the project. + +You should omit the version number of the dependencies in your build file if you are using a BOM. + +{{< tabs "uniqueid" >}} +{{< tab "Gradle" >}} + +You have two ways to import a BOM. + +First, you can use the Gradle’s native BOM support by adding `dependencies`: + +```kotlin +import org.springframework.boot.gradle.plugin.SpringBootPlugin + +plugins { + id("java") + id("org.springframework.boot") version "3.2.O" // if you are using Spring Boot +} + +dependencies { + implementation(platform(SpringBootPlugin.BOM_COORDINATES)) // if you are using Spring Boot + implementation(platform("io.prometheus:prometheus-metrics-bom:$version")) +} +``` + +The other way with Gradle is to use `dependencyManagement`: + +```kotlin +plugins { + id("java") + id("org.springframework.boot") version "3.2.O" // if you are using Spring Boot + id("io.spring.dependency-management") version "1.1.0" // if you are using Spring Boot +} + +dependencyManagement { + imports { + mavenBom("io.prometheus:prometheus-metrics-bom:$version") + } +} +``` + +{{% alert title="Note" color="info" %}} + +Be careful not to mix up the different ways of configuring things with Gradle. +For example, don't use +`implementation(platform("io.prometheus:prometheus-metrics-bom:$version"))` +with the `io.spring.dependency-management` plugin. + +{{% /alert %}} + +{{< /tab >}} +{{< tab "Maven" >}} + +{{% alert title="Note" color="info" %}} + +Import the Prometheus Java metrics BOMs before any other BOMs in your +project. For example, if you import the `spring-boot-dependencies` BOM, you have +to declare it after the Prometheus Java metrics BOMs. + +{{% /alert %}} + +The following example shows how to import the Prometheus Java metrics BOMs using Maven: + +```xml + + + + io.prometheus + prometheus-metrics-bom + $version + pom + import + + + +``` + +{{< /tab >}} +{{< /tabs >}} # Example Application diff --git a/scripts/set-release-version-github-pages.sh b/scripts/set-release-version-github-pages.sh new file mode 100755 index 000000000..ed49852c1 --- /dev/null +++ b/scripts/set-release-version-github-pages.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash + +set -euo 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