\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 44f3cf2c1..e788e5e69 100644
--- a/.mvn/wrapper/maven-wrapper.properties
+++ b/.mvn/wrapper/maven-wrapper.properties
@@ -1,2 +1,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 d107ad6d6..c5ae0ed4b 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,28 +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).
-## Major or minor release
+## How It Works
-After the release is created, do a text replace everywhere in the repository to update the
-snapshot version in the `pom.xml` files (and some other files) to the next version.
-For example, if the last release was `1.4.0`, the next snapshot version should be `1.5.0-SNAPSHOT`.
+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.
-Replace `1.4.0-SNAPSHOT` with `1.5.0-SNAPSHOT` in all following files.
+## Patch Release (default)
-## If the GPG key expired
+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 b2fad5766..6d8c9c5c4 100644
--- a/benchmarks/pom.xml
+++ b/benchmarks/pom.xml
@@ -1,14 +1,11 @@
-
+4.0.0io.prometheusclient_java
- 1.5.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 a13398228..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.5.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 a07c83f0b..681f4a557 100644
--- a/prometheus-metrics-config/pom.xml
+++ b/prometheus-metrics-config/pom.xml
@@ -1,12 +1,11 @@
-
+4.0.0io.prometheusclient_java
- 1.5.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
index 1cd037bf3..1d6bd37cf 100644
--- 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
@@ -1,7 +1,9 @@
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"),
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 20933bfdc..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,15 +1,16 @@
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";
@Nullable private final Integer minRetentionPeriodSeconds;
@Nullable private final Integer maxRetentionPeriodSeconds;
@@ -57,17 +58,17 @@ public Integer getSampleIntervalMilliseconds() {
}
/**
- * 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,
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 7f3b46842..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,19 +1,20 @@
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";
@Nullable private final List allowedNames;
@@ -61,19 +62,19 @@ public List getExcludedMetricNamePrefixes() {
}
/**
- * 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);
}
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 55c15a60c..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,17 +1,21 @@
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 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(@Nullable Integer port) {
+ private ExporterHttpServerProperties(@Nullable Integer port, boolean preferUncompressedResponse) {
this.port = port;
+ this.preferUncompressedResponse = preferUncompressedResponse;
}
@Nullable
@@ -19,15 +23,24 @@ 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() {
@@ -37,6 +50,7 @@ public static Builder builder() {
public static class Builder {
@Nullable private Integer port;
+ private boolean preferUncompressedResponse = false;
private Builder() {}
@@ -45,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 be09b5a63..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,10 +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");
@@ -181,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");
@@ -189,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,
@@ -225,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 6b081816d..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,15 +1,16 @@
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";
@Nullable private final Boolean includeCreatedTimestamps;
@@ -44,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);
}
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 9d7b380d1..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,29 +1,39 @@
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 = "escapingScheme";
+ 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";
@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(
@Nullable String address,
@Nullable String job,
@Nullable String scheme,
- @Nullable EscapingScheme escapingScheme) {
+ @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} */
@@ -56,28 +66,41 @@ 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 escapingScheme = Util.loadString(PREFIX + "." + ESCAPING_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, parseEscapingScheme(escapingScheme));
+ address, job, scheme, parseEscapingScheme(escapingScheme), connectTimeout, readTimeout);
}
private static @Nullable EscapingScheme parseEscapingScheme(@Nullable String scheme) {
@@ -95,10 +118,9 @@ static ExporterPushgatewayProperties load(Map properties)
return EscapingScheme.DOTS_ESCAPING;
default:
throw new PrometheusPropertiesException(
- String.format(
- "%s.%s: Illegal value. Expecting 'allow-utf-8', 'values', 'underscores', "
- + "or 'dots'. Found: %s",
- PREFIX, ESCAPING_SCHEME, scheme));
+ Util.invalidValueMessage(
+ PREFIX + "." + ESCAPING_SCHEME,
+ "Illegal value. Expecting 'allow-utf-8', 'values', 'underscores', or 'dots'."));
}
}
@@ -111,6 +133,8 @@ public static class Builder {
@Nullable private String job;
@Nullable private String scheme;
@Nullable private EscapingScheme escapingScheme;
+ @Nullable private Duration connectTimeout;
+ @Nullable private Duration readTimeout;
private Builder() {}
@@ -134,8 +158,19 @@ public Builder escapingScheme(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);
+ 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 bae38ab86..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,32 +2,54 @@
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";
+ "histogram_native_reset_duration_seconds"; // 0 means no reset
+ private static final String SUMMARY_QUANTILES = "summary_quantiles";
+ private static final String SUMMARY_QUANTILE_ERRORS = "summary_quantile_errors";
+ private static final String SUMMARY_MAX_AGE_SECONDS = "summary_max_age_seconds";
+ private static final String SUMMARY_NUMBER_OF_AGE_BUCKETS = "summary_number_of_age_buckets";
+
+ /**
+ * All known property suffixes that can be configured for metrics.
+ *
+ *
This list is used to parse metric-specific configuration keys from environment variables.
+ */
+ static final String[] PROPERTY_SUFFIXES = {
+ EXEMPLARS_ENABLED,
+ HISTOGRAM_NATIVE_ONLY,
+ HISTOGRAM_CLASSIC_ONLY,
+ HISTOGRAM_CLASSIC_UPPER_BOUNDS,
+ HISTOGRAM_NATIVE_INITIAL_SCHEMA,
+ HISTOGRAM_NATIVE_MIN_ZERO_THRESHOLD,
+ HISTOGRAM_NATIVE_MAX_ZERO_THRESHOLD,
+ HISTOGRAM_NATIVE_MAX_NUMBER_OF_BUCKETS,
+ HISTOGRAM_NATIVE_RESET_DURATION_SECONDS,
+ SUMMARY_QUANTILES,
+ SUMMARY_QUANTILE_ERRORS,
+ SUMMARY_MAX_AGE_SECONDS,
+ SUMMARY_NUMBER_OF_AGE_BUCKETS
+ };
@Nullable private final Boolean exemplarsEnabled;
@Nullable private final Boolean histogramNativeOnly;
@@ -226,17 +248,16 @@ private void validate(String prefix) throws PrometheusPropertiesException {
+ SUMMARY_QUANTILES);
}
if (summaryQuantileErrors.size() != summaryQuantiles.size()) {
+ String fullKey =
+ prefix.isEmpty() ? SUMMARY_QUANTILE_ERRORS : prefix + "." + SUMMARY_QUANTILE_ERRORS;
throw new PrometheusPropertiesException(
- prefix
- + "."
- + SUMMARY_QUANTILE_ERRORS
- + ": must have the same length as "
- + SUMMARY_QUANTILES);
+ fullKey + ": must have the same length as " + SUMMARY_QUANTILES);
}
for (double error : summaryQuantileErrors) {
if (error < 0 || error > 1) {
- throw new PrometheusPropertiesException(
- prefix + "." + SUMMARY_QUANTILE_ERRORS + ": Expecting 0.0 <= error <= 1.0");
+ String fullKey =
+ prefix.isEmpty() ? SUMMARY_QUANTILE_ERRORS : prefix + "." + SUMMARY_QUANTILE_ERRORS;
+ throw new PrometheusPropertiesException(fullKey + ": Expecting 0.0 <= error <= 1.0");
}
}
}
@@ -263,7 +284,7 @@ public Boolean getHistogramClassicOnly() {
return histogramClassicOnly;
}
- /** See {@code Histogram.Builder.classicBuckets()} */
+ /** See {@code Histogram.Builder.classicUpperBounds()} */
@Nullable
public List getHistogramClassicUpperBounds() {
return histogramClassicUpperBounds;
@@ -335,25 +356,25 @@ public Integer getSummaryNumberOfAgeBuckets() {
}
/**
- * 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 MetricsProperties load(String prefix, Map properties)
+ static MetricsProperties load(String prefix, PropertySource propertySource)
throws PrometheusPropertiesException {
return new MetricsProperties(
- Util.loadBoolean(prefix + "." + EXEMPLARS_ENABLED, properties),
- Util.loadBoolean(prefix + "." + HISTOGRAM_NATIVE_ONLY, properties),
- Util.loadBoolean(prefix + "." + HISTOGRAM_CLASSIC_ONLY, properties),
- Util.loadDoubleList(prefix + "." + HISTOGRAM_CLASSIC_UPPER_BOUNDS, properties),
- Util.loadInteger(prefix + "." + HISTOGRAM_NATIVE_INITIAL_SCHEMA, properties),
- Util.loadDouble(prefix + "." + HISTOGRAM_NATIVE_MIN_ZERO_THRESHOLD, properties),
- Util.loadDouble(prefix + "." + HISTOGRAM_NATIVE_MAX_ZERO_THRESHOLD, properties),
- Util.loadInteger(prefix + "." + HISTOGRAM_NATIVE_MAX_NUMBER_OF_BUCKETS, properties),
- Util.loadLong(prefix + "." + HISTOGRAM_NATIVE_RESET_DURATION_SECONDS, properties),
- Util.loadDoubleList(prefix + "." + SUMMARY_QUANTILES, properties),
- Util.loadDoubleList(prefix + "." + SUMMARY_QUANTILE_ERRORS, properties),
- Util.loadLong(prefix + "." + SUMMARY_MAX_AGE_SECONDS, properties),
- Util.loadInteger(prefix + "." + SUMMARY_NUMBER_OF_AGE_BUCKETS, properties),
+ Util.loadBoolean(prefix, EXEMPLARS_ENABLED, propertySource),
+ Util.loadBoolean(prefix, HISTOGRAM_NATIVE_ONLY, propertySource),
+ Util.loadBoolean(prefix, HISTOGRAM_CLASSIC_ONLY, propertySource),
+ Util.loadDoubleList(prefix, HISTOGRAM_CLASSIC_UPPER_BOUNDS, propertySource),
+ Util.loadInteger(prefix, HISTOGRAM_NATIVE_INITIAL_SCHEMA, propertySource),
+ Util.loadDouble(prefix, HISTOGRAM_NATIVE_MIN_ZERO_THRESHOLD, propertySource),
+ Util.loadDouble(prefix, HISTOGRAM_NATIVE_MAX_ZERO_THRESHOLD, propertySource),
+ Util.loadInteger(prefix, HISTOGRAM_NATIVE_MAX_NUMBER_OF_BUCKETS, propertySource),
+ Util.loadLong(prefix, HISTOGRAM_NATIVE_RESET_DURATION_SECONDS, propertySource),
+ Util.loadDoubleList(prefix, SUMMARY_QUANTILES, propertySource),
+ Util.loadDoubleList(prefix, SUMMARY_QUANTILE_ERRORS, propertySource),
+ Util.loadLong(prefix, SUMMARY_MAX_AGE_SECONDS, propertySource),
+ Util.loadInteger(prefix, SUMMARY_NUMBER_OF_AGE_BUCKETS, propertySource),
prefix);
}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/OpenMetrics2Properties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/OpenMetrics2Properties.java
new file mode 100644
index 000000000..1f5080f05
--- /dev/null
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/OpenMetrics2Properties.java
@@ -0,0 +1,141 @@
+package io.prometheus.metrics.config;
+
+import io.prometheus.metrics.annotations.StableApi;
+import javax.annotation.Nullable;
+
+/**
+ * Properties starting with io.prometheus.openmetrics2. These properties are experimental and
+ * subject to change.
+ */
+@StableApi
+public class OpenMetrics2Properties {
+
+ private static final String PREFIX = "io.prometheus.openmetrics2";
+ private static final String ENABLED = "enabled";
+ private static final String CONTENT_NEGOTIATION = "content_negotiation";
+ private static final String COMPOSITE_VALUES = "composite_values";
+ private static final String EXEMPLAR_COMPLIANCE = "exemplar_compliance";
+ private static final String NATIVE_HISTOGRAMS = "native_histograms";
+
+ @Nullable private final Boolean enabled;
+ @Nullable private final Boolean contentNegotiation;
+ @Nullable private final Boolean compositeValues;
+ @Nullable private final Boolean exemplarCompliance;
+ @Nullable private final Boolean nativeHistograms;
+
+ private OpenMetrics2Properties(
+ @Nullable Boolean enabled,
+ @Nullable Boolean contentNegotiation,
+ @Nullable Boolean compositeValues,
+ @Nullable Boolean exemplarCompliance,
+ @Nullable Boolean nativeHistograms) {
+ this.enabled = enabled;
+ this.contentNegotiation = contentNegotiation;
+ this.compositeValues = compositeValues;
+ this.exemplarCompliance = exemplarCompliance;
+ this.nativeHistograms = nativeHistograms;
+ }
+
+ /**
+ * Enable the OpenMetrics 2.0 text format writer. When {@code true}, the OM2 writer is used
+ * instead of OM1 for OpenMetrics responses. Default is {@code false}.
+ */
+ public boolean getEnabled() {
+ return enabled != null && enabled;
+ }
+
+ /** Gate OM2 features behind content negotiation. Default is {@code false}. */
+ public boolean getContentNegotiation() {
+ return contentNegotiation != null && contentNegotiation;
+ }
+
+ /** Single-line histogram/summary with {@code st@}. Default is {@code false}. */
+ public boolean getCompositeValues() {
+ return compositeValues != null && compositeValues;
+ }
+
+ /** Mandatory timestamps, no 128-char limit for exemplars. Default is {@code false}. */
+ public boolean getExemplarCompliance() {
+ return exemplarCompliance != null && exemplarCompliance;
+ }
+
+ /** Exponential buckets support for native histograms. Default is {@code false}. */
+ public boolean getNativeHistograms() {
+ return nativeHistograms != null && nativeHistograms;
+ }
+
+ /**
+ * 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 OpenMetrics2Properties load(PropertySource propertySource)
+ throws PrometheusPropertiesException {
+ Boolean enabled = Util.loadBoolean(PREFIX, ENABLED, propertySource);
+ Boolean contentNegotiation = Util.loadBoolean(PREFIX, CONTENT_NEGOTIATION, propertySource);
+ Boolean compositeValues = Util.loadBoolean(PREFIX, COMPOSITE_VALUES, propertySource);
+ Boolean exemplarCompliance = Util.loadBoolean(PREFIX, EXEMPLAR_COMPLIANCE, propertySource);
+ Boolean nativeHistograms = Util.loadBoolean(PREFIX, NATIVE_HISTOGRAMS, propertySource);
+ return new OpenMetrics2Properties(
+ enabled, contentNegotiation, compositeValues, exemplarCompliance, nativeHistograms);
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static class Builder {
+
+ @Nullable private Boolean enabled;
+ @Nullable private Boolean contentNegotiation;
+ @Nullable private Boolean compositeValues;
+ @Nullable private Boolean exemplarCompliance;
+ @Nullable private Boolean nativeHistograms;
+
+ private Builder() {}
+
+ /** See {@link #getEnabled()} */
+ public Builder enabled(boolean enabled) {
+ this.enabled = enabled;
+ return this;
+ }
+
+ /** See {@link #getContentNegotiation()} */
+ public Builder contentNegotiation(boolean contentNegotiation) {
+ this.contentNegotiation = contentNegotiation;
+ return this;
+ }
+
+ /** See {@link #getCompositeValues()} */
+ public Builder compositeValues(boolean compositeValues) {
+ this.compositeValues = compositeValues;
+ return this;
+ }
+
+ /** See {@link #getExemplarCompliance()} */
+ public Builder exemplarCompliance(boolean exemplarCompliance) {
+ this.exemplarCompliance = exemplarCompliance;
+ return this;
+ }
+
+ /** See {@link #getNativeHistograms()} */
+ public Builder nativeHistograms(boolean nativeHistograms) {
+ this.nativeHistograms = nativeHistograms;
+ return this;
+ }
+
+ /** Enable all OpenMetrics 2.0 features */
+ public Builder enableAll() {
+ this.enabled = true;
+ this.contentNegotiation = true;
+ this.compositeValues = true;
+ this.exemplarCompliance = true;
+ this.nativeHistograms = true;
+ return this;
+ }
+
+ public OpenMetrics2Properties build() {
+ return new OpenMetrics2Properties(
+ enabled, contentNegotiation, compositeValues, exemplarCompliance, nativeHistograms);
+ }
+ }
+}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusProperties.java
index ab78b48e3..aa145d07c 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusProperties.java
@@ -1,7 +1,9 @@
package io.prometheus.metrics.config;
+import io.prometheus.metrics.annotations.StableApi;
import java.util.HashMap;
import java.util.Map;
+import java.util.function.Consumer;
import javax.annotation.Nullable;
/**
@@ -9,18 +11,81 @@
*
*
This class represents the runtime configuration.
*/
+@StableApi
public class PrometheusProperties {
private static final PrometheusProperties instance = PrometheusPropertiesLoader.load();
private final MetricsProperties defaultMetricsProperties;
- private final Map metricProperties = new HashMap<>();
+ private final MetricPropertiesMap metricProperties;
private final ExemplarsProperties exemplarProperties;
private final ExporterProperties exporterProperties;
private final ExporterFilterProperties exporterFilterProperties;
private final ExporterHttpServerProperties exporterHttpServerProperties;
private final ExporterOpenTelemetryProperties exporterOpenTelemetryProperties;
private final ExporterPushgatewayProperties exporterPushgatewayProperties;
+ private final OpenMetrics2Properties openMetrics2Properties;
+
+ /**
+ * Map that stores metric-specific properties keyed by metric name in exposition format
+ * (underscores instead of dots).
+ *
+ *
This wrapper makes it explicit that metric names are normalized to underscore format for
+ * storage, so that environment variables and properties with dots in metric names can be
+ * correctly looked up using normalized names.
+ */
+ static class MetricPropertiesMap {
+ private final Map map = new HashMap<>();
+
+ void set(Map properties) {
+ map.clear();
+ properties.forEach(this::put);
+ }
+
+ void put(String metricName, MetricsProperties properties) {
+ map.put(normalize(metricName), properties);
+ }
+
+ /**
+ * Get metric properties by metric name.
+ *
+ *
Accepts metric names in any format (with dots or underscores) and automatically converts
+ * them to the normalized underscore format used for storage.
+ *
+ * @param metricName the metric name (dots will be converted to underscores)
+ * @return the metric properties, or null if not configured
+ */
+ @Nullable
+ MetricsProperties get(String metricName) {
+ return map.get(normalize(metricName));
+ }
+
+ // copied from PrometheusNaming - but we can't reuse that class here because it's in a module
+ // that
+ // depends on PrometheusProperties, which would create a circular dependency.
+ private static String normalize(String name) {
+ StringBuilder escaped = new StringBuilder();
+
+ for (int i = 0; i < name.length(); ) {
+ int c = name.codePointAt(i);
+ if (isValidLegacyChar(c, i)) {
+ escaped.appendCodePoint(c);
+ } else {
+ escaped.append('_');
+ }
+ i += Character.charCount(c);
+ }
+ return escaped.toString();
+ }
+ }
+
+ private static boolean isValidLegacyChar(int c, int i) {
+ return (c >= 'a' && c <= 'z')
+ || (c >= 'A' && c <= 'Z')
+ || c == '_'
+ || c == ':'
+ || (c >= '0' && c <= '9' && i > 0);
+ }
/**
* Get the properties instance. When called for the first time, {@code get()} loads the properties
@@ -41,23 +106,26 @@ public static Builder builder() {
return new Builder();
}
- public PrometheusProperties(
+ // Package-private constructor for PrometheusPropertiesLoader and Builder
+ PrometheusProperties(
MetricsProperties defaultMetricsProperties,
- Map metricProperties,
+ MetricPropertiesMap metricProperties,
ExemplarsProperties exemplarProperties,
ExporterProperties exporterProperties,
ExporterFilterProperties exporterFilterProperties,
ExporterHttpServerProperties httpServerConfig,
ExporterPushgatewayProperties pushgatewayProperties,
- ExporterOpenTelemetryProperties otelConfig) {
+ ExporterOpenTelemetryProperties otelConfig,
+ OpenMetrics2Properties openMetrics2Properties) {
this.defaultMetricsProperties = defaultMetricsProperties;
- this.metricProperties.putAll(metricProperties);
+ this.metricProperties = metricProperties;
this.exemplarProperties = exemplarProperties;
this.exporterProperties = exporterProperties;
this.exporterFilterProperties = exporterFilterProperties;
this.exporterHttpServerProperties = httpServerConfig;
this.exporterPushgatewayProperties = pushgatewayProperties;
this.exporterOpenTelemetryProperties = otelConfig;
+ this.openMetrics2Properties = openMetrics2Properties;
}
/**
@@ -72,10 +140,13 @@ public MetricsProperties getDefaultMetricProperties() {
* Properties specific for one metric. Should be merged with {@link
* #getDefaultMetricProperties()}. May return {@code null} if no metric-specific properties are
* configured for a metric name.
+ *
+ * @param metricName the metric name (dots will be automatically converted to underscores to match
+ * exposition format)
*/
@Nullable
public MetricsProperties getMetricProperties(String metricName) {
- return metricProperties.get(metricName.replace(".", "_"));
+ return metricProperties.get(metricName);
}
public ExemplarsProperties getExemplarProperties() {
@@ -102,9 +173,13 @@ public ExporterOpenTelemetryProperties getExporterOpenTelemetryProperties() {
return exporterOpenTelemetryProperties;
}
+ public OpenMetrics2Properties getOpenMetrics2Properties() {
+ return openMetrics2Properties;
+ }
+
public static class Builder {
private MetricsProperties defaultMetricsProperties = MetricsProperties.builder().build();
- private Map metricProperties = new HashMap<>();
+ private final MetricPropertiesMap metricProperties = new MetricPropertiesMap();
private ExemplarsProperties exemplarProperties = ExemplarsProperties.builder().build();
private ExporterProperties exporterProperties = ExporterProperties.builder().build();
private ExporterFilterProperties exporterFilterProperties =
@@ -115,6 +190,8 @@ public static class Builder {
ExporterPushgatewayProperties.builder().build();
private ExporterOpenTelemetryProperties otelConfig =
ExporterOpenTelemetryProperties.builder().build();
+ private OpenMetrics2Properties openMetrics2Properties =
+ OpenMetrics2Properties.builder().build();
private Builder() {}
@@ -124,7 +201,7 @@ public Builder defaultMetricsProperties(MetricsProperties defaultMetricsProperti
}
public Builder metricProperties(Map metricProperties) {
- this.metricProperties = metricProperties;
+ this.metricProperties.set(metricProperties);
return this;
}
@@ -166,6 +243,19 @@ public Builder exporterOpenTelemetryProperties(
return this;
}
+ public Builder enableOpenMetrics2(Consumer configurator) {
+ OpenMetrics2Properties.Builder openMetrics2Builder =
+ OpenMetrics2Properties.builder().enabled(true);
+ configurator.accept(openMetrics2Builder);
+ this.openMetrics2Properties = openMetrics2Builder.build();
+ return this;
+ }
+
+ public Builder openMetrics2Properties(OpenMetrics2Properties openMetrics2Properties) {
+ this.openMetrics2Properties = openMetrics2Properties;
+ return this;
+ }
+
public PrometheusProperties build() {
return new PrometheusProperties(
defaultMetricsProperties,
@@ -175,7 +265,8 @@ public PrometheusProperties build() {
exporterFilterProperties,
exporterHttpServerProperties,
pushgatewayProperties,
- otelConfig);
+ otelConfig,
+ openMetrics2Properties);
}
}
}
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesException.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesException.java
index bdb024514..b6f6fac4b 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesException.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesException.java
@@ -1,5 +1,8 @@
package io.prometheus.metrics.config;
+import io.prometheus.metrics.annotations.StableApi;
+
+@StableApi
public class PrometheusPropertiesException extends RuntimeException {
private static final long serialVersionUID = 0L;
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
index a847a8dba..04bbfe4a5 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
@@ -1,16 +1,14 @@
package io.prometheus.metrics.config;
+import io.prometheus.metrics.annotations.StableApi;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
-import java.util.HashSet;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
/**
* The Properties Loader is early stages.
@@ -20,6 +18,7 @@
* Boot's Externalized Configuration, like support for YAML, Properties, and env vars, or
* support for Spring's naming conventions for properties.
*/
+@StableApi
public class PrometheusPropertiesLoader {
/** See {@link PrometheusProperties#get()}. */
@@ -29,20 +28,22 @@ public static PrometheusProperties load() throws PrometheusPropertiesException {
public static PrometheusProperties load(Map externalProperties)
throws PrometheusPropertiesException {
- Map properties = loadProperties(externalProperties);
- Map metricsConfigs = loadMetricsConfigs(properties);
+ PropertySource propertySource = loadProperties(externalProperties);
+ PrometheusProperties.MetricPropertiesMap metricsConfigs = loadMetricsConfigs(propertySource);
MetricsProperties defaultMetricsProperties =
- MetricsProperties.load("io.prometheus.metrics", properties);
- ExemplarsProperties exemplarConfig = ExemplarsProperties.load(properties);
- ExporterProperties exporterProperties = ExporterProperties.load(properties);
- ExporterFilterProperties exporterFilterProperties = ExporterFilterProperties.load(properties);
+ MetricsProperties.load("io.prometheus.metrics", propertySource);
+ ExemplarsProperties exemplarConfig = ExemplarsProperties.load(propertySource);
+ ExporterProperties exporterProperties = ExporterProperties.load(propertySource);
+ ExporterFilterProperties exporterFilterProperties =
+ ExporterFilterProperties.load(propertySource);
ExporterHttpServerProperties exporterHttpServerProperties =
- ExporterHttpServerProperties.load(properties);
+ ExporterHttpServerProperties.load(propertySource);
ExporterPushgatewayProperties exporterPushgatewayProperties =
- ExporterPushgatewayProperties.load(properties);
+ ExporterPushgatewayProperties.load(propertySource);
ExporterOpenTelemetryProperties exporterOpenTelemetryProperties =
- ExporterOpenTelemetryProperties.load(properties);
- validateAllPropertiesProcessed(properties);
+ ExporterOpenTelemetryProperties.load(propertySource);
+ OpenMetrics2Properties openMetrics2Properties = OpenMetrics2Properties.load(propertySource);
+ validateAllPropertiesProcessed(propertySource);
return new PrometheusProperties(
defaultMetricsProperties,
metricsConfigs,
@@ -51,31 +52,53 @@ public static PrometheusProperties load(Map externalProperties)
exporterFilterProperties,
exporterHttpServerProperties,
exporterPushgatewayProperties,
- exporterOpenTelemetryProperties);
+ exporterOpenTelemetryProperties,
+ openMetrics2Properties);
}
- // This will remove entries from properties when they are processed.
- private static Map loadMetricsConfigs(Map properties) {
- Map result = new HashMap<>();
+ // This will remove entries from propertySource when they are processed.
+ static PrometheusProperties.MetricPropertiesMap loadMetricsConfigs(
+ PropertySource propertySource) {
+ PrometheusProperties.MetricPropertiesMap result =
+ new PrometheusProperties.MetricPropertiesMap();
// Note that the metric name in the properties file must be as exposed in the Prometheus
// exposition formats,
// i.e. all dots replaced with underscores.
- Pattern pattern = Pattern.compile("io\\.prometheus\\.metrics\\.([^.]+)\\.");
- // Create a copy of the keySet() for iterating. We cannot iterate directly over keySet()
- // because entries are removed when MetricsConfig.load(...) is called.
- Set propertyNames = new HashSet<>();
- for (Object key : properties.keySet()) {
- propertyNames.add(key.toString());
- }
+
+ // Get a snapshot of all keys for pattern matching. Entries will be removed
+ // when MetricsProperties.load(...) is called.
+ Set propertyNames = propertySource.getAllKeys();
for (String propertyName : propertyNames) {
- Matcher matcher = pattern.matcher(propertyName);
- if (matcher.find()) {
- String metricName = matcher.group(1).replace(".", "_");
- if (!result.containsKey(metricName)) {
- result.put(
- metricName,
- MetricsProperties.load("io.prometheus.metrics." + metricName, properties));
+ String metricName = null;
+
+ if (propertyName.startsWith("io.prometheus.metrics.")) {
+ // Dot-separated format (from regular properties, system properties, or files)
+ String remainder = propertyName.substring("io.prometheus.metrics.".length());
+ // Try to match against known property suffixes
+ for (String suffix : MetricsProperties.PROPERTY_SUFFIXES) {
+ if (remainder.endsWith("." + suffix)) {
+ // Metric name in dot format, convert dots to underscores for exposition format
+ metricName =
+ remainder.substring(0, remainder.length() - suffix.length() - 1).replace(".", "_");
+ break;
+ }
}
+ } else if (propertyName.startsWith("io_prometheus_metrics_")) {
+ // Underscore-separated format (from environment variables)
+ String remainder = propertyName.substring("io_prometheus_metrics_".length());
+ // Try to match against known property suffixes
+ for (String suffix : MetricsProperties.PROPERTY_SUFFIXES) {
+ if (remainder.endsWith("_" + suffix)) {
+ metricName = remainder.substring(0, remainder.length() - suffix.length() - 1);
+ break;
+ }
+ }
+ }
+
+ if (metricName != null && result.get(metricName) == null) {
+ result.put(
+ metricName,
+ MetricsProperties.load("io.prometheus.metrics." + metricName, propertySource));
}
}
return result;
@@ -84,26 +107,43 @@ private static Map loadMetricsConfigs(Map properties) {
- for (Object key : properties.keySet()) {
- if (key.toString().startsWith("io.prometheus")) {
+ private static void validateAllPropertiesProcessed(PropertySource propertySource) {
+ for (String key : propertySource.getRemainingKeys()) {
+ if (key.startsWith("io.prometheus") || key.startsWith("io_prometheus")) {
throw new PrometheusPropertiesException(key + ": Unknown property");
}
}
}
- private static Map loadProperties(Map externalProperties) {
- Map properties = new HashMap<>();
- properties.putAll(loadPropertiesFromClasspath());
- properties.putAll(loadPropertiesFromFile()); // overriding the entries from the classpath file
+ private static PropertySource loadProperties(Map externalProperties) {
+ // Regular properties (lowest priority): classpath, file, system properties
+ Map regularProperties = new HashMap<>();
+ // Normalize all properties at load time to handle camelCase in files for backward compatibility
+ normalizeAndPutAll(regularProperties, loadPropertiesFromClasspath());
+ normalizeAndPutAll(
+ regularProperties,
+ loadPropertiesFromFile()); // overriding the entries from the classpath file
// overriding the entries from the properties file
// copy System properties to avoid ConcurrentModificationException
+ // normalize camelCase system properties to snake_case for backward compatibility
System.getProperties().stringPropertyNames().stream()
.filter(key -> key.startsWith("io.prometheus"))
- .forEach(key -> properties.put(key, System.getProperty(key)));
- properties.putAll(externalProperties); // overriding all the entries above
- // TODO: Add environment variables like EXEMPLARS_ENABLED.
- return properties;
+ .forEach(key -> regularProperties.put(normalizePropertyKey(key), System.getProperty(key)));
+
+ // Environment variables (second priority): just lowercase, keep underscores
+ Map envVarProperties = loadPropertiesFromEnvironment();
+
+ // External properties (highest priority): normalize camelCase for backward compatibility
+ Map normalizedExternalProperties = new HashMap<>();
+ externalProperties.forEach(
+ (key, value) ->
+ normalizedExternalProperties.put(normalizePropertyKey(key.toString()), value));
+
+ return new PropertySource(normalizedExternalProperties, envVarProperties, regularProperties);
+ }
+
+ private static void normalizeAndPutAll(Map
# editorconfig-checker-disable-line
+
+
+[![Build][build-badge]][build-workflow]
+