\n"
+ " */\n"
+ )
+
+ for cls in (
+ "CounterBenchmark",
+ "HistogramBenchmark",
+ "TextFormatUtilBenchmark",
+ ):
+ fname = os.path.join(self.module_path, f"{cls}.java")
+ with open(fname, "w", encoding="utf-8") as f:
+ f.write(javadoc_pre)
+ f.write(f"public class {cls} {{}}\n")
+ self.files[cls] = fname
+
+ def tearDown(self):
+ self.tmpdir.cleanup()
+
+ def _read_pre_contents(self, path):
+ with open(path, "r", encoding="utf-8") as f:
+ content = f.read()
+ m = re.search(r"
\n([\s\S]*?)
", content)
+ return m.group(1) if m else ""
+
+ def test_update_only_inserts_matching_class_lines(self):
+ updated = update_pre_blocks_under_module(self.module_path, self.table)
+ # All three files should be updated
+ self.assertEqual(
+ {os.path.basename(p) for p in updated},
+ {
+ os.path.basename(self.files["CounterBenchmark"]),
+ os.path.basename(self.files["HistogramBenchmark"]),
+ os.path.basename(self.files["TextFormatUtilBenchmark"]),
+ },
+ )
+
+ # Verify CounterBenchmark file contains only CounterBenchmark lines
+ cb_pre = self._read_pre_contents(self.files["CounterBenchmark"])
+ self.assertIn("CounterBenchmark.codahaleIncNoLabels", cb_pre)
+ self.assertIn("CounterBenchmark.prometheusInc", cb_pre)
+ self.assertNotIn("HistogramBenchmark.prometheusNative", cb_pre)
+ self.assertNotIn("TextFormatUtilBenchmark.prometheusWriteToNull", cb_pre)
+
+ # Verify HistogramBenchmark contains only its line
+ hb_pre = self._read_pre_contents(self.files["HistogramBenchmark"])
+ self.assertIn("HistogramBenchmark.prometheusNative", hb_pre)
+ self.assertNotIn("CounterBenchmark.codahaleIncNoLabels", hb_pre)
+ self.assertNotIn("TextFormatUtilBenchmark.prometheusWriteToNull", hb_pre)
+
+ # Verify TextFormatUtilBenchmark contains only its line
+ tf_pre = self._read_pre_contents(self.files["TextFormatUtilBenchmark"])
+ self.assertIn("TextFormatUtilBenchmark.prometheusWriteToNull", tf_pre)
+ self.assertNotIn("CounterBenchmark.prometheusInc", tf_pre)
+ self.assertNotIn("HistogramBenchmark.prometheusNative", tf_pre)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.mise/tasks/update_benchmarks.py b/.mise/tasks/update_benchmarks.py
new file mode 100755
index 000000000..6f7f788dd
--- /dev/null
+++ b/.mise/tasks/update_benchmarks.py
@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+
+# [MISE] description="Run and update JMH benchmark outputs in the benchmarks module"
+# [MISE] alias="update-benchmarks"
+
+"""
+Run benchmarks for the `benchmarks` module, capture JMH text output, and update
+any
...
blocks containing "thrpt" under the `benchmarks/` module
+(files such as Java sources with embedded example output in javadocs).
+
+Usage: ./.mise/tasks/update_benchmarks.py [--mvnw ./mvnw] [--module benchmarks] [--java java]
+ [--jmh-args "-f 1 -wi 0 -i 1"]
+
+By default this will:
+ - run the maven wrapper to package the benchmarks: `./mvnw -pl benchmarks -am -DskipTests package`
+ - locate the shaded jar under `benchmarks/target/` (named containing "benchmarks")
+ - run `java -jar -rf text` (add extra JMH args with --jmh-args)
+ - parse the first JMH table (the block starting with the "Benchmark Mode" header)
+ - update all files under the `benchmarks/` directory which contain a `
` block with the substring "thrpt"
+
+This script is careful to preserve Javadoc comment prefixes like " * " when replacing the
+contents of the
block.
+"""
+
+import argparse
+import glob
+import os
+import re
+import shlex
+import subprocess
+import sys
+
+
+def run_cmd(cmd: list[str], cwd: str | None = None) -> str:
+ """Run a command, stream stdout/stderr to the console for progress, and return the full output.
+
+ This replaces the previous blocking subprocess.run approach so users can see build / JMH
+ progress in real time while the command runs.
+ """
+ try:
+ proc = subprocess.Popen(
+ cmd, cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
+ )
+ except FileNotFoundError:
+ # Helpful message if the executable is not found
+ print(f"Command not found: {cmd[0]}")
+ raise
+
+ output_lines: list[str] = []
+ try:
+ assert proc.stdout is not None
+ # Stream lines as they appear and capture them for returning
+ for line in proc.stdout:
+ # Print immediately so callers (and CI) can observe progress
+ print(line, end="", flush=True)
+ output_lines.append(line)
+ proc.wait()
+ except KeyboardInterrupt:
+ # If the user interrupts, ensure the child process is terminated
+ proc.kill()
+ proc.wait()
+ print("\nCommand interrupted by user.")
+ raise
+
+ output = "".join(output_lines)
+ if proc.returncode != 0:
+ print(
+ f"Command failed: {' '.join(cmd)}\nExit: {proc.returncode}\nOutput:\n{output}"
+ )
+ raise SystemExit(proc.returncode)
+ return output
+
+
+def build_benchmarks(mvnw: str, module: str) -> None:
+ print(f"Building Maven module '{module}' using {mvnw} (this may take a while)...")
+ cmd = [mvnw, "-pl", module, "-am", "-DskipTests", "clean", "package"]
+ run_cmd(cmd)
+ print("Build completed.")
+
+
+def find_benchmarks_jar(module: str) -> str:
+ pattern = os.path.join(module, "target", "*.jar")
+ jars = [p for p in glob.glob(pattern) if "original" not in p and p.endswith(".jar")]
+ # prefer jar whose basename contains module name
+ jars_pref = [j for j in jars if module in os.path.basename(j)]
+ chosen = (jars_pref or jars)[:1]
+ if not chosen:
+ raise FileNotFoundError(
+ f"No jar found in {os.path.join(module, 'target')} (tried: {pattern})"
+ )
+ jar = chosen[0]
+ print(f"Using jar: {jar}")
+ return jar
+
+
+def run_jmh(jar: str, java_cmd: str, extra_args: str | None) -> str:
+ args = [java_cmd, "-jar", jar, "-rf", "text"]
+ if extra_args:
+ args += shlex.split(extra_args)
+ print(f"Running JMH: {' '.join(args)}")
+ output = run_cmd(args)
+ print("JMH run completed.")
+ return output
+
+
+def extract_first_table(jmh_output: str) -> str:
+ # Try to extract the first table that starts with "Benchmark" header and continues until a blank line
+ m = re.search(r"(\nBenchmark\s+Mode[\s\S]*?)(?:\n\s*\n|\Z)", jmh_output)
+ if not m:
+ # fallback: collect all lines that contain 'thrpt' plus a header if present
+ lines = [line for line in jmh_output.splitlines() if "thrpt" in line]
+ if not lines:
+ raise ValueError('Could not find any "thrpt" lines in JMH output')
+ # try to find header
+ header = next(
+ (
+ line
+ for line in jmh_output.splitlines()
+ if line.startswith("Benchmark") and "Mode" in line
+ ),
+ "Benchmark Mode Cnt Score Error Units",
+ )
+ return header + "\n" + "\n".join(lines)
+ table = m.group(1).strip("\n")
+ # Ensure we return only the table lines (remove any leading iteration info lines that JMH sometimes prints)
+ # Normalize spaces: keep as-is
+ return table
+
+
+def filter_table_for_class(table: str, class_name: str) -> str | None:
+ """
+ Return a table string that contains only the header and the lines belonging to `class_name`.
+ If no matching lines are found, return None.
+ """
+ lines = table.splitlines()
+ # find header line index (starts with 'Benchmark' and contains 'Mode')
+ header_idx = None
+ for i, ln in enumerate(lines):
+ if ln.strip().startswith("Benchmark") and "Mode" in ln:
+ header_idx = i
+ break
+ header = (
+ lines[header_idx]
+ if header_idx is not None
+ else "Benchmark Mode Cnt Score Error Units"
+ )
+
+ matched = []
+ pattern = re.compile(r"^\s*" + re.escape(class_name) + r"\.")
+ for ln in lines[header_idx + 1 if header_idx is not None else 0 :]:
+ if "thrpt" in ln and pattern.search(ln):
+ matched.append(ln)
+
+ if not matched:
+ return None
+ return header + "\n" + "\n".join(matched)
+
+
+def update_pre_blocks_under_module(module: str, table: str) -> list[str]:
+ # Find files under module and update any
...
block that contains 'thrpt'
+ updated_files = []
+ for path in glob.glob(os.path.join(module, "**"), recursive=True):
+ if os.path.isdir(path):
+ continue
+ content = None
+ try:
+ with open(path, "r", encoding="utf-8") as f:
+ content = f.read()
+ except (OSError, UnicodeError):
+ pass
+ if content is None:
+ continue
+ # quick filter
+ if "
" not in content or "thrpt" not in content:
+ continue
+
+ original = content
+
+ # Determine the class name from the filename (e.g. TextFormatUtilBenchmark.java -> TextFormatUtilBenchmark)
+ base = os.path.basename(path)
+ class_name = os.path.splitext(base)[0]
+
+ # Build a filtered table for this class; if no matching lines, skip updating this file
+ filtered_table = filter_table_for_class(table, class_name)
+ if filtered_table is None:
+ # nothing to update for this class
+ continue
+
+ # Regex to find any line-starting Javadoc prefix like " * " before
+ # This will match patterns like: " *
...
" and capture the prefix (e.g. " * ")
+ pattern = re.compile(r"(?m)^(?P[ \t]*\*[ \t]*)
[\s\S]*?
")
+
+ def repl(m: re.Match, replacement_table: str = filtered_table) -> str:
+ prefix = m.group("prefix")
+ # Build the new block with the same prefix on each line
+ lines = replacement_table.splitlines()
+ replaced = prefix + "
\n"
+ for ln in lines:
+ replaced += prefix + ln.rstrip() + "\n"
+ replaced += prefix + "
"
+ return replaced
+
+ new_content, nsubs = pattern.subn(repl, content)
+ if nsubs > 0 and new_content != original:
+ with open(path, "w", encoding="utf-8") as f:
+ f.write(new_content)
+ updated_files.append(path)
+ print(f"Updated {path}: replaced {nsubs}
block(s)")
+ return updated_files
+
+
+def main(argv: list[str]):
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--mvnw", default="./mvnw", help="Path to maven wrapper")
+ parser.add_argument(
+ "--module", default="benchmarks", help="Module directory to build/run"
+ )
+ parser.add_argument("--java", default="java", help="Java command")
+ parser.add_argument(
+ "--jmh-args",
+ default="",
+ help='Extra arguments to pass to the JMH main (e.g. "-f 1 -wi 0 -i 1")',
+ )
+ args = parser.parse_args(argv)
+
+ build_benchmarks(args.mvnw, args.module)
+ jar = find_benchmarks_jar(args.module)
+ output = run_jmh(jar, args.java, args.jmh_args)
+
+ # Print a short preview of the JMH output
+ preview = "\n".join(output.splitlines()[:120])
+ print("\n--- JMH output preview ---")
+ print(preview)
+ print("--- end preview ---\n")
+
+ table = extract_first_table(output)
+
+ updated = update_pre_blocks_under_module(args.module, table)
+
+ if not updated:
+ print(
+ 'No files were updated (no
blocks with "thrpt" found under the module).'
+ )
+ else:
+ print("\nUpdated files:")
+ for p in updated:
+ print(" -", p)
+
+
+if __name__ == "__main__":
+ main(sys.argv[1:])
diff --git a/.mvn/wrapper/maven-wrapper.properties b/.mvn/wrapper/maven-wrapper.properties
index 12fbe1e90..e788e5e69 100644
--- a/.mvn/wrapper/maven-wrapper.properties
+++ b/.mvn/wrapper/maven-wrapper.properties
@@ -1,19 +1,2 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-wrapperVersion=3.3.2
distributionType=only-script
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..2949d8089
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,163 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working
+with code in this repository.
+
+## Build Commands
+
+This project uses Maven with mise for task automation.
+The Maven wrapper (`./mvnw`) is used for all builds.
+
+```bash
+# Full CI build (clean + install + all checks)
+mise run ci
+
+# Quick compile without tests or checks (fastest)
+mise run compile
+
+# Run unit tests only (skips formatting and coverage)
+mise run test
+
+# Run all tests including integration tests
+mise run test-all
+
+# Run a single test class
+./mvnw test -Dtest=CounterTest \
+ -Dcoverage.skip=true
+
+# Run a single test method
+./mvnw test -Dtest=CounterTest#testIncrement \
+ -Dcoverage.skip=true
+
+# Run tests in a specific module
+./mvnw test -pl prometheus-metrics-core \
+ -Dcoverage.skip=true
+
+# Regenerate protobuf classes (after protobuf dep update)
+mise run generate
+```
+
+## Architecture
+
+The library follows a layered architecture where metrics
+flow from core types through a registry to exporters:
+
+```text
+prometheus-metrics-core (user-facing API)
+ โ
+ โผ collect()
+prometheus-metrics-model (immutable snapshots)
+ โ
+ โผ
+prometheus-metrics-exposition-formats
+ โ
+ โผ
+Exporters (httpserver, servlet, pushgateway, otel)
+```
+
+### Key Modules
+
+- **prometheus-metrics-core**: User-facing metric types
+ (Counter, Gauge, Histogram, Summary, Info, StateSet).
+ All metrics implement `Collector` with `collect()`.
+- **prometheus-metrics-model**: Internal read-only immutable
+ snapshot types returned by `collect()`.
+ Contains `PrometheusRegistry` for metric registration.
+- **prometheus-metrics-config**: Runtime configuration via
+ properties files or system properties.
+- **prometheus-metrics-exposition-formats**: Converts
+ snapshots to Prometheus exposition formats.
+- **prometheus-metrics-tracer**: Exemplar support with
+ OpenTelemetry tracing integration.
+- **prometheus-metrics-simpleclient-bridge**: Allows legacy
+ simpleclient 0.16.0 metrics to work with the new registry.
+
+### Instrumentation Modules
+
+Pre-built instrumentations:
+`prometheus-metrics-instrumentation-jvm`, `-caffeine`,
+`-guava`, `-dropwizard`, `-dropwizard5`.
+
+## Code Style
+
+- **Formatter**: Google Java Format (enforced via flint)
+- **Line length**: 100 characters
+ (enforced for ALL files including Markdown, Java, YAML)
+- **Indentation**: 2 spaces
+- **Static analysis**: `Error Prone` with NullAway
+ (`io.prometheus.metrics` package)
+- **Logger naming**: Logger fields must be named `logger`
+ (not `log`, `LOG`, or `LOGGER`)
+- **Assertions in tests**: Use static imports from AssertJ
+ (`import static ...Assertions.assertThat`)
+- **Empty catch blocks**: Use `ignored` as the variable name
+- **Markdown code blocks**: Always specify language
+ (e.g., ` ```java`, ` ```bash`, ` ```text`)
+
+## Pull Requests
+
+- PR titles must use semantic/conventional prefixes, for example
+ `feat: ...`, `fix: ...`, `docs: ...`, `chore: ...`, or
+ `test: ...`.
+- Do not prefix PR titles with `[codex]`.
+- Match the PR title type to the primary user-facing change.
+
+## Linting
+
+Run `mise run lint:fix` before committing changes.
+If output includes `fixed`, keep those changes.
+If output includes `partial` or `review`, address the remaining issues and
+run `mise run lint:fix` again.
+
+Example output:
+flint: fixed: gofmt โ commit before pushing | partial: cargo-clippy
+
+**CRITICAL**: These checks MUST be run before creating any
+commits. CI will fail if these checks fail.
+
+### Java Files
+
+- **ALWAYS** run `mise run build` after modifying Java files
+ to ensure:
+ - Code formatting via flint
+ - Static analysis (`Error Prone` with NullAway)
+ - Checkstyle validation
+ - Build succeeds (tests are skipped;
+ run `mise run test` or `mise run test-all` for tests)
+
+## API Design
+
+- For internal or SDK-facing classes, prefer static factories and builders
+ over adding new public constructors.
+- Keep constructors non-public unless they are intentionally part of the
+ stable API.
+
+## Testing
+
+- JUnit 5 (Jupiter) with `@Test` annotations
+- AssertJ for fluent assertions
+- Mockito for mocking
+- **Test visibility**: Test classes and test methods must be
+ package-protected (no `public` modifier)
+- 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/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 000000000..81ba1f52a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,144 @@
+# Changelog
+
+## [1.8.0](https://github.com/prometheus/client_java/compare/v1.7.0...v1.8.0) (2026-06-11)
+
+
+### Features
+
+* Add custom labels to exemplars ([#2191](https://github.com/prometheus/client_java/issues/2191)) ([fd1f3e8](https://github.com/prometheus/client_java/commit/fd1f3e85177ec4d4e4922f22f3aa79dc2dd7e17e))
+* add MetricMetadata.Builder, deprecate wide constructors ([#2202](https://github.com/prometheus/client_java/issues/2202)) ([adeef32](https://github.com/prometheus/client_java/commit/adeef32f303a9dfadee9b7702b255db193c9c533))
+
+
+### Bug Fixes
+
+* Avoid unnuecessary exemplar allocations ([#2209](https://github.com/prometheus/client_java/issues/2209)) ([0b6a91f](https://github.com/prometheus/client_java/commit/0b6a91f2bafe0fa15f6fe828f315103d8c20f9f9))
+* **deps:** update spring boot to v4.1.0 ([#2213](https://github.com/prometheus/client_java/issues/2213)) ([df25c08](https://github.com/prometheus/client_java/commit/df25c0821605b7edf7b87b9874a65d3d529592a5))
+
+
+### Documentation
+
+* cover typed family descriptors and @StableApi since v1.6.1 ([#2181](https://github.com/prometheus/client_java/issues/2181)) ([7ca9f99](https://github.com/prometheus/client_java/commit/7ca9f99b8f1731315d2cf8f68247fc94174a8b3b))
+
+## [1.7.0](https://github.com/prometheus/client_java/compare/v1.6.1...v1.7.0) (2026-06-03)
+
+
+### Features
+
+* Add StableApi marker and API diff check ([#2168](https://github.com/prometheus/client_java/issues/2168)) ([768fd3a](https://github.com/prometheus/client_java/commit/768fd3a7aab5f11f3558a35c0d6257b5a217a078))
+* add typed metric family descriptors ([#2114](https://github.com/prometheus/client_java/issues/2114)) ([9c3b097](https://github.com/prometheus/client_java/commit/9c3b097f6842ffc08fb3a2ed00217c73a6c2b191))
+* track api-diff baseline via Renovate and store diffs in docs/apidiffs ([#2174](https://github.com/prometheus/client_java/issues/2174)) ([3adb890](https://github.com/prometheus/client_java/commit/3adb89078df4bf3d7739886612d4cf051176a6f3))
+
+
+### Bug Fixes
+
+* **deps:** update dependency com.github.ben-manes.caffeine:caffeine to v3.2.4 ([#2088](https://github.com/prometheus/client_java/issues/2088)) ([144eb61](https://github.com/prometheus/client_java/commit/144eb61030d412afe83631b8f341d2cb1595ab1c))
+* **deps:** update dependency io.dropwizard.metrics:metrics-core to v4.2.39 ([#2139](https://github.com/prometheus/client_java/issues/2139)) ([5817d13](https://github.com/prometheus/client_java/commit/5817d1395dc348b6634ea169264fd13f4ad56e82))
+* **deps:** update dependency io.dropwizard.metrics5:metrics-core to v5.0.7 ([#2140](https://github.com/prometheus/client_java/issues/2140)) ([261c451](https://github.com/prometheus/client_java/commit/261c4510eefe156ad688e019b9239cfcfd39bd2b))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.28.0-alpha ([#2126](https://github.com/prometheus/client_java/issues/2126)) ([b62b5d0](https://github.com/prometheus/client_java/commit/b62b5d0ab4b8d3a1335286bd3d36e8c9ac5aa269))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.28.0-alpha ([#2127](https://github.com/prometheus/client_java/issues/2127)) ([e11ce3d](https://github.com/prometheus/client_java/commit/e11ce3de19daf5acd2f73ffb90c96689c172f3c3))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.28.1-alpha ([#2132](https://github.com/prometheus/client_java/issues/2132)) ([b09be38](https://github.com/prometheus/client_java/commit/b09be3882f0ad95ff299db41d706a2e52faa7525))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.28.1-alpha ([#2133](https://github.com/prometheus/client_java/issues/2133)) ([a241c16](https://github.com/prometheus/client_java/commit/a241c165927d3cbb91b97eedd52de9c9eff595d0))
+* **deps:** update dependency org.apache.tomcat.embed:tomcat-embed-core to v11.0.22 ([#2099](https://github.com/prometheus/client_java/issues/2099)) ([22125c5](https://github.com/prometheus/client_java/commit/22125c5f531467030793fc48cb2308ff14bbcaa7))
+* **deps:** update jetty monorepo to v12.1.10 ([#2169](https://github.com/prometheus/client_java/issues/2169)) ([ddd3991](https://github.com/prometheus/client_java/commit/ddd3991096d409a3e58ae2003ce13457a51b8876))
+* **deps:** update jetty monorepo to v12.1.9 ([#2102](https://github.com/prometheus/client_java/issues/2102)) ([04bee70](https://github.com/prometheus/client_java/commit/04bee70efff866f8c4966643926905c28a4eae3a))
+* **deps:** update protobuf ([#2129](https://github.com/prometheus/client_java/issues/2129)) ([320538a](https://github.com/prometheus/client_java/commit/320538a09efad128c6d80bcc3d6eecca394603db))
+* Reduce allocations for classic histogram buckets ([#2081](https://github.com/prometheus/client_java/issues/2081)) ([edd160a](https://github.com/prometheus/client_java/commit/edd160ab93254c80250d7cf58a1dcb399fef67a1))
+* restore legacy suffix compatibility ([#2100](https://github.com/prometheus/client_java/issues/2100)) ([b2ae70f](https://github.com/prometheus/client_java/commit/b2ae70ffd4ac0830fb567319beae9d1c3ad8bc2f))
+* restore reserved suffix stripping in `PrometheusNaming.sanitizeMetricName()` ([#2124](https://github.com/prometheus/client_java/issues/2124)) ([2d0f508](https://github.com/prometheus/client_java/commit/2d0f508efd2f5e009b6f09f6a9ccb451cf9f3b6f))
+
+
+### Performance Improvements
+
+* Refactored sorting to use optimized sort algorithms ([#2161](https://github.com/prometheus/client_java/issues/2161)) ([25b94fc](https://github.com/prometheus/client_java/commit/25b94fc16273659892af0132cedb71f57597adf7))
+
+
+### Documentation
+
+* clarify downstream adapter validation requirements ([#2101](https://github.com/prometheus/client_java/issues/2101)) ([ef8c75c](https://github.com/prometheus/client_java/commit/ef8c75cf352bddd0d3a2052c3f1b0c8b6103a6f4))
+* Document OM2 ([#2059](https://github.com/prometheus/client_java/issues/2059)) ([45d753c](https://github.com/prometheus/client_java/commit/45d753c418f005fbb17bf7caca3dc94655717687))
+* document PushGateway shading workaround ([#2106](https://github.com/prometheus/client_java/issues/2106)) ([8ca0eb8](https://github.com/prometheus/client_java/commit/8ca0eb8d79b800ad8d7a08f10762ed631f4f2a70))
+
+## [1.6.1](https://github.com/prometheus/client_java/compare/v1.6.0...v1.6.1) (2026-04-27)
+
+> Note: With the OM2 metric-name preservation fix in this release, OpenMetrics 2.0 can now be
+> tested. It is still in progress and not ready for general use yet.
+
+### Bug Fixes
+
+* Preserve original metric names in OM2 output ([#2058](https://github.com/prometheus/client_java/issues/2058)) ([59a7a6d](https://github.com/prometheus/client_java/commit/59a7a6d4d5a9eb31c33167764b11ba96d6625b74))
+
+
+### Documentation
+
+* clarify 1.6.0 release notes ([#2062](https://github.com/prometheus/client_java/issues/2062)) ([9e5d591](https://github.com/prometheus/client_java/commit/9e5d591f4c2e8e0d39ce5141ac14fff057b09c67))
+* Document semantic PR title guidance ([#2060](https://github.com/prometheus/client_java/issues/2060)) ([7277889](https://github.com/prometheus/client_java/commit/727788942cccbecfa57d75eee9fb3e942083a95e))
+
+## [1.6.0](https://github.com/prometheus/client_java/compare/v1.5.1...v1.6.0) (2026-04-25)
+
+> Note: OpenMetrics 2.0 support is still in progress and not ready for general use yet.
+>
+> As part of the OM2 work, metric-name suffix handling moved from metric creation time to scrape
+> time. A positive side effect is that metric names are now more flexible across the board, for
+> example names ending in suffixes like `_total` are accepted where they were previously rejected.
+> To keep the Prometheus and OM1 output unambiguous, the registry tracks claimed exposition names
+> and still rejects registrations that would collide at scrape time.
+>
+> Downstream adapter libraries that implement `MultiCollector` need their registration-time
+> metadata to match the metric families they emit at scrape time. When upgrading to 1.6.0+, adapter
+> registration metadata needs to stay aligned with emitted names, types, label names, and suffix
+> behavior under the new collision model.
+> See also: [Validation at registration only](docs/content/getting-started/registry.md#validation-at-registration-only)
+>
+> | Example | Before 1.6.0 | Since 1.6.0 | Reason |
+> | --- | --- | --- | --- |
+> | `Gauge("foo_total")` | Rejected | Allowed | Not breaking because this previously failed at registration, so no working setup changes behavior, and safe because `_total` suffix expansion applies to counters, not gauges. |
+> | `Counter("events_total")` | Rejected | Allowed | Not breaking because the OM1 output is still `events_total`; only the builder now accepts the name. |
+> | `Gauge("foo_total")` + `Histogram("foo")` | Rejected | Allowed | Not breaking because this combination used to be blocked even though the exposed names do not overlap. |
+> | `Gauge("events_total")` + `Counter("events")` | Rejected | Rejected | Not breaking because the ambiguous OM1 output would still expose two `events_total` series. |
+> | `Gauge("foo_count")` + `Histogram("foo")` | Allowed | Rejected | Intentionally breaking because the old behavior could expose a conflicting `foo_count` name at scrape time. |
+
+### Features
+
+* Relax metric name validation in Dropwizard5 ([#1985](https://github.com/prometheus/client_java/issues/1985)) ([deb782f](https://github.com/prometheus/client_java/commit/deb782f9fce60ffb1308a98b661c0a1ccb79a82b))
+
+
+### Bug Fixes
+
+* **deps:** update dependency com.google.guava:guava to v33.6.0-jre ([#2021](https://github.com/prometheus/client_java/issues/2021)) ([1382693](https://github.com/prometheus/client_java/commit/13826930b9c2f566040a6929090ef23c94e81796))
+* **deps:** update dependency commons-io:commons-io to v2.22.0 ([#2044](https://github.com/prometheus/client_java/issues/2044)) ([9e05c1d](https://github.com/prometheus/client_java/commit/9e05c1d56b7b0de17ba5aaaa300eb6433cc70824))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.27.0-alpha ([#2022](https://github.com/prometheus/client_java/issues/2022)) ([30ac534](https://github.com/prometheus/client_java/commit/30ac534d860fb7c60a1e7835723a6cf0035ea7f7))
+* **deps:** update dependency io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha to v2.27.0-alpha ([#2023](https://github.com/prometheus/client_java/issues/2023)) ([2d51a32](https://github.com/prometheus/client_java/commit/2d51a3251f6943cf1b03ba9ea8778ff052f83ef9))
+* **deps:** update dependency io.prometheus:prometheus-metrics-bom to v1.5.1 ([#2004](https://github.com/prometheus/client_java/issues/2004)) ([650ce4b](https://github.com/prometheus/client_java/commit/650ce4b677f2ca65f5877e77260e403fa85533db))
+* **deps:** update dependency org.apache.tomcat.embed:tomcat-embed-core to v11.0.21 ([#2005](https://github.com/prometheus/client_java/issues/2005)) ([7a36df7](https://github.com/prometheus/client_java/commit/7a36df7151e55adafd5bb5a72af81fd7bf8f1133))
+* **deps:** update dependency org.springframework.boot:spring-boot-starter-parent to v4.0.5 ([#2006](https://github.com/prometheus/client_java/issues/2006)) ([0106c18](https://github.com/prometheus/client_java/commit/0106c18adffd6d3e829f73979917bdf7cc5f53dd))
+* **deps:** update dependency org.springframework.boot:spring-boot-starter-parent to v4.0.6 ([#2046](https://github.com/prometheus/client_java/issues/2046)) ([40a9db8](https://github.com/prometheus/client_java/commit/40a9db868805e36fbaa0f9ac3d02becb17104cd0))
+* **deps:** update jetty monorepo to v12.1.8 ([#2007](https://github.com/prometheus/client_java/issues/2007)) ([acab5b2](https://github.com/prometheus/client_java/commit/acab5b213e7661818470716158b3cfe67caae9da))
+* **deps:** update protobuf ([#2024](https://github.com/prometheus/client_java/issues/2024)) ([8e2214e](https://github.com/prometheus/client_java/commit/8e2214e0a3ac2fe8a9194d9519dcee10f6c9a694))
+* pass release tag as input to deploy workflow ([#1982](https://github.com/prometheus/client_java/issues/1982)) ([165c921](https://github.com/prometheus/client_java/commit/165c921c2508e073baa8f403b30e536ba9b43df9))
+* pin grafana/otel-lgtm to 0.7.2 in OATs acceptance test ([#1992](https://github.com/prometheus/client_java/issues/1992)) ([f17ad9a](https://github.com/prometheus/client_java/commit/f17ad9ad9be2ed0a8519db094f9d8fe9a8a83c48))
+* stabilize flaky timer and thread count tests ([#1973](https://github.com/prometheus/client_java/issues/1973)) ([ce5867b](https://github.com/prometheus/client_java/commit/ce5867b3e25e10c68a6face275732b994a80ec98))
+* trigger Maven deploy from release-please via workflow_dispatch ([#1981](https://github.com/prometheus/client_java/issues/1981)) ([698f956](https://github.com/prometheus/client_java/commit/698f9565e825cdb0f58d2782131cb152cc13894a))
+
+## [1.5.1](https://github.com/prometheus/client_java/compare/v1.5.0...v1.5.1) (2026-03-20)
+
+
+### Bug Fixes
+
+* **deps:** update dependency io.prometheus:prometheus-metrics-bom to v1.5.0 ([#1877](https://github.com/prometheus/client_java/issues/1877)) ([043fc57](https://github.com/prometheus/client_java/commit/043fc5742752fdc2f67f0219418030a190c53bde))
+* **deps:** update dependency org.springframework.boot:spring-boot-starter-parent to v4.0.3 ([#1900](https://github.com/prometheus/client_java/issues/1900)) ([0d800d0](https://github.com/prometheus/client_java/commit/0d800d0a91578e48f34909472c183174fdf1d83e))
+* **deps:** update jetty monorepo to v12.1.7 ([#1932](https://github.com/prometheus/client_java/issues/1932)) ([5bd3b79](https://github.com/prometheus/client_java/commit/5bd3b7932f454f3ed2cf55f26d6e1e1908d9ad16))
+* **deps:** update junit-framework monorepo to v6.0.3 ([#1880](https://github.com/prometheus/client_java/issues/1880)) ([05ad751](https://github.com/prometheus/client_java/commit/05ad751a40053f11eae90b9e6cbd741814ca71a7))
+* exclude standalone examples from `mise run format` ([#1931](https://github.com/prometheus/client_java/issues/1931)) ([537fb88](https://github.com/prometheus/client_java/commit/537fb88aae4048ab36041268f902afbbdce54a96))
+* fix release-please PR title pattern and permissions ([#1978](https://github.com/prometheus/client_java/issues/1978)) ([d737978](https://github.com/prometheus/client_java/commit/d7379780f1351a1521c8d93d0544bffce49d02a6))
+* Handle empty datapoints in otel exporter ([#1898](https://github.com/prometheus/client_java/issues/1898)) ([59c8552](https://github.com/prometheus/client_java/commit/59c8552f3d67c06d82344383b45e07fea8ed88b9))
+* inline set-version logic in build-release.sh ([#1884](https://github.com/prometheus/client_java/issues/1884)) ([c050435](https://github.com/prometheus/client_java/commit/c050435a4153046c72d158991c4c8e064dfb24ec))
+* reduce lychee retries to avoid compounding GitHub 429s ([#1940](https://github.com/prometheus/client_java/issues/1940)) ([cc17d6e](https://github.com/prometheus/client_java/commit/cc17d6e4346c9d51e054010fddc75cf8935cbc7d))
+* remove version manipulation from build-release.sh ([#1886](https://github.com/prometheus/client_java/issues/1886)) ([93e2b6d](https://github.com/prometheus/client_java/commit/93e2b6da48abc03ba7d96ffff5020ab73c1ee8c1))
+* trigger Maven deploy on release-please published events ([#1966](https://github.com/prometheus/client_java/issues/1966)) ([643d0e7](https://github.com/prometheus/client_java/commit/643d0e70c274e2a55024611c73a53545a65e94a0))
+* use /tree/ instead of /blob/ for directory URL ([#1944](https://github.com/prometheus/client_java/issues/1944)) ([b81332e](https://github.com/prometheus/client_java/commit/b81332e3a09e465f956f118a2403e64b83771ae5))
+* use maven release type for release-please ([#1967](https://github.com/prometheus/client_java/issues/1967)) ([ff3bd2d](https://github.com/prometheus/client_java/commit/ff3bd2d329acdb6761044846559c353a526c0384))
+
+
+### Documentation
+
+* document DCO sign-off requirement for contributions ([#1937](https://github.com/prometheus/client_java/issues/1937)) ([0860e77](https://github.com/prometheus/client_java/commit/0860e7742b08ab019d129ea24c348191c3f9e0da))
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..6b5e23414
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,3 @@
+
+
+@AGENTS.md
diff --git a/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 000000000..1f70593ce
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1,4 @@
+# https://help.github.com/articles/about-codeowners/
+# https://git-scm.com/docs/gitignore#_pattern_format
+
+* @fstab @dhoard @zeitlinger @jaydeluca
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 50d60bfcc..1b42bfaf4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,12 +12,73 @@ Prometheus uses GitHub to manage reviews of pull requests.
This will avoid unnecessary work and surely give you and us a good deal
of inspiration.
+## Pull Request Titles
+
+Use a [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)-style
+title for pull requests:
+
+```text
+[optional scope]:
+```
+
+For example: `fix(metrics): handle empty scrapes`. Common types include `feat`, `fix`,
+`docs`, `test`, `refactor`, `perf`, `build`, `ci`, `chore`, and `revert`.
+
+## Signing Off Commits
+
+Every commit must include a `Signed-off-by` line, as required by the
+[Developer Certificate of Origin (DCO)](https://developercertificate.org/).
+
+Sign off each commit by passing `--signoff` (or `-s`) to `git commit`:
+
+```bash
+git commit --signoff -m "Your commit message"
+```
+
+To sign off only the most recent commit, use `--amend`:
+
+```bash
+git commit --amend --signoff --no-edit
+```
+
+To sign off multiple commits, rebase (replace `N` with the number of commits):
+
+```bash
+git rebase --signoff HEAD~N
+```
+
+Then force-push the branch:
+
+```bash
+git push --force-with-lease
+```
+
## Formatting
-This repository uses [Google Java Format](https://github.com/google/google-java-format) to format
-the code.
+This repository uses flint to run formatting and lint checks.
+
+Run all the linters:
+
+`mise run lint`
+
+To autofix linting issues:
+
+`mise run lint:fix`
+
+### Pre-commit Hook (Optional)
-Run `./mvnw spotless:apply` to format the code (only changed files) before committing.
+Run `mise run setup:pre-commit-hook` to install a git pre-commit hook
+that auto-lints changed files before each commit.
+This requires native lint tools,
+which you can install with `mise run setup:native-lint-tools`.
+These are optional but catch formatting and lint issues before CI.
+
+## API Design
+
+For internal or SDK-facing classes, prefer static factories and builders over
+adding new public constructors. Constructors are difficult to evolve
+compatibly, so keep them non-public unless they are intentionally part of the
+stable API.
## Running Tests
@@ -29,21 +90,18 @@ If you're getting errors when running tests:
### Running native tests
```shell
-mise --env native test
+mise --cd .mise/envs/native run native-test
```
### Avoid failures while running tests
-- Use `-Dspotless.check.skip=true` to skip the formatting check during development.
- Use `-Dcoverage.skip=true` to skip the coverage check during development.
-- Use `-Dcheckstyle.skip=true` to skip the checkstyle check during development.
- Use `-Dwarnings=-nowarn` to skip the warnings during development.
Combine all with
```shell
-./mvnw install -DskipTests -Dspotless.check.skip=true -Dcoverage.skip=true \
- -Dcheckstyle.skip=true -Dwarnings=-nowarn
+./mvnw install -DskipTests -Dcoverage.skip=true -Dwarnings=-nowarn
```
or simply
@@ -52,12 +110,34 @@ or simply
mise run compile
```
+## Version Numbers in Examples
+
+Example `pom.xml` files (under `examples/`) should reference the latest
+**released** version, not a SNAPSHOT. After each release, Renovate
+updates these versions automatically.
+
+Only use a SNAPSHOT version in an example when it demonstrates a new
+feature that has not been released yet.
+
## Updating the Protobuf Java Classes
+The generated protobuf `Metrics.java` lives in a versioned package
+(e.g., `...generated.com_google_protobuf_4_33_5`) that changes with each
+protobuf release. A stable extending class at
+`...generated/Metrics.java` reexports all types so that consumer code
+only imports from the version-free package. On protobuf upgrades only
+the `extends` clause in the stable class changes.
+
In the failing PR from renovate, run:
```shell
mise run generate
```
-Add the new `Metrics.java` to Git and commit it.
+The script will:
+
+1. Re-generate the protobuf sources with the new version.
+2. Update the versioned package name in all Java files
+ (including the stable `Metrics.java` extends clause).
+
+Add the updated files to Git and commit them.
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
index cf0a885eb..a247eb14a 100644
--- a/MAINTAINERS.md
+++ b/MAINTAINERS.md
@@ -2,5 +2,9 @@
- Fabian Stรคber @fstab
- Doug Hoard @dhoard
-- Tom Wilkie @tomwilkie
- Gregor Zeitlinger @zeitlinger
+- Jay DeLuca @jaydeluca
+
+## Emeritus
+
+- Tom Wilkie @tomwilkie
diff --git a/README.md b/README.md
index a6b611db2..daef2ac3d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,15 @@
# Prometheus Java Metrics Library
-[](https://github.com/prometheus/client_java/actions/workflows/build.yml) # editorconfig-checker-disable-line
+
+
+[![Build][build-badge]][build-workflow]
+
+
+
+
+
+[build-badge]: https://github.com/prometheus/client_java/actions/workflows/build.yml/badge.svg
+[build-workflow]: https://github.com/prometheus/client_java/actions/workflows/build.yml
## Documentation
diff --git a/RELEASING.md b/RELEASING.md
index d98ae94b1..c5ae0ed4b 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,20 +1,79 @@
-# Create a Release
+# Releasing Instructions for Prometheus Java Client
-1. Go to
-2. Click on "Choose a tag", enter the tag name (e.g. `v0.1.0`), and click "Create a new tag".
-3. Click on "Generate release notes" to auto-generate the release notes based on the commits since
- the last release.
-4. Click on "Publish release".
+Releases are automated via
+[release-please](https://github.com/googleapis/release-please).
-## If the GPG key expired
+## How It Works
+
+1. Commits to `main` using
+ [Conventional Commits](https://www.conventionalcommits.org/) are
+ tracked by release-please.
+2. Release-please maintains a release PR that accumulates changes and
+ updates the changelog.
+3. When the release PR is merged, release-please creates a GitHub
+ release and a `vX.Y.Z` tag.
+4. The tag triggers the existing `release.yml` workflow, which deploys
+ to Maven Central.
+5. After tagging, release-please opens a follow-up PR to bump the
+ SNAPSHOT version in all `pom.xml` files.
+
+## Patch Release (default)
+
+Simply merge the release PR โ release-please bumps the patch version
+by default (e.g. `1.5.0` -> `1.5.1`).
+
+## Minor or Major Release
+
+Add a `release-as: X.Y.0` footer to any commit on `main`:
+
+```text
+feat: add new feature
+
+release-as: 1.6.0
+```
+
+Alternatively, edit the release PR title to
+`chore(main): release 1.6.0`.
+
+## Before the Release
+
+If there have been significant changes since the last release, update
+the benchmarks before merging the release PR:
+
+```shell
+mise run update-benchmarks
+```
+
+## If the Sonatype Central Token is Invalid
+
+The release workflow verifies the token before deploy. If it fails:
+
+1. Sign in at and open
+ View Account -> Generate User Token.
+2. Copy the `username` and `password` values from the snippet.
+3. Update the secrets:
+ -
+ -
+4. Verify locally:
+
+ ```shell
+ curl -i -u "$USER:$PASS" \
+ "https://central.sonatype.com/api/v1/publisher/status?id=test"
+ ```
+
+ `{"error":{"message":"Invalid token"}}` means the token is still
+ wrong. Any other response (including 404 for the test id) means the
+ token works.
+
+## If the GPG Key Expired
1. Generate a new key:
-2. Distribute the
- key:
-3. use `gpg --armor --export-secret-keys YOUR_ID` to
- export ([docs](https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#gpg))
-4. Update the
- passphrase:
-5. Update the GPG
- key:
+2. Distribute the key:
+
+3. Use `gpg --armor --export-secret-keys YOUR_ID` to export
+ ([docs](https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#gpg))
+4. Update the passphrase:
+
+5. Update the GPG key:
+
diff --git a/SECURITY.md b/SECURITY.md
index fed02d85c..5e6f976db 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -3,4 +3,4 @@
The Prometheus security policy, including how to report vulnerabilities, can be
found here:
-
+[https://prometheus.io/docs/operating/security/](https://prometheus.io/docs/operating/security/)
diff --git a/benchmarks/README.md b/benchmarks/README.md
index cb445c7bf..3859eddea 100644
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@ -2,6 +2,27 @@
## How to Run
+### Running benchmarks
+
+Run benchmarks and update the results in the Javadoc of the benchmark classes:
+
+```shell
+mise run update-benchmarks
+```
+
+### Different benchmark configurations
+
+The full benchmark suite takes approximately 2 hours with JMH defaults.
+For faster iterations, use these preset configurations:
+
+| Command | Duration | Use Case |
+| ----------------------------- | -------- | ---------------------------------------- |
+| `mise run benchmark:quick` | ~10 min | Quick smoke test during development |
+| `mise run benchmark:standard` | ~60 min | CI/nightly runs with good accuracy |
+| `mise run benchmark:full` | ~2 hours | Full JMH defaults for release validation |
+
+### Running benchmarks manually
+
```shell
java -jar ./benchmarks/target/benchmarks.jar
```
@@ -12,12 +33,33 @@ Run only one specific benchmark:
java -jar ./benchmarks/target/benchmarks.jar CounterBenchmark
```
+### Custom JMH arguments
+
+You can pass custom JMH arguments:
+
+```shell
+# Quick run: 1 fork, 1 warmup iteration, 3 measurement iterations
+mise run update-benchmarks -- --jmh-args "-f 1 -wi 1 -i 3"
+
+# Standard CI: 3 forks, 3 warmup iterations, 5 measurement iterations
+mise run update-benchmarks -- --jmh-args "-f 3 -wi 3 -i 5"
+```
+
+JMH parameter reference:
+
+- `-f N`: Number of forks (JVM restarts)
+- `-wi N`: Number of warmup iterations
+- `-i N`: Number of measurement iterations
+- `-w Ns`: Warmup iteration time (default: 10s)
+- `-r Ns`: Measurement iteration time (default: 10s)
+
## Results
See Javadoc of the benchmark classes:
-- [CounterBenchmark](https://github.com/prometheus/client_java/blob/1.0.x/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java)
-- [HistogramBenchmark](https://github.com/prometheus/client_java/blob/1.0.x/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java)
+- [CounterBenchmark](https://github.com/prometheus/client_java/blob/main/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java)
+- [HistogramBenchmark](https://github.com/prometheus/client_java/blob/main/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java)
+- [TextFormatUtilBenchmark](https://github.com/prometheus/client_java/blob/main/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/TextFormatUtilBenchmark.java)
## What Prometheus Java client optimizes for
@@ -31,6 +73,14 @@ Prometheus client Java metrics support concurrent updates and scrapes. This show
multiple threads recording data in shared
metrics.
+## Test the benchmark creation script
+
+To test the benchmark creation script, run:
+
+```shell
+python ./.mise/tasks/test_update-benchmarks.py
+```
+
## Archive
The `src/main/archive/` directory contains the old benchmarks from 0.16.0 and earlier. It will be
diff --git a/benchmarks/pom.xml b/benchmarks/pom.xml
index 3cdbc09c0..6d8c9c5c4 100644
--- a/benchmarks/pom.xml
+++ b/benchmarks/pom.xml
@@ -1,14 +1,11 @@
-
+4.0.0io.prometheusclient_java
- 1.4.0-SNAPSHOT
+ 1.8.1-SNAPSHOTbenchmarks
@@ -23,6 +20,7 @@
0.16.03.0.2true
+ true
@@ -85,8 +83,8 @@
1.81.8
-
-
+
+
-parameters
@@ -110,8 +108,7 @@
benchmarks
-
+ io.prometheus.metrics.benchmarks.BenchmarkRunner
diff --git a/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java b/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java
index f3c1e9309..d8b75e437 100644
--- a/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java
+++ b/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/CounterBenchmark.java
@@ -18,21 +18,20 @@
import org.openjdk.jmh.annotations.Threads;
/**
- * Results on a machine with dedicated Core i7 1265U:
+ * Results on a machine with dedicated Ubuntu 24.04 LTS, AMD Ryzenโข 9 7900 ร 24, 96.0 GiB RAM:
*
*
*
* Prometheus counters are faster than counters of other libraries. For example, incrementing a
diff --git a/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java b/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java
index a8e6bddb1..41b7097db 100644
--- a/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java
+++ b/benchmarks/src/main/java/io/prometheus/metrics/benchmarks/HistogramBenchmark.java
@@ -17,15 +17,15 @@
import org.openjdk.jmh.annotations.Threads;
/**
- * Results on a machine with dedicated Core i7 1265U:
+ * Results on a machine with dedicated Ubuntu 24.04 LTS, AMD Ryzenโข 9 7900 ร 24, 96.0 GiB RAM:
*
*
Use this on public or protected types to publish the type and its members. Use it on
+ * individual constructors, methods, and fields when only part of a public type is stable.
+ */
+@Documented
+@Retention(CLASS)
+@Target({TYPE, CONSTRUCTOR, METHOD, FIELD})
+public @interface StableApi {}
diff --git a/prometheus-metrics-bom/pom.xml b/prometheus-metrics-bom/pom.xml
index 242710819..c2c9935f7 100644
--- a/prometheus-metrics-bom/pom.xml
+++ b/prometheus-metrics-bom/pom.xml
@@ -1,12 +1,11 @@
-
+4.0.0io.prometheusclient_java_parent
- 1.4.0-SNAPSHOT
+ 1.8.1-SNAPSHOT../prometheus-metrics-parent/pom.xml
@@ -18,12 +17,13 @@
Bill of Materials for the Prometheus Metrics library
-
- true
-
-
+
+ io.prometheus
+ prometheus-metrics-annotations
+ ${project.version}
+ io.prometheusprometheus-metrics-config
@@ -119,6 +119,12 @@
prometheus-metrics-model${project.version}
+
+ io.prometheus
+ prometheus-metrics-otel-support
+ ${project.version}
+ pom
+ io.prometheusprometheus-metrics-simpleclient-bridge
diff --git a/prometheus-metrics-config/pom.xml b/prometheus-metrics-config/pom.xml
index 4546c3dc9..681f4a557 100644
--- a/prometheus-metrics-config/pom.xml
+++ b/prometheus-metrics-config/pom.xml
@@ -1,12 +1,11 @@
-
+4.0.0io.prometheusclient_java
- 1.4.0-SNAPSHOT
+ 1.8.1-SNAPSHOTprometheus-metrics-config
@@ -21,4 +20,19 @@
io.prometheus.metrics.config
+
+
+ io.prometheus
+ prometheus-metrics-annotations
+ ${project.version}
+ true
+
+
+ org.junit-pioneer
+ junit-pioneer
+ ${junit-pioneer.version}
+ test
+
+
+
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java
new file mode 100644
index 000000000..1d6bd37cf
--- /dev/null
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java
@@ -0,0 +1,87 @@
+package io.prometheus.metrics.config;
+
+import io.prometheus.metrics.annotations.StableApi;
+import javax.annotation.Nullable;
+
+@StableApi
+public enum EscapingScheme {
+ /** NO_ESCAPING indicates that a name will not be escaped. */
+ ALLOW_UTF8("allow-utf-8"),
+
+ /** UNDERSCORE_ESCAPING replaces all legacy-invalid characters with underscores. */
+ UNDERSCORE_ESCAPING("underscores"),
+
+ /**
+ * DOTS_ESCAPING is similar to UNDERSCORE_ESCAPING, except that dots are converted to `_dot_` and
+ * pre-existing underscores are converted to `__`.
+ */
+ DOTS_ESCAPING("dots"),
+
+ /**
+ * VALUE_ENCODING_ESCAPING prepends the name with `U__` and replaces all invalid characters with
+ * the Unicode value, surrounded by underscores. Single underscores are replaced with double
+ * underscores.
+ */
+ VALUE_ENCODING_ESCAPING("values");
+
+ private static final String ESCAPING_KEY = "escaping";
+
+ /** Default escaping scheme for names when not specified. */
+ public static final EscapingScheme DEFAULT = UNDERSCORE_ESCAPING;
+
+ public final String getValue() {
+ return value;
+ }
+
+ private final String value;
+
+ EscapingScheme(String value) {
+ this.value = value;
+ }
+
+ /**
+ * fromAcceptHeader returns an EscapingScheme depending on the Accept header. Iff the header
+ * contains an escaping=allow-utf-8 term, it will select NO_ESCAPING. If a valid "escaping" term
+ * exists, that will be used. Otherwise, the global default will be returned.
+ */
+ public static EscapingScheme fromAcceptHeader(@Nullable String acceptHeader) {
+ if (acceptHeader != null) {
+ for (String p : acceptHeader.split(";")) {
+ String[] toks = p.split("=");
+ if (toks.length != 2) {
+ continue;
+ }
+ String key = toks[0].trim();
+ String value = toks[1].trim();
+ if (key.equals(ESCAPING_KEY)) {
+ try {
+ return EscapingScheme.forString(value);
+ } catch (IllegalArgumentException e) {
+ // If the escaping parameter is unknown, ignore it.
+ return DEFAULT;
+ }
+ }
+ }
+ }
+ return DEFAULT;
+ }
+
+ static EscapingScheme forString(String value) {
+ switch (value) {
+ case "allow-utf-8":
+ return ALLOW_UTF8;
+ case "underscores":
+ return UNDERSCORE_ESCAPING;
+ case "dots":
+ return DOTS_ESCAPING;
+ case "values":
+ return VALUE_ENCODING_ESCAPING;
+ default:
+ throw new IllegalArgumentException("Unknown escaping scheme: " + value);
+ }
+ }
+
+ public String toHeaderFormat() {
+ return "; " + ESCAPING_KEY + "=" + value;
+ }
+}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExemplarsProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExemplarsProperties.java
index 017d67909..93190ef19 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExemplarsProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExemplarsProperties.java
@@ -1,23 +1,25 @@
package io.prometheus.metrics.config;
-import java.util.Map;
+import io.prometheus.metrics.annotations.StableApi;
+import javax.annotation.Nullable;
/** Properties starting with io.prometheus.exemplars */
+@StableApi
public class ExemplarsProperties {
private static final String PREFIX = "io.prometheus.exemplars";
- private static final String MIN_RETENTION_PERIOD_SECONDS = "minRetentionPeriodSeconds";
- private static final String MAX_RETENTION_PERIOD_SECONDS = "maxRetentionPeriodSeconds";
- private static final String SAMPLE_INTERVAL_MILLISECONDS = "sampleIntervalMilliseconds";
+ private static final String MIN_RETENTION_PERIOD_SECONDS = "min_retention_period_seconds";
+ private static final String MAX_RETENTION_PERIOD_SECONDS = "max_retention_period_seconds";
+ private static final String SAMPLE_INTERVAL_MILLISECONDS = "sample_interval_milliseconds";
- private final Integer minRetentionPeriodSeconds;
- private final Integer maxRetentionPeriodSeconds;
- private final Integer sampleIntervalMilliseconds;
+ @Nullable private final Integer minRetentionPeriodSeconds;
+ @Nullable private final Integer maxRetentionPeriodSeconds;
+ @Nullable private final Integer sampleIntervalMilliseconds;
private ExemplarsProperties(
- Integer minRetentionPeriodSeconds,
- Integer maxRetentionPeriodSeconds,
- Integer sampleIntervalMilliseconds) {
+ @Nullable Integer minRetentionPeriodSeconds,
+ @Nullable Integer maxRetentionPeriodSeconds,
+ @Nullable Integer sampleIntervalMilliseconds) {
this.minRetentionPeriodSeconds = minRetentionPeriodSeconds;
this.maxRetentionPeriodSeconds = maxRetentionPeriodSeconds;
this.sampleIntervalMilliseconds = sampleIntervalMilliseconds;
@@ -28,6 +30,7 @@ private ExemplarsProperties(
*
*
Default see {@code ExemplarSamplerConfig.DEFAULT_MIN_RETENTION_PERIOD_SECONDS}
*/
+ @Nullable
public Integer getMinRetentionPeriodSeconds() {
return minRetentionPeriodSeconds;
}
@@ -37,6 +40,7 @@ public Integer getMinRetentionPeriodSeconds() {
*
*
Default see {@code ExemplarSamplerConfig.DEFAULT_MAX_RETENTION_PERIOD_SECONDS}
*/
+ @Nullable
public Integer getMaxRetentionPeriodSeconds() {
return maxRetentionPeriodSeconds;
}
@@ -48,22 +52,23 @@ public Integer getMaxRetentionPeriodSeconds() {
*
*
Default see {@code ExemplarSamplerConfig.DEFAULT_SAMPLE_INTERVAL_MILLISECONDS}
*/
+ @Nullable
public Integer getSampleIntervalMilliseconds() {
return sampleIntervalMilliseconds;
}
/**
- * Note that this will remove entries from {@code properties}. This is because we want to know if
- * there are unused properties remaining after all properties have been loaded.
+ * Note that this will remove entries from {@code propertySource}. This is because we want to know
+ * if there are unused properties remaining after all properties have been loaded.
*/
- static ExemplarsProperties load(Map properties)
+ static ExemplarsProperties load(PropertySource propertySource)
throws PrometheusPropertiesException {
Integer minRetentionPeriodSeconds =
- Util.loadInteger(PREFIX + "." + MIN_RETENTION_PERIOD_SECONDS, properties);
+ Util.loadInteger(PREFIX, MIN_RETENTION_PERIOD_SECONDS, propertySource);
Integer maxRetentionPeriodSeconds =
- Util.loadInteger(PREFIX + "." + MAX_RETENTION_PERIOD_SECONDS, properties);
+ Util.loadInteger(PREFIX, MAX_RETENTION_PERIOD_SECONDS, propertySource);
Integer sampleIntervalMilliseconds =
- Util.loadInteger(PREFIX + "." + SAMPLE_INTERVAL_MILLISECONDS, properties);
+ Util.loadInteger(PREFIX, SAMPLE_INTERVAL_MILLISECONDS, propertySource);
Util.assertValue(
minRetentionPeriodSeconds,
@@ -108,9 +113,9 @@ public static Builder builder() {
public static class Builder {
- private Integer minRetentionPeriodSeconds;
- private Integer maxRetentionPeriodSeconds;
- private Integer sampleIntervalMilliseconds;
+ @Nullable private Integer minRetentionPeriodSeconds;
+ @Nullable private Integer maxRetentionPeriodSeconds;
+ @Nullable private Integer sampleIntervalMilliseconds;
private Builder() {}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterFilterProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterFilterProperties.java
index c2c3d48d3..999c2c8e8 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterFilterProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterFilterProperties.java
@@ -1,30 +1,32 @@
package io.prometheus.metrics.config;
+import io.prometheus.metrics.annotations.StableApi;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
-import java.util.Map;
+import javax.annotation.Nullable;
/** Properties starting with io.prometheus.exporter.filter */
+@StableApi
public class ExporterFilterProperties {
- public static final String METRIC_NAME_MUST_BE_EQUAL_TO = "metricNameMustBeEqualTo";
- public static final String METRIC_NAME_MUST_NOT_BE_EQUAL_TO = "metricNameMustNotBeEqualTo";
- public static final String METRIC_NAME_MUST_START_WITH = "metricNameMustStartWith";
- public static final String METRIC_NAME_MUST_NOT_START_WITH = "metricNameMustNotStartWith";
+ public static final String METRIC_NAME_MUST_BE_EQUAL_TO = "metric_name_must_be_equal_to";
+ public static final String METRIC_NAME_MUST_NOT_BE_EQUAL_TO = "metric_name_must_not_be_equal_to";
+ public static final String METRIC_NAME_MUST_START_WITH = "metric_name_must_start_with";
+ public static final String METRIC_NAME_MUST_NOT_START_WITH = "metric_name_must_not_start_with";
private static final String PREFIX = "io.prometheus.exporter.filter";
- private final List allowedNames;
- private final List excludedNames;
- private final List allowedPrefixes;
- private final List excludedPrefixes;
+ @Nullable private final List allowedNames;
+ @Nullable private final List excludedNames;
+ @Nullable private final List allowedPrefixes;
+ @Nullable private final List excludedPrefixes;
private ExporterFilterProperties(
- List allowedNames,
- List excludedNames,
- List allowedPrefixes,
- List excludedPrefixes) {
+ @Nullable List allowedNames,
+ @Nullable List excludedNames,
+ @Nullable List allowedPrefixes,
+ @Nullable List excludedPrefixes) {
this.allowedNames =
allowedNames == null ? null : Collections.unmodifiableList(new ArrayList<>(allowedNames));
this.excludedNames =
@@ -39,36 +41,40 @@ private ExporterFilterProperties(
: Collections.unmodifiableList(new ArrayList<>(excludedPrefixes));
}
+ @Nullable
public List getAllowedMetricNames() {
return allowedNames;
}
+ @Nullable
public List getExcludedMetricNames() {
return excludedNames;
}
+ @Nullable
public List getAllowedMetricNamePrefixes() {
return allowedPrefixes;
}
+ @Nullable
public List getExcludedMetricNamePrefixes() {
return excludedPrefixes;
}
/**
- * Note that this will remove entries from {@code properties}. This is because we want to know if
- * there are unused properties remaining after all properties have been loaded.
+ * Note that this will remove entries from {@code propertySource}. This is because we want to know
+ * if there are unused properties remaining after all properties have been loaded.
*/
- static ExporterFilterProperties load(Map properties)
+ static ExporterFilterProperties load(PropertySource propertySource)
throws PrometheusPropertiesException {
List allowedNames =
- Util.loadStringList(PREFIX + "." + METRIC_NAME_MUST_BE_EQUAL_TO, properties);
+ Util.loadStringList(PREFIX, METRIC_NAME_MUST_BE_EQUAL_TO, propertySource);
List excludedNames =
- Util.loadStringList(PREFIX + "." + METRIC_NAME_MUST_NOT_BE_EQUAL_TO, properties);
+ Util.loadStringList(PREFIX, METRIC_NAME_MUST_NOT_BE_EQUAL_TO, propertySource);
List allowedPrefixes =
- Util.loadStringList(PREFIX + "." + METRIC_NAME_MUST_START_WITH, properties);
+ Util.loadStringList(PREFIX, METRIC_NAME_MUST_START_WITH, propertySource);
List excludedPrefixes =
- Util.loadStringList(PREFIX + "." + METRIC_NAME_MUST_NOT_START_WITH, properties);
+ Util.loadStringList(PREFIX, METRIC_NAME_MUST_NOT_START_WITH, propertySource);
return new ExporterFilterProperties(
allowedNames, excludedNames, allowedPrefixes, excludedPrefixes);
}
@@ -79,10 +85,10 @@ public static Builder builder() {
public static class Builder {
- private List allowedNames;
- private List excludedNames;
- private List allowedPrefixes;
- private List excludedPrefixes;
+ @Nullable private List allowedNames;
+ @Nullable private List excludedNames;
+ @Nullable private List allowedPrefixes;
+ @Nullable private List excludedPrefixes;
private Builder() {}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterHttpServerProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterHttpServerProperties.java
index 6618ab88e..4f921c2ac 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterHttpServerProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterHttpServerProperties.java
@@ -1,31 +1,46 @@
package io.prometheus.metrics.config;
-import java.util.Map;
+import io.prometheus.metrics.annotations.StableApi;
+import javax.annotation.Nullable;
-/** Properties starting with io.prometheus.exporter.httpServer */
+/** Properties starting with io.prometheus.exporter.http_server */
+@StableApi
public class ExporterHttpServerProperties {
private static final String PORT = "port";
- private static final String PREFIX = "io.prometheus.exporter.httpServer";
- private final Integer port;
+ private static final String PREFER_UNCOMPRESSED_RESPONSE = "prefer_uncompressed_response";
+ private static final String PREFIX = "io.prometheus.exporter.http_server";
+ @Nullable private final Integer port;
+ private final boolean preferUncompressedResponse;
- private ExporterHttpServerProperties(Integer port) {
+ private ExporterHttpServerProperties(@Nullable Integer port, boolean preferUncompressedResponse) {
this.port = port;
+ this.preferUncompressedResponse = preferUncompressedResponse;
}
+ @Nullable
public Integer getPort() {
return port;
}
+ public boolean isPreferUncompressedResponse() {
+ return preferUncompressedResponse;
+ }
+
/**
- * Note that this will remove entries from {@code properties}. This is because we want to know if
- * there are unused properties remaining after all properties have been loaded.
+ * Note that this will remove entries from {@code propertySource}. This is because we want to know
+ * if there are unused properties remaining after all properties have been loaded.
*/
- static ExporterHttpServerProperties load(Map properties)
+ static ExporterHttpServerProperties load(PropertySource propertySource)
throws PrometheusPropertiesException {
- Integer port = Util.loadInteger(PREFIX + "." + PORT, properties);
+ Integer port = Util.loadInteger(PREFIX, PORT, propertySource);
Util.assertValue(port, t -> t > 0, "Expecting value > 0.", PREFIX, PORT);
- return new ExporterHttpServerProperties(port);
+
+ Boolean preferUncompressedResponse =
+ Util.loadBoolean(PREFIX, PREFER_UNCOMPRESSED_RESPONSE, propertySource);
+
+ return new ExporterHttpServerProperties(
+ port, preferUncompressedResponse != null && preferUncompressedResponse);
}
public static Builder builder() {
@@ -34,7 +49,8 @@ public static Builder builder() {
public static class Builder {
- private Integer port;
+ @Nullable private Integer port;
+ private boolean preferUncompressedResponse = false;
private Builder() {}
@@ -43,8 +59,13 @@ public Builder port(int port) {
return this;
}
+ public Builder preferUncompressedResponse(boolean preferUncompressedResponse) {
+ this.preferUncompressedResponse = preferUncompressedResponse;
+ return this;
+ }
+
public ExporterHttpServerProperties build() {
- return new ExporterHttpServerProperties(port);
+ return new ExporterHttpServerProperties(port, preferUncompressedResponse);
}
}
}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterOpenTelemetryProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterOpenTelemetryProperties.java
index 53acb6b14..8c0bdd5c7 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterOpenTelemetryProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterOpenTelemetryProperties.java
@@ -1,9 +1,38 @@
package io.prometheus.metrics.config;
+import io.prometheus.metrics.annotations.StableApi;
import java.util.HashMap;
import java.util.Map;
+import javax.annotation.Nullable;
-// TODO: JavaDoc is currently only in OpenTelemetryExporter.Builder. Look there for reference.
+/**
+ * Properties for configuring the OpenTelemetry exporter.
+ *
+ *
These properties can be configured via {@code prometheus.properties}, system properties, or
+ * programmatically.
+ *
+ *
All properties are prefixed with {@code io.prometheus.exporter.opentelemetry}.
+ *
+ *
See OpenTelemetry's OTEL_EXPORTER_OTLP_METRICS_ENDPOINT.
+ */
public Builder endpoint(String endpoint) {
this.endpoint = endpoint;
return this;
}
- /** Add a request header. Call multiple times to add multiple headers. */
+ /**
+ * Add an HTTP header to be applied to outgoing requests. Call multiple times to add multiple
+ * headers.
+ *
+ *
See OpenTelemetry's OTEL_EXPORTER_OTLP_HEADERS.
+ */
public Builder header(String name, String value) {
this.headers.put(name, value);
return this;
}
+ /**
+ * The interval between the start of two export attempts. Default is 60 seconds.
+ *
+ *
Like OpenTelemetry's OTEL_METRIC_EXPORT_INTERVAL
+ * (which defaults to 60000 milliseconds), but specified in seconds rather than milliseconds.
+ */
public Builder intervalSeconds(int intervalSeconds) {
if (intervalSeconds <= 0) {
throw new IllegalArgumentException(intervalSeconds + ": Expecting intervalSeconds > 0");
@@ -172,6 +260,13 @@ public Builder intervalSeconds(int intervalSeconds) {
return this;
}
+ /**
+ * The timeout for outgoing requests. Default is 10.
+ *
+ *
Like OpenTelemetry's OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
+ * but in seconds rather than milliseconds.
+ */
public Builder timeoutSeconds(int timeoutSeconds) {
if (timeoutSeconds <= 0) {
throw new IllegalArgumentException(timeoutSeconds + ": Expecting timeoutSeconds > 0");
@@ -180,31 +275,77 @@ public Builder timeoutSeconds(int timeoutSeconds) {
return this;
}
+ /**
+ * The {@code service.name} resource attribute.
+ *
+ *
If not explicitly specified, {@code client_java} will try to initialize it with a
+ * reasonable default, like the JAR file name.
+ *
+ *
See {@code service.name} in OpenTelemetry's Resource
+ * Semantic Conventions.
+ */
public Builder serviceName(String serviceName) {
this.serviceName = serviceName;
return this;
}
+ /**
+ * The {@code service.namespace} resource attribute.
+ *
+ *
See {@code service.namespace} in OpenTelemetry's Resource
+ * Semantic Conventions.
+ */
public Builder serviceNamespace(String serviceNamespace) {
this.serviceNamespace = serviceNamespace;
return this;
}
+ /**
+ * The {@code service.instance.id} resource attribute.
+ *
+ *
See {@code service.instance.id} in OpenTelemetry's Resource
+ * Semantic Conventions.
+ */
public Builder serviceInstanceId(String serviceInstanceId) {
this.serviceInstanceId = serviceInstanceId;
return this;
}
+ /**
+ * The {@code service.version} resource attribute.
+ *
+ *
See {@code service.version} in OpenTelemetry's Resource
+ * Semantic Conventions.
+ */
public Builder serviceVersion(String serviceVersion) {
this.serviceVersion = serviceVersion;
return this;
}
+ /**
+ * Add a resource attribute. Call multiple times to add multiple resource attributes.
+ *
+ *
See OpenTelemetry's OTEL_RESOURCE_ATTRIBUTES.
+ */
public Builder resourceAttribute(String name, String value) {
this.resourceAttributes.put(name, value);
return this;
}
+ /**
+ * When {@code true}, metric names are preserved as-is (including suffixes like {@code _total}).
+ * When {@code false} (default), standard OTel name normalization is applied.
+ */
+ public Builder preserveNames(boolean preserveNames) {
+ this.preserveNames = preserveNames;
+ return this;
+ }
+
public ExporterOpenTelemetryProperties build() {
return new ExporterOpenTelemetryProperties(
protocol,
@@ -216,7 +357,8 @@ public ExporterOpenTelemetryProperties build() {
serviceNamespace,
serviceInstanceId,
serviceVersion,
- resourceAttributes);
+ resourceAttributes,
+ preserveNames);
}
}
}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
index d35f970ff..a1c67266a 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
@@ -1,24 +1,26 @@
package io.prometheus.metrics.config;
-import java.util.Map;
+import io.prometheus.metrics.annotations.StableApi;
+import javax.annotation.Nullable;
/** Properties starting with io.prometheus.exporter */
+@StableApi
public class ExporterProperties {
- private static final String INCLUDE_CREATED_TIMESTAMPS = "includeCreatedTimestamps";
+ private static final String INCLUDE_CREATED_TIMESTAMPS = "include_created_timestamps";
// milliseconds is the default - we only provide a boolean flag to avoid a breaking change
- private static final String PROMETHEUS_TIMESTAMPS_IN_MS = "prometheusTimestampsInMs";
- private static final String EXEMPLARS_ON_ALL_METRIC_TYPES = "exemplarsOnAllMetricTypes";
+ private static final String PROMETHEUS_TIMESTAMPS_IN_MS = "prometheus_timestamps_in_ms";
+ private static final String EXEMPLARS_ON_ALL_METRIC_TYPES = "exemplars_on_all_metric_types";
private static final String PREFIX = "io.prometheus.exporter";
- private final Boolean includeCreatedTimestamps;
- private final Boolean prometheusTimestampsInMs;
- private final Boolean exemplarsOnAllMetricTypes;
+ @Nullable private final Boolean includeCreatedTimestamps;
+ @Nullable private final Boolean prometheusTimestampsInMs;
+ @Nullable private final Boolean exemplarsOnAllMetricTypes;
private ExporterProperties(
- Boolean includeCreatedTimestamps,
- Boolean prometheusTimestampsInMs,
- Boolean exemplarsOnAllMetricTypes) {
+ @Nullable Boolean includeCreatedTimestamps,
+ @Nullable Boolean prometheusTimestampsInMs,
+ @Nullable Boolean exemplarsOnAllMetricTypes) {
this.includeCreatedTimestamps = includeCreatedTimestamps;
this.prometheusTimestampsInMs = prometheusTimestampsInMs;
this.exemplarsOnAllMetricTypes = exemplarsOnAllMetricTypes;
@@ -43,17 +45,16 @@ public boolean getExemplarsOnAllMetricTypes() {
}
/**
- * Note that this will remove entries from {@code properties}. This is because we want to know if
- * there are unused properties remaining after all properties have been loaded.
+ * Note that this will remove entries from {@code propertySource}. This is because we want to know
+ * if there are unused properties remaining after all properties have been loaded.
*/
- static ExporterProperties load(Map properties)
+ static ExporterProperties load(PropertySource propertySource)
throws PrometheusPropertiesException {
Boolean includeCreatedTimestamps =
- Util.loadBoolean(PREFIX + "." + INCLUDE_CREATED_TIMESTAMPS, properties);
- Boolean timestampsInMs =
- Util.loadBoolean(PREFIX + "." + PROMETHEUS_TIMESTAMPS_IN_MS, properties);
+ Util.loadBoolean(PREFIX, INCLUDE_CREATED_TIMESTAMPS, propertySource);
+ Boolean timestampsInMs = Util.loadBoolean(PREFIX, PROMETHEUS_TIMESTAMPS_IN_MS, propertySource);
Boolean exemplarsOnAllMetricTypes =
- Util.loadBoolean(PREFIX + "." + EXEMPLARS_ON_ALL_METRIC_TYPES, properties);
+ Util.loadBoolean(PREFIX, EXEMPLARS_ON_ALL_METRIC_TYPES, propertySource);
return new ExporterProperties(
includeCreatedTimestamps, timestampsInMs, exemplarsOnAllMetricTypes);
}
@@ -64,8 +65,8 @@ public static Builder builder() {
public static class Builder {
- private Boolean includeCreatedTimestamps;
- private Boolean exemplarsOnAllMetricTypes;
+ @Nullable private Boolean includeCreatedTimestamps;
+ @Nullable private Boolean exemplarsOnAllMetricTypes;
boolean prometheusTimestampsInMs;
private Builder() {}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java
index 8aafba3a4..e97ade191 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java
@@ -1,24 +1,43 @@
package io.prometheus.metrics.config;
-import java.util.Map;
+import io.prometheus.metrics.annotations.StableApi;
+import java.time.Duration;
+import javax.annotation.Nullable;
+@StableApi
public class ExporterPushgatewayProperties {
private static final String ADDRESS = "address";
private static final String JOB = "job";
private static final String SCHEME = "scheme";
+ private static final String ESCAPING_SCHEME = "escaping_scheme";
+ private static final String READ_TIMEOUT = "read_timeout_seconds";
+ private static final String CONNECT_TIMEOUT = "connect_timeout_seconds";
private static final String PREFIX = "io.prometheus.exporter.pushgateway";
- private final String scheme;
- private final String address;
- private final String job;
+ @Nullable private final String scheme;
+ @Nullable private final String address;
+ @Nullable private final String job;
+ @Nullable private final EscapingScheme escapingScheme;
+ @Nullable private final Duration connectTimeout;
+ @Nullable private final Duration readTimeout;
- private ExporterPushgatewayProperties(String address, String job, String scheme) {
+ private ExporterPushgatewayProperties(
+ @Nullable String address,
+ @Nullable String job,
+ @Nullable String scheme,
+ @Nullable EscapingScheme escapingScheme,
+ @Nullable Duration connectTimeout,
+ @Nullable Duration readTimeout) {
this.address = address;
this.job = job;
this.scheme = scheme;
+ this.escapingScheme = escapingScheme;
+ this.connectTimeout = connectTimeout;
+ this.readTimeout = readTimeout;
}
/** Address of the Pushgateway in the form {@code host:port}. Default is {@code localhost:9091} */
+ @Nullable
public String getAddress() {
return address;
}
@@ -27,6 +46,7 @@ public String getAddress() {
* {@code job} label for metrics being pushed. Default is the name of the JAR file that is
* running.
*/
+ @Nullable
public String getJob() {
return job;
}
@@ -35,27 +55,122 @@ public String getJob() {
* Scheme to be used when pushing metrics to the pushgateway. Must be "http" or "https". Default
* is "http".
*/
+ @Nullable
public String getScheme() {
return scheme;
}
+ /** Escaping scheme to be used when pushing metric data to the pushgateway. */
+ @Nullable
+ public EscapingScheme getEscapingScheme() {
+ return escapingScheme;
+ }
+
+ /** Connection timeout for connections to the Pushgateway. */
+ @Nullable
+ public Duration getConnectTimeout() {
+ return connectTimeout;
+ }
+
+ /** Read timeout for connections to the Pushgateway. */
+ @Nullable
+ public Duration getReadTimeout() {
+ return readTimeout;
+ }
+
/**
- * Note that this will remove entries from {@code properties}. This is because we want to know if
- * there are unused properties remaining after all properties have been loaded.
+ * Note that this will remove entries from {@code propertySource}. This is because we want to know
+ * if there are unused properties remaining after all properties have been loaded.
*/
- static ExporterPushgatewayProperties load(Map properties)
+ static ExporterPushgatewayProperties load(PropertySource propertySource)
throws PrometheusPropertiesException {
- String address = Util.loadString(PREFIX + "." + ADDRESS, properties);
- String job = Util.loadString(PREFIX + "." + JOB, properties);
- String scheme = Util.loadString(PREFIX + "." + SCHEME, properties);
+ String address = Util.loadString(PREFIX, ADDRESS, propertySource);
+ String job = Util.loadString(PREFIX, JOB, propertySource);
+ String scheme = Util.loadString(PREFIX, SCHEME, propertySource);
+ String escapingScheme = Util.loadString(PREFIX, ESCAPING_SCHEME, propertySource);
+ Duration connectTimeout = Util.loadOptionalDuration(PREFIX, CONNECT_TIMEOUT, propertySource);
+ Duration readTimeout = Util.loadOptionalDuration(PREFIX, READ_TIMEOUT, propertySource);
+
if (scheme != null) {
if (!scheme.equals("http") && !scheme.equals("https")) {
throw new PrometheusPropertiesException(
- String.format(
- "%s.%s: Illegal value. Expecting 'http' or 'https'. Found: %s",
- PREFIX, SCHEME, scheme));
+ Util.invalidValueMessage(
+ PREFIX + "." + SCHEME, "Illegal value. Expecting 'http' or 'https'."));
}
}
- return new ExporterPushgatewayProperties(address, job, scheme);
+
+ return new ExporterPushgatewayProperties(
+ address, job, scheme, parseEscapingScheme(escapingScheme), connectTimeout, readTimeout);
+ }
+
+ private static @Nullable EscapingScheme parseEscapingScheme(@Nullable String scheme) {
+ if (scheme == null) {
+ return null;
+ }
+ switch (scheme) {
+ case "allow-utf-8":
+ return EscapingScheme.ALLOW_UTF8;
+ case "values":
+ return EscapingScheme.VALUE_ENCODING_ESCAPING;
+ case "underscores":
+ return EscapingScheme.UNDERSCORE_ESCAPING;
+ case "dots":
+ return EscapingScheme.DOTS_ESCAPING;
+ default:
+ throw new PrometheusPropertiesException(
+ Util.invalidValueMessage(
+ PREFIX + "." + ESCAPING_SCHEME,
+ "Illegal value. Expecting 'allow-utf-8', 'values', 'underscores', or 'dots'."));
+ }
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static class Builder {
+ @Nullable private String address;
+ @Nullable private String job;
+ @Nullable private String scheme;
+ @Nullable private EscapingScheme escapingScheme;
+ @Nullable private Duration connectTimeout;
+ @Nullable private Duration readTimeout;
+
+ private Builder() {}
+
+ public Builder address(String address) {
+ this.address = address;
+ return this;
+ }
+
+ public Builder job(String job) {
+ this.job = job;
+ return this;
+ }
+
+ public Builder scheme(String scheme) {
+ this.scheme = scheme;
+ return this;
+ }
+
+ public Builder escapingScheme(EscapingScheme escapingScheme) {
+ this.escapingScheme = escapingScheme;
+ return this;
+ }
+
+ public Builder connectTimeout(Duration connectTimeout) {
+ this.connectTimeout = connectTimeout;
+ return this;
+ }
+
+ public Builder readTimeout(Duration readTimeout) {
+ this.readTimeout = readTimeout;
+ return this;
+ }
+
+ public ExporterPushgatewayProperties build() {
+ return new ExporterPushgatewayProperties(
+ address, job, scheme, escapingScheme, connectTimeout, readTimeout);
+ }
}
}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/MetricsProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/MetricsProperties.java
index 7667fadce..c2758bd87 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/MetricsProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/MetricsProperties.java
@@ -2,60 +2,83 @@
import static java.util.Collections.unmodifiableList;
+import io.prometheus.metrics.annotations.StableApi;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
-import java.util.Map;
+import javax.annotation.Nullable;
/** Properties starting with io.prometheus.metrics */
+@StableApi
public class MetricsProperties {
- private static final String EXEMPLARS_ENABLED = "exemplarsEnabled";
- private static final String HISTOGRAM_NATIVE_ONLY = "histogramNativeOnly";
- private static final String HISTOGRAM_CLASSIC_ONLY = "histogramClassicOnly";
- private static final String HISTOGRAM_CLASSIC_UPPER_BOUNDS = "histogramClassicUpperBounds";
- private static final String HISTOGRAM_NATIVE_INITIAL_SCHEMA = "histogramNativeInitialSchema";
+ private static final String EXEMPLARS_ENABLED = "exemplars_enabled";
+ private static final String HISTOGRAM_NATIVE_ONLY = "histogram_native_only";
+ private static final String HISTOGRAM_CLASSIC_ONLY = "histogram_classic_only";
+ private static final String HISTOGRAM_CLASSIC_UPPER_BOUNDS = "histogram_classic_upper_bounds";
+ private static final String HISTOGRAM_NATIVE_INITIAL_SCHEMA = "histogram_native_initial_schema";
private static final String HISTOGRAM_NATIVE_MIN_ZERO_THRESHOLD =
- "histogramNativeMinZeroThreshold";
+ "histogram_native_min_zero_threshold";
private static final String HISTOGRAM_NATIVE_MAX_ZERO_THRESHOLD =
- "histogramNativeMaxZeroThreshold";
+ "histogram_native_max_zero_threshold";
private static final String HISTOGRAM_NATIVE_MAX_NUMBER_OF_BUCKETS =
- "histogramNativeMaxNumberOfBuckets"; // 0 means unlimited number of buckets
+ "histogram_native_max_number_of_buckets"; // 0 means unlimited number of buckets
private static final String HISTOGRAM_NATIVE_RESET_DURATION_SECONDS =
- "histogramNativeResetDurationSeconds"; // 0 means no reset
- private static final String SUMMARY_QUANTILES = "summaryQuantiles";
- private static final String SUMMARY_QUANTILE_ERRORS = "summaryQuantileErrors";
- private static final String SUMMARY_MAX_AGE_SECONDS = "summaryMaxAgeSeconds";
- private static final String SUMMARY_NUMBER_OF_AGE_BUCKETS = "summaryNumberOfAgeBuckets";
-
- private final Boolean exemplarsEnabled;
- private final Boolean histogramNativeOnly;
- private final Boolean histogramClassicOnly;
- private final List histogramClassicUpperBounds;
- private final Integer histogramNativeInitialSchema;
- private final Double histogramNativeMinZeroThreshold;
- private final Double histogramNativeMaxZeroThreshold;
- private final Integer histogramNativeMaxNumberOfBuckets;
- private final Long histogramNativeResetDurationSeconds;
- private final List
# editorconfig-checker-disable-line
+
+
+[![Build][build-badge]][build-workflow]
+