Merge branch 'main' into add-caffeine-guava-instrumentation-to-bom

Author: zeitlinger

.github/workflows/build.yml

@@ -11,21 +11,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Set up JDK
-        uses: actions/setup-java@v4
+      - name: Setup ASDF
+        uses: equisoft-actions/with-asdf-vm@v2
+      - name: Cache local Maven repository
+        uses: actions/cache@v4
         with:
-          java-version: 17
-          distribution: temurin
-          cache: 'maven'
-      - name: Install Protoc
-        run: |    
-          VERSION=28.2
-          curl -sL -o protoc.zip https://github.com/protocolbuffers/protobuf/releases/download/v$VERSION/protoc-$VERSION-linux-x86_64.zip
-          sudo unzip protoc.zip -d /usr/local
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
       - name: Run the Maven verify phase
         env:
           PROTO_GENERATION: true
           REQUIRE_PROTO_UP_TO_DATE: true
         run: |
+          echo "Java version: $(java -version) in $(which java), Maven version: $(mvn -v)"
+          echo "JAVA_HOME: $JAVA_HOME"
           ./mvnw clean install
           ./mvnw javadoc:javadoc -P javadoc # just to check if javadoc is generated

.github/workflows/github-pages.yaml

@@ -34,12 +34,17 @@ jobs:
       HUGO_VERSION: 0.115.4
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-tags: 'true'
+          fetch-depth: 0
       - 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 \

.tool-versions

@@ -1 +1,2 @@
-java temurin-17.0.7+7
+java temurin-17.0.13+11
+protoc 28.3

docs/content/getting-started/quickstart.md

@@ -1,48 +1,134 @@
 ---
 title: Quickstart
-weight: 1
+weight: 0
 ---
 
 This tutorial shows the quickest way to get started with the Prometheus Java metrics library.
 
+{{< toc >}}
+
 # Dependencies
 
 We use the following dependencies:
 
 * `prometheus-metrics-core` is the actual metrics library.
 * `prometheus-metrics-instrumentation-jvm` provides out-of-the-box JVM metrics.
 * `prometheus-metrics-exporter-httpserver` is a standalone HTTP server for exposing Prometheus metrics.
-{{< tabs "uniqueid" >}}
+{{< tabs "deps" >}}
 {{< 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" >}}
 ```xml
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-core</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-exporter-httpserver</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 ```
 {{< /tab >}}
 {{< /tabs >}}
 
 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 "bom" >}}
+{{< 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")
+  }
+}
+```
+
+{{< hint type=note >}}
+
+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.
+
+{{< /hint >}}
+
+{{< /tab >}}
+{{< tab "Maven" >}}
+
+{{< hint type=note >}}
+
+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.
+
+{{< /hint >}}
+
+The following example shows how to import the Prometheus Java metrics BOMs using Maven:
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.prometheus</groupId>
+            <artifactId>prometheus-metrics-bom</artifactId>
+            <version>$version</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+{{< /tab >}}
+{{< /tabs >}}
 
 # Example Application
 

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

@@ -38,7 +38,7 @@
         <dependency>
             <groupId>org.apache.tomcat.embed</groupId>
             <artifactId>tomcat-embed-core</artifactId>
-            <version>11.0.0</version>
+            <version>11.0.1</version>
         </dependency>
     </dependencies>
 

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

@@ -38,7 +38,7 @@
         <dependency>
             <groupId>org.apache.tomcat.embed</groupId>
             <artifactId>tomcat-embed-core</artifactId>
-            <version>11.0.0</version>
+            <version>11.0.1</version>
         </dependency>
     </dependencies>
 

examples/example-exporter-servlet-tomcat/pom.xml

@@ -38,7 +38,7 @@
         <dependency>
             <groupId>org.apache.tomcat.embed</groupId>
             <artifactId>tomcat-embed-core</artifactId>
-            <version>11.0.0</version>
+            <version>11.0.1</version>
         </dependency>
     </dependencies>
 

integration-tests/it-exporter/it-exporter-servlet-tomcat-sample/pom.xml

@@ -33,7 +33,7 @@
         <dependency>
             <groupId>org.apache.tomcat.embed</groupId>
             <artifactId>tomcat-embed-core</artifactId>
-            <version>11.0.0</version>
+            <version>11.0.1</version>
         </dependency>
     </dependencies>
 

integration-tests/it-exporter/it-exporter-test/src/test/java/io/prometheus/metrics/it/exporter/test/ExporterIT.java

@@ -6,7 +6,7 @@
 
 import io.prometheus.client.it.common.LogConsumer;
 import io.prometheus.client.it.common.Volume;
-import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_28_2.Metrics;
+import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_28_3.Metrics;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;

prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/CounterTest.java

@@ -8,7 +8,7 @@
 import io.prometheus.metrics.core.exemplars.ExemplarSamplerConfigTestUtil;
 import io.prometheus.metrics.expositionformats.PrometheusProtobufWriter;
 import io.prometheus.metrics.expositionformats.TextFormatUtil;
-import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_28_2.Metrics;
+import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_28_3.Metrics;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot;
 import io.prometheus.metrics.model.snapshots.Exemplar;
 import io.prometheus.metrics.model.snapshots.Label;