From 34316342c009b259f49f4b743b9361ce6c631480 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Mon, 1 Jun 2026 17:07:08 +0000 Subject: [PATCH 1/2] Add StableApi marker and API diff check Signed-off-by: Gregor Zeitlinger --- .github/renovate-tracked-deps.json | 5 + .github/workflows/api-diff.yml | 79 +++++ .github/workflows/codeql.yml | 1 + docs/stable-api-rationale.md | 325 ++++++++++++++++++ mise.toml | 13 + pom.xml | 72 ++++ prometheus-metrics-annotations/pom.xml | 22 ++ .../metrics/annotations/StableApi.java | 22 ++ prometheus-metrics-bom/pom.xml | 5 + prometheus-metrics-config/pom.xml | 6 + .../metrics/config/EscapingScheme.java | 2 + .../metrics/config/ExemplarsProperties.java | 2 + .../config/ExporterFilterProperties.java | 2 + .../config/ExporterHttpServerProperties.java | 2 + .../ExporterOpenTelemetryProperties.java | 2 + .../metrics/config/ExporterProperties.java | 2 + .../config/ExporterPushgatewayProperties.java | 2 + .../metrics/config/MetricsProperties.java | 2 + .../config/OpenMetrics2Properties.java | 2 + .../metrics/config/PrometheusProperties.java | 2 + .../config/PrometheusPropertiesException.java | 3 + .../config/PrometheusPropertiesLoader.java | 2 + prometheus-metrics-core/pom.xml | 6 + .../core/datapoints/CounterDataPoint.java | 2 + .../metrics/core/datapoints/DataPoint.java | 3 + .../datapoints/DistributionDataPoint.java | 2 + .../core/datapoints/GaugeDataPoint.java | 2 + .../core/datapoints/StateSetDataPoint.java | 3 + .../metrics/core/datapoints/Timer.java | 2 + .../metrics/core/datapoints/TimerApi.java | 2 + .../core/exemplars/ExemplarSampler.java | 2 + .../core/exemplars/ExemplarSamplerConfig.java | 2 + .../metrics/core/metrics/Counter.java | 2 + .../core/metrics/CounterWithCallback.java | 2 + .../metrics/core/metrics/Gauge.java | 2 + .../core/metrics/GaugeWithCallback.java | 2 + .../metrics/core/metrics/Histogram.java | 2 + .../prometheus/metrics/core/metrics/Info.java | 2 + .../metrics/core/metrics/Metric.java | 2 + .../core/metrics/MetricWithFixedMetadata.java | 2 + .../metrics/core/metrics/SlidingWindow.java | 2 + .../metrics/core/metrics/StateSet.java | 2 + .../metrics/core/metrics/StatefulMetric.java | 2 + .../metrics/core/metrics/Summary.java | 2 + .../core/metrics/SummaryWithCallback.java | 2 + prometheus-metrics-exporter-common/pom.xml | 6 + .../common/PrometheusHttpExchange.java | 2 + .../common/PrometheusHttpRequest.java | 2 + .../common/PrometheusHttpResponse.java | 2 + .../common/PrometheusScrapeHandler.java | 2 + .../pom.xml | 6 + .../exporter/httpserver/DefaultHandler.java | 2 + .../exporter/httpserver/HTTPServer.java | 2 + .../exporter/httpserver/HealthyHandler.java | 2 + .../exporter/httpserver/MetricsHandler.java | 2 + .../pom.xml | 6 + .../pom.xml | 6 + .../opentelemetry/OpenTelemetryExporter.java | 2 + .../pom.xml | 6 + .../DefaultHttpConnectionFactory.java | 2 + .../metrics/exporter/pushgateway/Format.java | 3 + .../pushgateway/HttpConnectionFactory.java | 2 + .../exporter/pushgateway/PushGateway.java | 2 + .../metrics/exporter/pushgateway/Scheme.java | 3 + .../pom.xml | 6 + .../jakarta/PrometheusMetricsServlet.java | 2 + .../pom.xml | 6 + .../javax/PrometheusMetricsServlet.java | 2 + .../pom.xml | 6 + .../ExpositionFormatWriter.java | 2 + .../expositionformats/ExpositionFormats.java | 2 + .../OpenMetrics2TextFormatWriter.java | 2 + .../OpenMetricsTextFormatWriter.java | 2 + .../PrometheusProtobufWriter.java | 2 + .../PrometheusTextFormatWriter.java | 2 + .../pom.xml | 6 + .../caffeine/CacheMetricsCollector.java | 2 + .../pom.xml | 6 + .../dropwizard/DropwizardExports.java | 2 + .../pom.xml | 6 + .../dropwizard5/DropwizardExports.java | 2 + .../dropwizard5/InvalidMetricHandler.java | 3 + .../dropwizard5/labels/CustomLabelMapper.java | 2 + .../dropwizard5/labels/MapperConfig.java | 2 + .../pom.xml | 6 + .../guava/CacheMetricsCollector.java | 2 + .../pom.xml | 6 + .../jvm/JvmBufferPoolMetrics.java | 2 + .../jvm/JvmClassLoadingMetrics.java | 2 + .../jvm/JvmCompilationMetrics.java | 2 + .../jvm/JvmGarbageCollectorMetrics.java | 2 + .../instrumentation/jvm/JvmMemoryMetrics.java | 2 + .../jvm/JvmMemoryPoolAllocationMetrics.java | 2 + .../instrumentation/jvm/JvmMetrics.java | 2 + .../jvm/JvmNativeMemoryMetrics.java | 2 + .../jvm/JvmRuntimeInfoMetric.java | 2 + .../jvm/JvmThreadsMetrics.java | 2 + .../instrumentation/jvm/ProcessMetrics.java | 2 + prometheus-metrics-model/pom.xml | 6 + .../metrics/model/registry/Collector.java | 2 + .../model/registry/MetricNameFilter.java | 2 + .../metrics/model/registry/MetricType.java | 3 + .../model/registry/MultiCollector.java | 2 + .../model/registry/PrometheusRegistry.java | 2 + .../registry/PrometheusScrapeRequest.java | 2 + .../snapshots/ClassicHistogramBucket.java | 3 + .../snapshots/ClassicHistogramBuckets.java | 2 + .../model/snapshots/CounterSnapshot.java | 2 + .../model/snapshots/DataPointSnapshot.java | 2 + .../DistributionDataPointSnapshot.java | 3 + .../snapshots/DuplicateLabelsException.java | 3 + .../metrics/model/snapshots/Exemplar.java | 2 + .../metrics/model/snapshots/Exemplars.java | 2 + .../model/snapshots/GaugeSnapshot.java | 2 + .../model/snapshots/HistogramSnapshot.java | 2 + .../metrics/model/snapshots/InfoSnapshot.java | 2 + .../metrics/model/snapshots/Label.java | 2 + .../metrics/model/snapshots/Labels.java | 2 + .../snapshots/MetricFamilyDescriptor.java | 2 + .../model/snapshots/MetricMetadata.java | 2 + .../model/snapshots/MetricSnapshot.java | 2 + .../model/snapshots/MetricSnapshots.java | 2 + .../snapshots/NativeHistogramBucket.java | 3 + .../snapshots/NativeHistogramBuckets.java | 2 + .../model/snapshots/PrometheusNaming.java | 2 + .../metrics/model/snapshots/Quantile.java | 3 + .../metrics/model/snapshots/Quantiles.java | 2 + .../model/snapshots/StateSetSnapshot.java | 2 + .../model/snapshots/SummarySnapshot.java | 2 + .../metrics/model/snapshots/Unit.java | 2 + .../model/snapshots/UnknownSnapshot.java | 2 + .../pom.xml | 6 + .../bridge/SimpleclientCollector.java | 2 + .../prometheus-metrics-tracer-common/pom.xml | 9 + .../metrics/tracer/common/SpanContext.java | 2 + 135 files changed, 883 insertions(+) create mode 100644 .github/workflows/api-diff.yml create mode 100644 docs/stable-api-rationale.md create mode 100644 prometheus-metrics-annotations/pom.xml create mode 100644 prometheus-metrics-annotations/src/main/java/io/prometheus/metrics/annotations/StableApi.java diff --git a/.github/renovate-tracked-deps.json b/.github/renovate-tracked-deps.json index 412a82a33..95fa34155 100644 --- a/.github/renovate-tracked-deps.json +++ b/.github/renovate-tracked-deps.json @@ -16,6 +16,11 @@ "mise" ] }, + ".github/workflows/api-diff.yml": { + "regex": [ + "mise" + ] + }, ".github/workflows/build.yml": { "regex": [ "mise" diff --git a/.github/workflows/api-diff.yml b/.github/workflows/api-diff.yml new file mode 100644 index 000000000..3a6ed2edf --- /dev/null +++ b/.github/workflows/api-diff.yml @@ -0,0 +1,79 @@ +--- +name: API Diff + +on: + pull_request: + types: + - opened + - synchronize + - reopened + - labeled + - unlabeled + workflow_dispatch: + inputs: + baseline_version: + description: Version to compare the PR artifacts against + required: false + default: "1.5.1" + +permissions: + contents: read + +jobs: + api-diff: + runs-on: ubuntu-24.04 + env: + API_DIFF_BASELINE_VERSION: ${{ inputs.baseline_version || '1.5.1' }} + BREAKING_API_CHANGE_ACCEPTED: >- + ${{ contains(github.event.pull_request.labels.*.name, 'breaking-api-change-accepted') }} + + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + persist-credentials: false + - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1 + with: + version: v2026.5.18 + sha256: cfac593469d028d7ae5fe36e37bd7c59118b5238e92d8a876209578464f24a84 + - name: Cache local Maven repository + uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5 + with: + path: ~/.m2/repository + key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }} + - name: Run japicmp API diff + run: mise run api-diff + - name: Fail on incompatible published API changes + run: | + python3 - <<'PY' + import os + from pathlib import Path + import sys + import xml.etree.ElementTree as ET + + failures = [] + for report in sorted(Path(".").glob("**/target/japicmp/api-diff.xml")): + parts = report.parts + module = "/".join(parts[: parts.index("target")]) + tree = ET.parse(report) + for change in tree.findall(".//compatibilityChange"): + binary = change.get("binaryCompatible") == "false" + source = change.get("sourceCompatible") == "false" + if binary or source: + failures.append((module, change.get("type", "unknown"))) + + if not failures: + print("No incompatible published API changes detected.") + sys.exit(0) + + print("Incompatible published API changes detected:") + for module, change_type in failures[:100]: + print(f"- {module}: {change_type}") + if len(failures) > 100: + print(f"... and {len(failures) - 100} more") + if os.environ.get("BREAKING_API_CHANGE_ACCEPTED") == "true": + print("Accepted by PR label `breaking-api-change-accepted`.") + sys.exit(0) + print("Run `mise run api-diff` locally for full japicmp output.") + print("Reports are written to `**/target/japicmp/*`.") + sys.exit(1) + PY diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 05b7cbaf5..4847aee2f 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -49,6 +49,7 @@ jobs: - name: Build (CodeQL traces the build) run: > ./mvnw clean compile + -P '!default' -DskipTests -Dcoverage.skip=true -Dcheckstyle.skip=true diff --git a/docs/stable-api-rationale.md b/docs/stable-api-rationale.md new file mode 100644 index 000000000..5a8a3235b --- /dev/null +++ b/docs/stable-api-rationale.md @@ -0,0 +1,325 @@ +# Stable API rationale + +This file records the first-pass guess for the `@StableApi` surface. + +The guess is intentionally conservative about user-facing entry points, but it also includes +supporting public value types when they appear in signatures of those entry points. The +annotation is currently applied to top-level types. Public nested builders and data point +snapshots are treated as part of the annotated enclosing type. + +Evidence labels: + +- D-core: documented in getting-started metric, label, callback, registry, or + multi-target docs. +- D-config: documented in `docs/content/config/config.md`. +- D-exporter: documented in exporter docs under `docs/content/exporters/`. +- D-instr: documented in instrumentation docs under `docs/content/instrumentation/`. +- D-migration: documented in `docs/content/migration/simpleclient.md`. +- D-otel: documented in OpenTelemetry docs under `docs/content/otel/`. +- M: imported or used by Micrometer's Prometheus registry or samples. +- J: imported or used by Prometheus JMX Exporter's collector, common, agent, or tests. +- S: support type in the public signatures or returned snapshots of another stable API. +- T: tooling contract for the API diff mechanism itself. + +Entries justified only by S are the weakest guesses. They are included because excluding them +would make a documented or externally used API hard to use without unstable public types. + +## Annotation module + +### `io.prometheus.metrics.annotations` + +- `StableApi`: T. This is the opt-in marker used by japicmp and by humans to decide + which public types are part of the published compatibility contract. + +## Config + +### `io.prometheus.metrics.config` + +- `EscapingScheme`: D-config, D-exporter. PushGateway and unicode docs expose escaping + selection, and the type is accepted by documented builder methods. +- `ExemplarsProperties`: D-config, M. Micrometer constructs exemplar sampler config from + this type, and the config docs link its getters directly. +- `ExporterFilterProperties`: D-config. Exporter filtering is documented as runtime + configuration and maps to this public properties type. +- `ExporterHttpServerProperties`: D-config. The HTTP server exporter settings are + documented and map to this public properties type. +- `ExporterOpenTelemetryProperties`: D-config, D-otel. OTLP exporter settings are + documented and map to this public properties type. +- `ExporterProperties`: D-config. Exporter-wide options such as exemplar behavior are + documented and exposed through this public type. +- `ExporterPushgatewayProperties`: D-config, D-exporter. PushGateway runtime settings are + documented and map to this public properties type. +- `MetricsProperties`: D-config. Core metric defaults such as histogram and summary + options are documented and exposed through this type. +- `OpenMetrics2Properties`: D-config, D-exporter. OM2 is experimental, but the public + docs link this type and its getters explicitly. +- `PrometheusProperties`: D-config, D-exporter, D-otel, M, J. It is the root config type + used by docs, Micrometer, and JMX Exporter. +- `PrometheusPropertiesException`: S. Public exception thrown by the public config loader + and builder path; callers may catch it. +- `PrometheusPropertiesLoader`: D-config, M. The config docs describe loading runtime + configuration, and Micrometer imports this loader. + +## Core datapoints and timers + +### `io.prometheus.metrics.core.datapoints` + +- `CounterDataPoint`: S. Returned by documented `Counter` label accessors and callback + APIs, so users can increment labeled counters. +- `DataPoint`: S. Common public supertype for metric child handles returned by stable + metric APIs. +- `DistributionDataPoint`: S. Common public supertype behind histogram and summary child + handles, including observe and exemplar operations. +- `GaugeDataPoint`: S. Returned by documented `Gauge` label accessors and callback APIs, + so users can set and adjust labeled gauges. +- `StateSetDataPoint`: S. Returned by documented `StateSet` APIs, so users can set named + state values. +- `Timer`: D-core, S. Returned by documented timer helpers used to time histogram and + summary observations. +- `TimerApi`: D-core. The metric type docs link this interface for timing APIs on + histogram and summary metrics. + +## Core exemplars + +### `io.prometheus.metrics.core.exemplars` + +- `ExemplarSampler`: M, D-otel. Micrometer imports it for exemplar sampling, and the OTel + tracing docs describe exemplar behavior as an integration surface. +- `ExemplarSamplerConfig`: M. Micrometer imports it to configure exemplar sampler + creation. + +## Core metrics + +### `io.prometheus.metrics.core.metrics` + +- `Counter`: D-core, D-migration, D-otel, J. It is a primary metric type in docs and is + imported by JMX Exporter. +- `CounterWithCallback`: D-core. The callback docs list it as the counter callback metric + type. +- `Gauge`: D-core, D-exporter, J. It is a primary metric type in docs and is imported by + JMX Exporter. +- `GaugeWithCallback`: D-core. The callback docs list it as the gauge callback metric + type and show examples. +- `Histogram`: D-core, D-config. It is a primary metric type in docs, including classic + and native histogram configuration. +- `Info`: D-core, D-exporter, J. The metric type and OM2 docs describe info metrics, and + JMX Exporter imports it for build info. +- `Metric`: S. Public common base for documented metric classes and their shared builder + behavior. +- `MetricWithFixedMetadata`: S. Public base for documented metric classes whose metadata + is fixed at build time. +- `SlidingWindow`: S. Public summary configuration type used by summary implementation + and exposed through public summary behavior. +- `StateSet`: D-core. The metric type docs document StateSet as an OpenMetrics metric + type and show builder usage. +- `StatefulMetric`: S. Public base for documented metric classes that expose label child + handles. +- `Summary`: D-core, D-config, D-migration. It is a primary metric type in docs and is + covered by documented quantile and age configuration. +- `SummaryWithCallback`: D-core. The callback docs list it as the summary callback metric + type and show examples. + +## Exporter common + +### `io.prometheus.metrics.exporter.common` + +- `PrometheusHttpExchange`: S. Public exchange abstraction used by the stable scrape + handler so non-server adapters can plug in. +- `PrometheusHttpRequest`: S. Public request abstraction used by `PrometheusScrapeHandler`. +- `PrometheusHttpResponse`: S. Public response abstraction used by `PrometheusScrapeHandler`. +- `PrometheusScrapeHandler`: S, D-exporter. Shared public scrape handler behind documented + HTTP and servlet exporters. + +## HTTP server exporter + +### `io.prometheus.metrics.exporter.httpserver` + +- `DefaultHandler`: J, D-exporter. JMX Exporter imports it to configure HTTP endpoints; + HTTP server docs mention default endpoint behavior. +- `HTTPServer`: D-core, D-exporter, D-otel, J. It is the documented standalone exporter + and is imported by JMX Exporter. +- `HealthyHandler`: J, D-exporter. JMX Exporter imports it for the health endpoint; the + HTTP server docs document health endpoint behavior. +- `MetricsHandler`: J, D-exporter. JMX Exporter imports it for the metrics endpoint; the + HTTP server docs document metrics endpoint behavior. + +## OpenTelemetry exporter + +### `io.prometheus.metrics.exporter.opentelemetry` + +- `OpenTelemetryExporter`: D-config, D-otel, J. The OTLP docs use its builder directly, + and JMX Exporter imports it for OTel mode. + +## PushGateway exporter + +### `io.prometheus.metrics.exporter.pushgateway` + +- `DefaultHttpConnectionFactory`: S. Public default implementation of the documented + PushGateway connection extension point. +- `Format`: S, D-exporter. Public enum controlling the documented PushGateway wire format. +- `HttpConnectionFactory`: S. Public extension point accepted by `PushGateway.Builder`. +- `PushGateway`: D-config, D-exporter. The PushGateway docs use this type and its builder + throughout. +- `Scheme`: S, D-config. Public scheme enum accepted by documented PushGateway builder + and config paths. + +## Servlet exporters + +### `io.prometheus.metrics.exporter.servlet.jakarta` + +- `PrometheusMetricsServlet`: D-exporter. Servlet and Spring docs show direct + registration of the Jakarta servlet class. + +### `io.prometheus.metrics.exporter.servlet.javax` + +- `PrometheusMetricsServlet`: D-exporter. The javax artifact is the legacy servlet + counterpart of the documented Jakarta servlet entry point. + +## Exposition formats + +### `io.prometheus.metrics.expositionformats` + +- `ExpositionFormatWriter`: S. Public writer interface behind the documented exposition + format selection and custom writer implementations. +- `ExpositionFormats`: M, D-exporter. Micrometer imports it for scraping, and exporter + docs describe content negotiation between formats. +- `OpenMetrics2TextFormatWriter`: D-exporter. OM2 preview docs document the experimental + OM2 writer path. +- `OpenMetricsTextFormatWriter`: M, D-exporter. Micrometer tests import it, and exporter + docs describe OpenMetrics text output. +- `PrometheusProtobufWriter`: D-exporter. Exporter docs mention this class by name for + shaded PushGateway jars. +- `PrometheusTextFormatWriter`: M, D-exporter. Micrometer tests import it, and exporter + docs describe Prometheus text output. + +## Instrumentation + +### `io.prometheus.metrics.instrumentation.caffeine` + +- `CacheMetricsCollector`: D-instr. The caffeine instrumentation docs describe registering + this collector for cache metrics. + +### `io.prometheus.metrics.instrumentation.dropwizard` + +- `DropwizardExports`: S. Dropwizard 4 is a shipped instrumentation module and equivalent + public entry point to the documented Dropwizard 5 exporter. + +### `io.prometheus.metrics.instrumentation.dropwizard5` + +- `DropwizardExports`: S. Dropwizard 5 is a shipped instrumentation module with public + registration entry point. +- `InvalidMetricHandler`: S. Public extension point used by Dropwizard exports to decide + how invalid Dropwizard metrics are handled. + +### `io.prometheus.metrics.instrumentation.dropwizard5.labels` + +- `CustomLabelMapper`: S. Public extension point for Dropwizard 5 custom label mapping. +- `MapperConfig`: S. Public configuration value consumed by `CustomLabelMapper`. + +### `io.prometheus.metrics.instrumentation.guava` + +- `CacheMetricsCollector`: D-instr. The guava instrumentation docs describe registering + this collector for cache metrics. + +### `io.prometheus.metrics.instrumentation.jvm` + +- `JvmBufferPoolMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `JvmClassLoadingMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `JvmCompilationMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `JvmGarbageCollectorMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `JvmMemoryMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `JvmMemoryPoolAllocationMetrics`: S, D-instr. Public component metric used by aggregate + JVM instrumentation. +- `JvmMetrics`: D-core, D-instr, D-migration, J. Quickstart, migration, and JMX Exporter + use this aggregate JVM instrumentation entry point. +- `JvmNativeMemoryMetrics`: D-instr. Native memory tracking is documented as part of JVM + instrumentation. +- `JvmRuntimeInfoMetric`: D-instr. The JVM docs link this metric class directly. +- `JvmThreadsMetrics`: S, D-instr. Public component metric used by aggregate JVM + instrumentation. +- `ProcessMetrics`: S, D-instr. Public process metric component used by aggregate JVM + instrumentation. + +## Registry + +### `io.prometheus.metrics.model.registry` + +- `Collector`: D-core, S. Public extension point for custom collectors registered in a + `PrometheusRegistry`. +- `MetricNameFilter`: S. Public filter accepted by registry scrape collection paths. +- `MetricType`: S. Public enum used in metadata and snapshot APIs. +- `MultiCollector`: M, J, D-core. Micrometer and JMX Exporter implement or import it, and + multi-target docs show a custom collector pattern. +- `PrometheusRegistry`: D-core, D-migration, D-otel, M, J. It is the central registry in + docs and a direct dependency of Micrometer and JMX Exporter. +- `PrometheusScrapeRequest`: D-core, S. Multi-target docs show scrape-request-aware + collection; the type is required for that extension point. + +## Snapshots + +### `io.prometheus.metrics.model.snapshots` + +- `ClassicHistogramBucket`: M, S. Micrometer uses classic histogram bucket snapshots, and + this is the public value type for one bucket. +- `ClassicHistogramBuckets`: M, S. Micrometer uses it when reading histogram snapshots. +- `CounterSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in + multi-target custom collector examples. +- `DataPointSnapshot`: M, J, D-core. Common public base for snapshot data points used by + Micrometer, JMX Exporter, and custom collector docs. +- `DistributionDataPointSnapshot`: S. Public base for histogram and summary data point + snapshots returned by documented distribution metrics. +- `DuplicateLabelsException`: J, S. JMX Exporter tests catch duplicate-label behavior; + custom collectors can encounter this public validation exception. +- `Exemplar`: M, D-otel. Micrometer creates exemplar snapshots, and OTel tracing docs + describe exemplar output. +- `Exemplars`: M, D-otel. Micrometer creates exemplar containers, and OTel tracing docs + describe exemplar output. +- `GaugeSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in + multi-target custom collector examples. +- `HistogramSnapshot`: M, D-core. Micrometer reads histogram snapshots, and histogram is a + documented primary metric type. +- `InfoSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter for info metrics. +- `Label`: S. Public value type contained by `Labels` and snapshot APIs. +- `Labels`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in label and + multi-target docs. +- `MetricMetadata`: M, J, S. Used by Micrometer and JMX Exporter when building custom + snapshots. +- `MetricFamilyDescriptor`: S. Registration-time descriptor returned by the stable + `Collector` and `MultiCollector` extension points. +- `MetricSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in + registry and multi-target docs. +- `MetricSnapshots`: M, J, D-core. Used by Micrometer and JMX Exporter, and returned by + custom collector examples. +- `NativeHistogramBucket`: S. Public value type for native histogram snapshots, needed + because native histograms are documented metric output. +- `NativeHistogramBuckets`: S. Public container for native histogram snapshot buckets. +- `PrometheusNaming`: M, J, D-core. Micrometer and JMX Exporter use it for name + sanitizing, and multi-target docs show it directly. +- `Quantile`: S, D-core. Public value type for summary quantiles, which are documented in + summary and callback APIs. +- `Quantiles`: M, D-core. Micrometer uses it and summary docs expose quantile behavior. +- `StateSetSnapshot`: S, D-core. Public snapshot type for the documented StateSet metric. +- `SummarySnapshot`: M, D-core. Micrometer reads summary snapshots, and summary is a + documented primary metric type. +- `Unit`: J, S. JMX Exporter imports it, and unit metadata appears throughout documented + metric and naming behavior. +- `UnknownSnapshot`: J, S. JMX Exporter builds unknown snapshots for untyped JMX metrics. + +## Simpleclient bridge + +### `io.prometheus.metrics.simpleclient.bridge` + +- `SimpleclientCollector`: D-migration. Migration docs use this bridge as the supported + path for simpleclient 0.x metrics. + +## Tracer common + +### `io.prometheus.metrics.tracer.common` + +- `SpanContext`: M, D-otel. Micrometer imports it for exemplars, and OTel tracing docs + describe span context propagation into exemplars. diff --git a/mise.toml b/mise.toml index 973ef10a8..616159a90 100644 --- a/mise.toml +++ b/mise.toml @@ -59,6 +59,19 @@ run = "./mvnw verify" description = "build all modules without tests" run = "./mvnw install -DskipTests -Dcoverage.skip=true" +[tasks."api-diff"] +description = "Compare published API against the configured japicmp baseline" +run = """ +BASELINE_VERSION="${API_DIFF_BASELINE_VERSION:-1.5.1}" +./mvnw -B verify \ + -P 'api-diff,!examples-and-integration-tests' \ + -Dapi.diff.baseline.version="${BASELINE_VERSION}" \ + -DskipTests \ + -Dcoverage.skip=true \ + -Dcheckstyle.skip=true \ + -Dwarnings=-nowarn +""" + [tasks."lint"] description = "Run all lints" depends = ["lint:bom"] diff --git a/pom.xml b/pom.xml index f9c25d9e2..a53c8e24e 100644 --- a/pom.xml +++ b/pom.xml @@ -29,6 +29,7 @@ 2.28.1-alpha 8 25 + 1.5.1 0.70 false false @@ -38,6 +39,7 @@ prometheus-metrics-parent + prometheus-metrics-annotations prometheus-metrics-bom prometheus-metrics-core prometheus-metrics-config @@ -171,6 +173,11 @@ exec-maven-plugin 3.6.3 + + com.github.siom79.japicmp + japicmp-maven-plugin + 0.26.1 + @@ -401,6 +408,71 @@ + + api-diff + + + + com.github.siom79.japicmp + japicmp-maven-plugin + + + + ${project.groupId} + ${project.artifactId} + ${api.diff.baseline.version} + jar + + + + + ${project.build.directory}/${project.build.finalName}.jar + + + + public + true + + io.prometheus.metrics.annotations.StableApi + @io.prometheus.metrics.annotations.StableApi + + + io.prometheus.metrics.expositionformats.generated + io.prometheus.metrics.shaded + + false + + false + + + false + + false + true + true + true + true + true + true + + bundle + jar + + + + + + api-diff + verify + + cmp + + + + + + + errorprone diff --git a/prometheus-metrics-annotations/pom.xml b/prometheus-metrics-annotations/pom.xml new file mode 100644 index 000000000..4b22354c4 --- /dev/null +++ b/prometheus-metrics-annotations/pom.xml @@ -0,0 +1,22 @@ + + + 4.0.0 + + + io.prometheus + client_java + 1.6.2-SNAPSHOT + + + prometheus-metrics-annotations + bundle + + Prometheus Metrics Annotations + + Annotations for Prometheus Metrics library API contracts. + + + + io.prometheus.metrics.annotations + + diff --git a/prometheus-metrics-annotations/src/main/java/io/prometheus/metrics/annotations/StableApi.java b/prometheus-metrics-annotations/src/main/java/io/prometheus/metrics/annotations/StableApi.java new file mode 100644 index 000000000..a3bfe89ae --- /dev/null +++ b/prometheus-metrics-annotations/src/main/java/io/prometheus/metrics/annotations/StableApi.java @@ -0,0 +1,22 @@ +package io.prometheus.metrics.annotations; + +import static java.lang.annotation.ElementType.CONSTRUCTOR; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.CLASS; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +/** + * Marks a Java element as part of the stable, published Prometheus Metrics API. + * + *

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 b01bcce43..66bcb524e 100644 --- a/prometheus-metrics-bom/pom.xml +++ b/prometheus-metrics-bom/pom.xml @@ -19,6 +19,11 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + io.prometheus prometheus-metrics-config diff --git a/prometheus-metrics-config/pom.xml b/prometheus-metrics-config/pom.xml index d505248e7..e207c6b49 100644 --- a/prometheus-metrics-config/pom.xml +++ b/prometheus-metrics-config/pom.xml @@ -21,6 +21,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + org.junit-pioneer junit-pioneer 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 765d33ac5..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,8 +1,10 @@ package io.prometheus.metrics.config; +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"; 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 d59330cb9..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,5 +1,6 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; @@ -7,6 +8,7 @@ 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 = "metric_name_must_be_equal_to"; 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 0623f78e1..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,8 +1,10 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import javax.annotation.Nullable; /** Properties starting with io.prometheus.exporter.http_server */ +@StableApi public class ExporterHttpServerProperties { private static final String PORT = "port"; 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 6e93f5de7..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,5 +1,6 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import java.util.HashMap; import java.util.Map; import javax.annotation.Nullable; @@ -31,6 +32,7 @@ * href="https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/">OpenTelemetry * SDK Environment Variables */ +@StableApi public class ExporterOpenTelemetryProperties { // See 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 460a5cae2..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,8 +1,10 @@ package io.prometheus.metrics.config; +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 = "include_created_timestamps"; 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 aea4b2d8f..10e8c0f33 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,8 +1,10 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import java.time.Duration; import javax.annotation.Nullable; +@StableApi public class ExporterPushgatewayProperties { private static final String ADDRESS = "address"; 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 a530f35e1..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,12 +2,14 @@ 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 javax.annotation.Nullable; /** Properties starting with io.prometheus.metrics */ +@StableApi public class MetricsProperties { private static final String EXEMPLARS_ENABLED = "exemplars_enabled"; 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 index be1d13279..1f5080f05 100644 --- 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 @@ -1,11 +1,13 @@ 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"; 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 55e7d8dab..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,5 +1,6 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import java.util.HashMap; import java.util.Map; import java.util.function.Consumer; @@ -10,6 +11,7 @@ * *

This class represents the runtime configuration. */ +@StableApi public class PrometheusProperties { private static final PrometheusProperties instance = PrometheusPropertiesLoader.load(); 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 018ea2c5d..6d52b71ef 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,5 +1,6 @@ package io.prometheus.metrics.config; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.io.InputStream; import java.nio.file.Files; @@ -17,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()}. */ diff --git a/prometheus-metrics-core/pom.xml b/prometheus-metrics-core/pom.xml index 3ba812f1d..61d10d3c5 100644 --- a/prometheus-metrics-core/pom.xml +++ b/prometheus-metrics-core/pom.xml @@ -21,6 +21,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-model diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/CounterDataPoint.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/CounterDataPoint.java index 7055d7565..4c5c2d28f 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/CounterDataPoint.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/CounterDataPoint.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.Labels; /** @@ -56,6 +57,7 @@ * CounterDataPoint counterData = counterWithoutLabels; * } */ +@StableApi public interface CounterDataPoint extends DataPoint { /** Add one. */ diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DataPoint.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DataPoint.java index 5b6017ddf..cfdc84df3 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DataPoint.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DataPoint.java @@ -1,3 +1,6 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; + +@StableApi public interface DataPoint {} diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DistributionDataPoint.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DistributionDataPoint.java index 0f2a072de..f87bede40 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DistributionDataPoint.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/DistributionDataPoint.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.Labels; /** @@ -17,6 +18,7 @@ *

See JavaDoc of {@link CounterDataPoint} on how using data points directly can improve * performance. */ +@StableApi public interface DistributionDataPoint extends DataPoint, TimerApi { /** Get the count of observations. */ diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/GaugeDataPoint.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/GaugeDataPoint.java index eec0304c7..8d917985e 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/GaugeDataPoint.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/GaugeDataPoint.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.Labels; /** @@ -9,6 +10,7 @@ *

See JavaDoc of {@link CounterDataPoint} on how using data points directly can improve * performance. */ +@StableApi public interface GaugeDataPoint extends DataPoint, TimerApi { /** Add one. */ diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/StateSetDataPoint.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/StateSetDataPoint.java index bf13b5214..f08876cae 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/StateSetDataPoint.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/StateSetDataPoint.java @@ -1,11 +1,14 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; + /** * Represents a single StateSet data point. * *

See JavaDoc of {@link CounterDataPoint} on how using data points directly can improve * performance. */ +@StableApi public interface StateSetDataPoint extends DataPoint { /** diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/Timer.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/Timer.java index d860bfa08..ee302a4c5 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/Timer.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/Timer.java @@ -1,10 +1,12 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.Unit; import java.io.Closeable; import java.util.function.DoubleConsumer; /** Helper class for observing durations. */ +@StableApi public class Timer implements Closeable { private final DoubleConsumer observeFunction; diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/TimerApi.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/TimerApi.java index 8267f7f78..00729503e 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/TimerApi.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/datapoints/TimerApi.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.datapoints; +import io.prometheus.metrics.annotations.StableApi; import java.util.concurrent.Callable; import java.util.function.Supplier; @@ -11,6 +12,7 @@ * must use base units (e.g. seconds, bytes) and leave converting them to something more readable to * graphing tools". */ +@StableApi public interface TimerApi { /** diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSampler.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSampler.java index 1219b2a09..ad1591c21 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSampler.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSampler.java @@ -2,6 +2,7 @@ import static java.util.Objects.requireNonNull; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.core.util.Scheduler; import io.prometheus.metrics.model.snapshots.Exemplar; import io.prometheus.metrics.model.snapshots.Exemplars; @@ -31,6 +32,7 @@ * *

See {@link ExemplarSamplerConfig} for configuration options. */ +@StableApi public class ExemplarSampler { private final ExemplarSamplerConfig config; diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSamplerConfig.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSamplerConfig.java index 5bf642e7e..f1afd1453 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSamplerConfig.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/exemplars/ExemplarSamplerConfig.java @@ -1,10 +1,12 @@ package io.prometheus.metrics.core.exemplars; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.ExemplarsProperties; import io.prometheus.metrics.config.PrometheusProperties; import java.util.concurrent.TimeUnit; import javax.annotation.Nullable; +@StableApi public class ExemplarSamplerConfig { /** See {@link ExemplarsProperties#getMinRetentionPeriodSeconds()} */ diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java index a93321392..742043449 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.MetricsProperties; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.datapoints.CounterDataPoint; @@ -31,6 +32,7 @@ * requestCount.labelValues("/hello-world", "500").inc(); * } */ +@StableApi public class Counter extends StatefulMetric implements CounterDataPoint { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java index de2e41174..514a13d26 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MetricType; import io.prometheus.metrics.model.snapshots.CounterSnapshot; @@ -22,6 +23,7 @@ * .register(); * } */ +@StableApi public class CounterWithCallback extends CallbackMetric { @FunctionalInterface diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java index 7dbfd9d9b..44b61a976 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.MetricsProperties; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.datapoints.GaugeDataPoint; @@ -38,6 +39,7 @@ * } * } */ +@StableApi public class Gauge extends StatefulMetric implements GaugeDataPoint { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java index 3b26cb520..6c81e2d89 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MetricType; import io.prometheus.metrics.model.snapshots.GaugeSnapshot; @@ -27,6 +28,7 @@ * .register(); * } */ +@StableApi public class GaugeWithCallback extends CallbackMetric { @FunctionalInterface diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java index 4412911d3..c10d583b1 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.ExemplarsProperties; import io.prometheus.metrics.config.MetricsProperties; import io.prometheus.metrics.config.PrometheusProperties; @@ -61,6 +62,7 @@ *

If you want the classic representation only, use {@link Histogram.Builder#classicOnly}. If you * want the native representation only, use {@link Histogram.Builder#nativeOnly}. */ +@StableApi public class Histogram extends StatefulMetric implements DistributionDataPoint { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java index 1aab04054..69be33e9d 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MetricType; import io.prometheus.metrics.model.snapshots.InfoSnapshot; @@ -30,6 +31,7 @@ * info.addLabelValues("dev", version, vendor, runtime); * } */ +@StableApi public class Info extends MetricWithFixedMetadata { private final Set labels = new CopyOnWriteArraySet<>(); diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Metric.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Metric.java index d3c00eca0..64c03c825 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Metric.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Metric.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.Collector; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -10,6 +11,7 @@ import java.util.List; /** Common base class for all metrics. */ +@StableApi public abstract class Metric implements Collector { protected final Labels constLabels; diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java index 7cbbaaed6..9be797b0e 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MetricType; import io.prometheus.metrics.model.snapshots.Label; @@ -20,6 +21,7 @@ *

An exception would be a metric that is a bridge to a 3rd party metric library, where the * metric name has to be retrieved from the 3rd party metric library at scrape time. */ +@StableApi public abstract class MetricWithFixedMetadata extends Metric { protected final MetricMetadata metadata; diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SlidingWindow.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SlidingWindow.java index e56134d5d..4940e1e6d 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SlidingWindow.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SlidingWindow.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import java.lang.reflect.Array; import java.util.concurrent.TimeUnit; import java.util.function.LongSupplier; @@ -26,6 +27,7 @@ * and the observation frequency is typically lower than Counter increments, the current * implementation provides an acceptable trade-off between simplicity and performance. */ +@StableApi public class SlidingWindow { private final Supplier constructor; diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java index 2ad314ee7..c62aecb77 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java @@ -2,6 +2,7 @@ import static io.prometheus.metrics.model.snapshots.PrometheusNaming.prometheusName; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.datapoints.StateSetDataPoint; import io.prometheus.metrics.model.registry.MetricType; @@ -51,6 +52,7 @@ * The example above shows how to use a StateSet with an enum. You don't have to use enum, you can * use regular strings as well. */ +@StableApi public class StateSet extends StatefulMetric implements StateSetDataPoint { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StatefulMetric.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StatefulMetric.java index f9d02d3d7..fabad19d0 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StatefulMetric.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StatefulMetric.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.MetricsProperties; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.datapoints.DataPoint; @@ -30,6 +31,7 @@ * because in Java synchronous and asynchronous usually refers to multi-threading, but * this has nothing to do with multi-threading. */ +@StableApi public abstract class StatefulMetric extends MetricWithFixedMetadata { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Summary.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Summary.java index b200274b9..1e380cc77 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Summary.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Summary.java @@ -2,6 +2,7 @@ import static java.util.Objects.requireNonNull; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.MetricsProperties; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.datapoints.DistributionDataPoint; @@ -42,6 +43,7 @@ * * See {@link Summary.Builder} for configuration options. */ +@StableApi public class Summary extends StatefulMetric implements DistributionDataPoint { diff --git a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SummaryWithCallback.java b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SummaryWithCallback.java index 8229a817c..0980f0d19 100644 --- a/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SummaryWithCallback.java +++ b/prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SummaryWithCallback.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.core.metrics; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MetricType; import io.prometheus.metrics.model.snapshots.Exemplars; @@ -35,6 +36,7 @@ * .register(); * } */ +@StableApi public class SummaryWithCallback extends CallbackMetric { @FunctionalInterface diff --git a/prometheus-metrics-exporter-common/pom.xml b/prometheus-metrics-exporter-common/pom.xml index 9c1c9c91f..9381b16dc 100644 --- a/prometheus-metrics-exporter-common/pom.xml +++ b/prometheus-metrics-exporter-common/pom.xml @@ -21,6 +21,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-model diff --git a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpExchange.java b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpExchange.java index b7ac63b28..81d00e62b 100644 --- a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpExchange.java +++ b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpExchange.java @@ -1,7 +1,9 @@ package io.prometheus.metrics.exporter.common; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; +@StableApi public interface PrometheusHttpExchange extends AutoCloseable { PrometheusHttpRequest getRequest(); diff --git a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpRequest.java b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpRequest.java index 4483fc83f..a0c692c23 100644 --- a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpRequest.java +++ b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpRequest.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.exporter.common; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.registry.PrometheusScrapeRequest; import java.io.UnsupportedEncodingException; import java.net.URLDecoder; @@ -7,6 +8,7 @@ import java.util.Enumeration; import javax.annotation.Nullable; +@StableApi public interface PrometheusHttpRequest extends PrometheusScrapeRequest { /** See {@code jakarta.servlet.http.HttpServletRequest.getQueryString()} */ diff --git a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpResponse.java b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpResponse.java index b3dd4e2fb..b084d3989 100644 --- a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpResponse.java +++ b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusHttpResponse.java @@ -1,8 +1,10 @@ package io.prometheus.metrics.exporter.common; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.io.OutputStream; +@StableApi public interface PrometheusHttpResponse { /** See {@code jakarta.servlet.http.HttpServletResponse.setHeader(String, String)} */ diff --git a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java index b538f898d..20328382a 100644 --- a/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java +++ b/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.exporter.common; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.config.ExporterFilterProperties; import io.prometheus.metrics.config.PrometheusProperties; @@ -22,6 +23,7 @@ import javax.annotation.Nullable; /** Prometheus scrape endpoint. */ +@StableApi public class PrometheusScrapeHandler { private final PrometheusRegistry registry; diff --git a/prometheus-metrics-exporter-httpserver/pom.xml b/prometheus-metrics-exporter-httpserver/pom.xml index d8916ca72..a9b854a87 100644 --- a/prometheus-metrics-exporter-httpserver/pom.xml +++ b/prometheus-metrics-exporter-httpserver/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-exporter-common diff --git a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/DefaultHandler.java b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/DefaultHandler.java index a4a343d54..2cafbb89c 100644 --- a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/DefaultHandler.java +++ b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/DefaultHandler.java @@ -2,10 +2,12 @@ import com.sun.net.httpserver.HttpExchange; import com.sun.net.httpserver.HttpHandler; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.nio.charset.StandardCharsets; /** Handler for the / endpoint */ +@StableApi public class DefaultHandler implements HttpHandler { private final byte[] responseBytes; diff --git a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java index 55ed6c67e..e93b122b0 100644 --- a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java +++ b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java @@ -7,6 +7,7 @@ import com.sun.net.httpserver.HttpServer; import com.sun.net.httpserver.HttpsConfigurator; import com.sun.net.httpserver.HttpsServer; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.PrometheusRegistry; import java.io.Closeable; @@ -35,6 +36,7 @@ * .buildAndStart(); * } */ +@StableApi public class HTTPServer implements Closeable { static { diff --git a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HealthyHandler.java b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HealthyHandler.java index 806b47553..10cb97462 100644 --- a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HealthyHandler.java +++ b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HealthyHandler.java @@ -2,10 +2,12 @@ import com.sun.net.httpserver.HttpExchange; import com.sun.net.httpserver.HttpHandler; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.nio.charset.StandardCharsets; /** Handler for the /-/healthy endpoint */ +@StableApi public class HealthyHandler implements HttpHandler { private final byte[] responseBytes; diff --git a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/MetricsHandler.java b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/MetricsHandler.java index 4ac4b80d7..175696b68 100644 --- a/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/MetricsHandler.java +++ b/prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/MetricsHandler.java @@ -2,12 +2,14 @@ import com.sun.net.httpserver.HttpExchange; import com.sun.net.httpserver.HttpHandler; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.exporter.common.PrometheusScrapeHandler; import io.prometheus.metrics.model.registry.PrometheusRegistry; import java.io.IOException; /** Handler for the /metrics endpoint */ +@StableApi public class MetricsHandler implements HttpHandler { private final PrometheusScrapeHandler prometheusScrapeHandler; diff --git a/prometheus-metrics-exporter-opentelemetry-shaded/pom.xml b/prometheus-metrics-exporter-opentelemetry-shaded/pom.xml index 308ee761e..514d58699 100644 --- a/prometheus-metrics-exporter-opentelemetry-shaded/pom.xml +++ b/prometheus-metrics-exporter-opentelemetry-shaded/pom.xml @@ -33,6 +33,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-exporter-opentelemetry/pom.xml b/prometheus-metrics-exporter-opentelemetry/pom.xml index 415882bb4..24c147f50 100644 --- a/prometheus-metrics-exporter-opentelemetry/pom.xml +++ b/prometheus-metrics-exporter-opentelemetry/pom.xml @@ -34,6 +34,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-exporter-opentelemetry/src/main/java/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.java b/prometheus-metrics-exporter-opentelemetry/src/main/java/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.java index 727647e2e..1ca92c2c7 100644 --- a/prometheus-metrics-exporter-opentelemetry/src/main/java/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.java +++ b/prometheus-metrics-exporter-opentelemetry/src/main/java/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.java @@ -1,12 +1,14 @@ package io.prometheus.metrics.exporter.opentelemetry; import io.opentelemetry.sdk.metrics.export.MetricReader; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.PrometheusRegistry; import java.util.HashMap; import java.util.Map; import javax.annotation.Nullable; +@StableApi public class OpenTelemetryExporter implements AutoCloseable { private final MetricReader reader; diff --git a/prometheus-metrics-exporter-pushgateway/pom.xml b/prometheus-metrics-exporter-pushgateway/pom.xml index c7b63fb96..b7d543a34 100644 --- a/prometheus-metrics-exporter-pushgateway/pom.xml +++ b/prometheus-metrics-exporter-pushgateway/pom.xml @@ -21,6 +21,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-exporter-common diff --git a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/DefaultHttpConnectionFactory.java b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/DefaultHttpConnectionFactory.java index 60c110149..ef28fb34f 100644 --- a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/DefaultHttpConnectionFactory.java +++ b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/DefaultHttpConnectionFactory.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.exporter.pushgateway; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.net.HttpURLConnection; import java.net.URL; @@ -12,6 +13,7 @@ * certificate verification see {@code PushGatewayTestApp} in {@code * integration-tests/it-pushgateway/}. */ +@StableApi public class DefaultHttpConnectionFactory implements HttpConnectionFactory { @Override public HttpURLConnection create(URL url) throws IOException { diff --git a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Format.java b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Format.java index 3d1b9d2e6..089c686fc 100644 --- a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Format.java +++ b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Format.java @@ -1,5 +1,8 @@ package io.prometheus.metrics.exporter.pushgateway; +import io.prometheus.metrics.annotations.StableApi; + +@StableApi public enum Format { PROMETHEUS_PROTOBUF, PROMETHEUS_TEXT diff --git a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.java b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.java index f7a039af7..7b112bb4d 100644 --- a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.java +++ b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.java @@ -1,11 +1,13 @@ package io.prometheus.metrics.exporter.pushgateway; +import io.prometheus.metrics.annotations.StableApi; import java.io.IOException; import java.net.HttpURLConnection; import java.net.URL; /** See {@link DefaultHttpConnectionFactory}. */ @FunctionalInterface +@StableApi public interface HttpConnectionFactory { HttpURLConnection create(URL url) throws IOException; } diff --git a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java index 594132cf2..5bf26b6c1 100644 --- a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java +++ b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java @@ -4,6 +4,7 @@ import static io.prometheus.metrics.model.snapshots.PrometheusNaming.escapeName; import static java.util.Objects.requireNonNull; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.config.ExporterPushgatewayProperties; import io.prometheus.metrics.config.PrometheusProperties; @@ -79,6 +80,7 @@ *

See https://github.com/prometheus/pushgateway. */ +@StableApi public class PushGateway { private final URL url; private final ExpositionFormatWriter writer; diff --git a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Scheme.java b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Scheme.java index 51a2e32dd..1ade4efdb 100644 --- a/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Scheme.java +++ b/prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/Scheme.java @@ -1,5 +1,8 @@ package io.prometheus.metrics.exporter.pushgateway; +import io.prometheus.metrics.annotations.StableApi; + +@StableApi public enum Scheme { HTTP("http"), HTTPS("https"); diff --git a/prometheus-metrics-exporter-servlet-jakarta/pom.xml b/prometheus-metrics-exporter-servlet-jakarta/pom.xml index 7ad2f482e..248af0c0b 100644 --- a/prometheus-metrics-exporter-servlet-jakarta/pom.xml +++ b/prometheus-metrics-exporter-servlet-jakarta/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-exporter-common diff --git a/prometheus-metrics-exporter-servlet-jakarta/src/main/java/io/prometheus/metrics/exporter/servlet/jakarta/PrometheusMetricsServlet.java b/prometheus-metrics-exporter-servlet-jakarta/src/main/java/io/prometheus/metrics/exporter/servlet/jakarta/PrometheusMetricsServlet.java index 5e22fc3fd..68153f761 100644 --- a/prometheus-metrics-exporter-servlet-jakarta/src/main/java/io/prometheus/metrics/exporter/servlet/jakarta/PrometheusMetricsServlet.java +++ b/prometheus-metrics-exporter-servlet-jakarta/src/main/java/io/prometheus/metrics/exporter/servlet/jakarta/PrometheusMetricsServlet.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.exporter.servlet.jakarta; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.exporter.common.PrometheusScrapeHandler; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -14,6 +15,7 @@ *

We'll add a Jakarta servlet, the built-in HTTPServer, etc. soon, and likely move common code * into a common module. */ +@StableApi public class PrometheusMetricsServlet extends HttpServlet { private static final long serialVersionUID = 0L; diff --git a/prometheus-metrics-exporter-servlet-javax/pom.xml b/prometheus-metrics-exporter-servlet-javax/pom.xml index 53df64c8d..d5749f71c 100644 --- a/prometheus-metrics-exporter-servlet-javax/pom.xml +++ b/prometheus-metrics-exporter-servlet-javax/pom.xml @@ -29,6 +29,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-exporter-common diff --git a/prometheus-metrics-exporter-servlet-javax/src/main/java/io/prometheus/metrics/exporter/servlet/javax/PrometheusMetricsServlet.java b/prometheus-metrics-exporter-servlet-javax/src/main/java/io/prometheus/metrics/exporter/servlet/javax/PrometheusMetricsServlet.java index a486aec93..aa2e3e3a9 100644 --- a/prometheus-metrics-exporter-servlet-javax/src/main/java/io/prometheus/metrics/exporter/servlet/javax/PrometheusMetricsServlet.java +++ b/prometheus-metrics-exporter-servlet-javax/src/main/java/io/prometheus/metrics/exporter/servlet/javax/PrometheusMetricsServlet.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.exporter.servlet.javax; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.exporter.common.PrometheusScrapeHandler; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -13,6 +14,7 @@ * PrometheusScrapeHandler to handle HTTP GET requests and export metrics. The servlet can be * configured with custom PrometheusProperties and a PrometheusRegistry. */ +@StableApi public class PrometheusMetricsServlet extends HttpServlet { private static final long serialVersionUID = 0L; diff --git a/prometheus-metrics-exposition-textformats/pom.xml b/prometheus-metrics-exposition-textformats/pom.xml index 91cb0de39..17c0dc450 100644 --- a/prometheus-metrics-exposition-textformats/pom.xml +++ b/prometheus-metrics-exposition-textformats/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-model diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormatWriter.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormatWriter.java index 03ac229ca..7ea071bf7 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormatWriter.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormatWriter.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.expositionformats; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.model.snapshots.MetricSnapshots; import java.io.ByteArrayOutputStream; @@ -7,6 +8,7 @@ import java.io.OutputStream; import javax.annotation.Nullable; +@StableApi public interface ExpositionFormatWriter { boolean accepts(@Nullable String acceptHeader); diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java index feabd89b8..0cfce9b5f 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java @@ -1,10 +1,12 @@ package io.prometheus.metrics.expositionformats; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.ExporterProperties; import io.prometheus.metrics.config.OpenMetrics2Properties; import io.prometheus.metrics.config.PrometheusProperties; import javax.annotation.Nullable; +@StableApi public class ExpositionFormats { private final PrometheusProtobufWriter prometheusProtobufWriter; diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java index 19e1e4c93..f400ecce0 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java @@ -9,6 +9,7 @@ import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getOriginalMetadataName; import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getSnapshotLabelName; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.config.OpenMetrics2Properties; import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets; @@ -45,6 +46,7 @@ * href="https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec_2_0.md">OpenMetrics * 2.0 specification evolves. */ +@StableApi public class OpenMetrics2TextFormatWriter implements ExpositionFormatWriter { public static class Builder { diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java index cd299cb94..02614a561 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java @@ -10,6 +10,7 @@ import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getMetadataName; import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getSnapshotLabelName; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets; import io.prometheus.metrics.model.snapshots.CounterSnapshot; @@ -43,6 +44,7 @@ * Write the OpenMetrics text format as defined on https://openmetrics.io. */ +@StableApi public class OpenMetricsTextFormatWriter implements ExpositionFormatWriter { public static class Builder { diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusProtobufWriter.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusProtobufWriter.java index 342beb255..d7f4e4469 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusProtobufWriter.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusProtobufWriter.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.expositionformats; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.model.snapshots.MetricSnapshots; import java.io.IOException; @@ -12,6 +13,7 @@ * *

As of today, this is the only exposition format that supports native histograms. */ +@StableApi public class PrometheusProtobufWriter implements ExpositionFormatWriter { @Nullable private static final ExpositionFormatWriter DELEGATE = createProtobufWriter(); diff --git a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java index 9251ac85e..f94d710ba 100644 --- a/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java +++ b/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java @@ -12,6 +12,7 @@ import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getMetadataName; import static io.prometheus.metrics.model.snapshots.SnapshotEscaper.getSnapshotLabelName; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets; import io.prometheus.metrics.model.snapshots.CounterSnapshot; @@ -40,6 +41,7 @@ * Write the Prometheus text format. This is the default if you view a Prometheus endpoint with your * Web browser. */ +@StableApi public class PrometheusTextFormatWriter implements ExpositionFormatWriter { public static final String CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"; diff --git a/prometheus-metrics-instrumentation-caffeine/pom.xml b/prometheus-metrics-instrumentation-caffeine/pom.xml index f2776f309..ed00e6e7d 100644 --- a/prometheus-metrics-instrumentation-caffeine/pom.xml +++ b/prometheus-metrics-instrumentation-caffeine/pom.xml @@ -29,6 +29,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java b/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java index 28edff88f..ba7552910 100644 --- a/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java +++ b/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java @@ -5,6 +5,7 @@ import com.github.benmanes.caffeine.cache.LoadingCache; import com.github.benmanes.caffeine.cache.Policy; import com.github.benmanes.caffeine.cache.stats.CacheStats; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.registry.MultiCollector; import io.prometheus.metrics.model.snapshots.CounterSnapshot; import io.prometheus.metrics.model.snapshots.GaugeSnapshot; @@ -55,6 +56,7 @@ * caffeine_cache_load_duration_seconds_sum{cache="mycache"} 0.0034 * */ +@StableApi public class CacheMetricsCollector implements MultiCollector { private static final double NANOSECONDS_PER_SECOND = 1_000_000_000.0; diff --git a/prometheus-metrics-instrumentation-dropwizard/pom.xml b/prometheus-metrics-instrumentation-dropwizard/pom.xml index 0f4c1ead3..fd90bfd51 100644 --- a/prometheus-metrics-instrumentation-dropwizard/pom.xml +++ b/prometheus-metrics-instrumentation-dropwizard/pom.xml @@ -29,6 +29,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-instrumentation-dropwizard/src/main/java/io/prometheus/metrics/instrumentation/dropwizard/DropwizardExports.java b/prometheus-metrics-instrumentation-dropwizard/src/main/java/io/prometheus/metrics/instrumentation/dropwizard/DropwizardExports.java index 0c1c8455f..4e527ce87 100644 --- a/prometheus-metrics-instrumentation-dropwizard/src/main/java/io/prometheus/metrics/instrumentation/dropwizard/DropwizardExports.java +++ b/prometheus-metrics-instrumentation-dropwizard/src/main/java/io/prometheus/metrics/instrumentation/dropwizard/DropwizardExports.java @@ -9,6 +9,7 @@ import com.codahale.metrics.MetricRegistry; import com.codahale.metrics.Snapshot; import com.codahale.metrics.Timer; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.instrumentation.dropwizard5.InvalidMetricHandler; import io.prometheus.metrics.instrumentation.dropwizard5.internal.AbstractDropwizardExports; import io.prometheus.metrics.instrumentation.dropwizard5.labels.CustomLabelMapper; @@ -22,6 +23,7 @@ *

This is a thin wrapper around {@link AbstractDropwizardExports} that handles the Dropwizard * 4.x specific API where metric names are Strings. */ +@StableApi public class DropwizardExports extends AbstractDropwizardExports< MetricRegistry, diff --git a/prometheus-metrics-instrumentation-dropwizard5/pom.xml b/prometheus-metrics-instrumentation-dropwizard5/pom.xml index ffee45702..654b575ce 100644 --- a/prometheus-metrics-instrumentation-dropwizard5/pom.xml +++ b/prometheus-metrics-instrumentation-dropwizard5/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/DropwizardExports.java b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/DropwizardExports.java index 86c64b54e..dec51dc92 100644 --- a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/DropwizardExports.java +++ b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/DropwizardExports.java @@ -10,6 +10,7 @@ import io.dropwizard.metrics5.MetricRegistry; import io.dropwizard.metrics5.Snapshot; import io.dropwizard.metrics5.Timer; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.instrumentation.dropwizard5.internal.AbstractDropwizardExports; import io.prometheus.metrics.instrumentation.dropwizard5.labels.CustomLabelMapper; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -22,6 +23,7 @@ *

This is a thin wrapper around {@link AbstractDropwizardExports} that handles the Dropwizard * 5.x specific API where metric names are {@link MetricName} objects. */ +@StableApi public class DropwizardExports extends AbstractDropwizardExports< MetricRegistry, diff --git a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/InvalidMetricHandler.java b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/InvalidMetricHandler.java index bac1aa0af..cb7d965ff 100644 --- a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/InvalidMetricHandler.java +++ b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/InvalidMetricHandler.java @@ -1,6 +1,9 @@ package io.prometheus.metrics.instrumentation.dropwizard5; +import io.prometheus.metrics.annotations.StableApi; + @FunctionalInterface +@StableApi public interface InvalidMetricHandler { InvalidMetricHandler ALWAYS_THROW = (metricName, exc) -> false; diff --git a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/CustomLabelMapper.java b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/CustomLabelMapper.java index f2174970c..61fb5de5a 100644 --- a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/CustomLabelMapper.java +++ b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/CustomLabelMapper.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.dropwizard5.labels; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.Labels; import java.util.ArrayList; import java.util.List; @@ -10,6 +11,7 @@ * labels and names. Prometheus metric name and labels are extracted from the Dropwizard name based * on the provided list of {@link MapperConfig}s. The FIRST matching config will be used. */ +@StableApi public class CustomLabelMapper { private final List compiledMapperConfigs; diff --git a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/MapperConfig.java b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/MapperConfig.java index 2fced7ef6..46d4d36e4 100644 --- a/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/MapperConfig.java +++ b/prometheus-metrics-instrumentation-dropwizard5/src/main/java/io/prometheus/metrics/instrumentation/dropwizard5/labels/MapperConfig.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.dropwizard5.labels; +import io.prometheus.metrics.annotations.StableApi; import java.util.HashMap; import java.util.Map; import java.util.regex.Pattern; @@ -15,6 +16,7 @@ *

Dropwizard metrics that match the "match" pattern will be further processed to have a new name * and new labels based on this config. */ +@StableApi public final class MapperConfig { // Each part of the metric name between dots. Accepts letters, digits, underscores, hyphens, // colons, and glob wildcards (*) to support a broad range of metric naming conventions. diff --git a/prometheus-metrics-instrumentation-guava/pom.xml b/prometheus-metrics-instrumentation-guava/pom.xml index bb23faf3e..63980781c 100644 --- a/prometheus-metrics-instrumentation-guava/pom.xml +++ b/prometheus-metrics-instrumentation-guava/pom.xml @@ -29,6 +29,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-instrumentation-guava/src/main/java/io/prometheus/metrics/instrumentation/guava/CacheMetricsCollector.java b/prometheus-metrics-instrumentation-guava/src/main/java/io/prometheus/metrics/instrumentation/guava/CacheMetricsCollector.java index 7a66e1d17..b807a28f0 100644 --- a/prometheus-metrics-instrumentation-guava/src/main/java/io/prometheus/metrics/instrumentation/guava/CacheMetricsCollector.java +++ b/prometheus-metrics-instrumentation-guava/src/main/java/io/prometheus/metrics/instrumentation/guava/CacheMetricsCollector.java @@ -3,6 +3,7 @@ import com.google.common.cache.Cache; import com.google.common.cache.CacheStats; import com.google.common.cache.LoadingCache; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.registry.MultiCollector; import io.prometheus.metrics.model.snapshots.CounterSnapshot; import io.prometheus.metrics.model.snapshots.GaugeSnapshot; @@ -51,6 +52,7 @@ * guava_cache_load_duration_seconds_sum{cache="mycache"} 0.0034 * */ +@StableApi public class CacheMetricsCollector implements MultiCollector { private static final double NANOSECONDS_PER_SECOND = 1_000_000_000.0; diff --git a/prometheus-metrics-instrumentation-jvm/pom.xml b/prometheus-metrics-instrumentation-jvm/pom.xml index d50a567e4..5cbdc3bd7 100644 --- a/prometheus-metrics-instrumentation-jvm/pom.xml +++ b/prometheus-metrics-instrumentation-jvm/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-core diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmBufferPoolMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmBufferPoolMetrics.java index 8fc4b87e9..a31d46ba4 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmBufferPoolMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmBufferPoolMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.GaugeWithCallback; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -41,6 +42,7 @@ * jvm_buffer_pool_used_bytes{pool="mapped"} 0.0 * */ +@StableApi public class JvmBufferPoolMetrics { private static final String JVM_BUFFER_POOL_USED_BYTES = "jvm_buffer_pool_used_bytes"; diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmClassLoadingMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmClassLoadingMetrics.java index 34e9dcb8a..28b10cfb7 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmClassLoadingMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmClassLoadingMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.CounterWithCallback; import io.prometheus.metrics.core.metrics.GaugeWithCallback; @@ -37,6 +38,7 @@ * jvm_classes_unloaded_total 0.0 * */ +@StableApi public class JvmClassLoadingMetrics { private static final String JVM_CLASSES_CURRENTLY_LOADED = "jvm_classes_currently_loaded"; diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmCompilationMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmCompilationMetrics.java index 975b6c6a3..86b5cc88d 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmCompilationMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmCompilationMetrics.java @@ -2,6 +2,7 @@ import static io.prometheus.metrics.model.snapshots.Unit.millisToSeconds; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.CounterWithCallback; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -33,6 +34,7 @@ * jvm_compilation_time_seconds_total 0.152 * */ +@StableApi public class JvmCompilationMetrics { private static final String JVM_COMPILATION_TIME_SECONDS_TOTAL = diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmGarbageCollectorMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmGarbageCollectorMetrics.java index a87b52a4f..aec943706 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmGarbageCollectorMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmGarbageCollectorMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.SummaryWithCallback; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -37,6 +38,7 @@ * jvm_gc_collection_seconds_sum{gc="PS Scavenge"} 0.0 * */ +@StableApi public class JvmGarbageCollectorMetrics { private static final String JVM_GC_COLLECTION_SECONDS = "jvm_gc_collection_seconds"; diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryMetrics.java index 1b34dba6c..2fb377882 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.GaugeWithCallback; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -104,6 +105,7 @@ * jvm_memory_used_bytes{area="nonheap"} 1.1490688E7 * */ +@StableApi public class JvmMemoryMetrics { private static final String JVM_MEMORY_OBJECTS_PENDING_FINALIZATION = diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryPoolAllocationMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryPoolAllocationMetrics.java index 5dfb4199b..a8f520584 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryPoolAllocationMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMemoryPoolAllocationMetrics.java @@ -2,6 +2,7 @@ import com.sun.management.GarbageCollectionNotificationInfo; import com.sun.management.GcInfo; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.Counter; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -47,6 +48,7 @@ * jvm_memory_pool_allocated_bytes_total{pool="PS Survivor Space"} 4115280.0 * */ +@StableApi public class JvmMemoryPoolAllocationMetrics { private static final String JVM_MEMORY_POOL_ALLOCATED_BYTES_TOTAL = diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMetrics.java index b0abd86b1..d7ab40d13 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.PrometheusRegistry; import io.prometheus.metrics.model.snapshots.Labels; @@ -13,6 +14,7 @@ * JvmMetrics.builder().register(); * } */ +@StableApi public class JvmMetrics { private static final Set REGISTERED = ConcurrentHashMap.newKeySet(); diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmNativeMemoryMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmNativeMemoryMetrics.java index 6b11df38a..d08e3fb11 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmNativeMemoryMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmNativeMemoryMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.GaugeWithCallback; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -85,6 +86,7 @@ * jvm_native_memory_reserved_bytes{pool="Unknown"} 32768.0 * */ +@StableApi public class JvmNativeMemoryMetrics { private static final String JVM_NATIVE_MEMORY_RESERVED_BYTES = "jvm_native_memory_reserved_bytes"; private static final String JVM_NATIVE_MEMORY_COMMITTED_BYTES = diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmRuntimeInfoMetric.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmRuntimeInfoMetric.java index 58363780f..095b643b0 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmRuntimeInfoMetric.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmRuntimeInfoMetric.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.Info; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -26,6 +27,7 @@ * jvm_runtime_info{runtime="OpenJDK Runtime Environment",vendor="Oracle Corporation",version="1.8.0_382-b05"} 1 * */ +@StableApi public class JvmRuntimeInfoMetric { private static final String JVM_RUNTIME_INFO = "jvm_runtime_info"; diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmThreadsMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmThreadsMetrics.java index 0e98e29d3..af41887bf 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmThreadsMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/JvmThreadsMetrics.java @@ -2,6 +2,7 @@ import static java.util.Objects.requireNonNull; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.CounterWithCallback; import io.prometheus.metrics.core.metrics.GaugeWithCallback; @@ -61,6 +62,7 @@ * jvm_threads_state{state="WAITING"} 3.0 * */ +@StableApi public class JvmThreadsMetrics { private static final String UNKNOWN = "UNKNOWN"; diff --git a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/ProcessMetrics.java b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/ProcessMetrics.java index b341f848a..6132ad08e 100644 --- a/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/ProcessMetrics.java +++ b/prometheus-metrics-instrumentation-jvm/src/main/java/io/prometheus/metrics/instrumentation/jvm/ProcessMetrics.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.instrumentation.jvm; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.core.metrics.CounterWithCallback; import io.prometheus.metrics.core.metrics.GaugeWithCallback; @@ -67,6 +68,7 @@ * process_virtual_memory_bytes 1.2683624448E10 * */ +@StableApi public class ProcessMetrics { private static final String PROCESS_CPU_SECONDS_TOTAL = "process_cpu_seconds_total"; diff --git a/prometheus-metrics-model/pom.xml b/prometheus-metrics-model/pom.xml index cdac0a60b..c1a83dea0 100644 --- a/prometheus-metrics-model/pom.xml +++ b/prometheus-metrics-model/pom.xml @@ -22,6 +22,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-config diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java index f903ce676..0f2ccd516 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.registry; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.MetricFamilyDescriptor; import io.prometheus.metrics.model.snapshots.MetricMetadata; import io.prometheus.metrics.model.snapshots.MetricSnapshot; @@ -13,6 +14,7 @@ * href="https://prometheus.io/docs/instrumenting/writing_clientlibs/">https://prometheus.io/docs/instrumenting/writing_clientlibs/. */ @FunctionalInterface +@StableApi public interface Collector { /** Called when the Prometheus server scrapes metrics. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricNameFilter.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricNameFilter.java index 609f7fd33..642f27150 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricNameFilter.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricNameFilter.java @@ -2,6 +2,7 @@ import static java.util.Collections.unmodifiableCollection; +import io.prometheus.metrics.annotations.StableApi; import java.util.ArrayList; import java.util.Arrays; import java.util.Collection; @@ -9,6 +10,7 @@ import javax.annotation.Nullable; /** Filter samples (i.e. time series) by name. */ +@StableApi public class MetricNameFilter implements Predicate { /** For convenience, a filter that allows all names. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricType.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricType.java index 5258da84e..f1b5d76ba 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricType.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricType.java @@ -1,11 +1,14 @@ package io.prometheus.metrics.model.registry; +import io.prometheus.metrics.annotations.StableApi; + /** * Represents the type of Prometheus metric. * *

This enum is used for registration-time validation to ensure that metrics with the same name * have consistent types across all registered collectors. */ +@StableApi public enum MetricType { COUNTER, GAUGE, diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java index 692f0be71..54ce8c47c 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.registry; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.MetricFamilyDescriptor; import io.prometheus.metrics.model.snapshots.MetricMetadata; import io.prometheus.metrics.model.snapshots.MetricSnapshot; @@ -13,6 +14,7 @@ /** Like {@link Collector}, but collecting multiple Snapshots at once. */ @FunctionalInterface +@StableApi public interface MultiCollector { /** Called when the Prometheus server scrapes metrics. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java index 071c90f4b..882f5711d 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java @@ -2,6 +2,7 @@ import static java.util.Collections.emptySet; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.model.snapshots.MetricFamilyDescriptor; import io.prometheus.metrics.model.snapshots.MetricMetadata; import io.prometheus.metrics.model.snapshots.MetricSnapshot; @@ -17,6 +18,7 @@ import java.util.function.Predicate; import javax.annotation.Nullable; +@StableApi public class PrometheusRegistry { public static final PrometheusRegistry defaultRegistry = new PrometheusRegistry(); diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusScrapeRequest.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusScrapeRequest.java index 91a1313ab..2ec6c768f 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusScrapeRequest.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusScrapeRequest.java @@ -1,8 +1,10 @@ package io.prometheus.metrics.model.registry; +import io.prometheus.metrics.annotations.StableApi; import javax.annotation.Nullable; /** Infos extracted from the request received by the endpoint */ +@StableApi public interface PrometheusScrapeRequest { /** Absolute path of the HTTP request. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBucket.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBucket.java index ebadd1f16..0f487efdf 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBucket.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBucket.java @@ -1,9 +1,12 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; + /** * Helper class for iterating over {@link ClassicHistogramBuckets}. Note that the {@code count} is * not cumulative. */ +@StableApi public class ClassicHistogramBucket implements Comparable { private final long count; // not cumulative diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBuckets.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBuckets.java index c697bee39..b2998d799 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBuckets.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ClassicHistogramBuckets.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; @@ -11,6 +12,7 @@ * Immutable container for histogram buckets with fixed bucket boundaries. Note that the counts are * not cumulative. */ +@StableApi public class ClassicHistogramBuckets implements Iterable { /** Used in native histograms to indicate that no classic histogram buckets are present. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/CounterSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/CounterSnapshot.java index e5831168b..42a06f3bb 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/CounterSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/CounterSnapshot.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import java.util.ArrayList; import java.util.Collection; @@ -7,6 +8,7 @@ import javax.annotation.Nullable; /** Immutable snapshot of a Counter. */ +@StableApi public class CounterSnapshot extends MetricSnapshot { /** diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DataPointSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DataPointSnapshot.java index d960912a0..910e2ef50 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DataPointSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DataPointSnapshot.java @@ -1,8 +1,10 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; @SuppressWarnings("this-escape") +@StableApi public abstract class DataPointSnapshot { private final Labels labels; private final long createdTimestampMillis; diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DistributionDataPointSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DistributionDataPointSnapshot.java index 1ae0559e1..2d1331915 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DistributionDataPointSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DistributionDataPointSnapshot.java @@ -1,9 +1,12 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; + /** * Common base class for histogram and summary data. Histograms and Summaries represent * distributions, like a latency distribution or a distribution of request sizes in Bytes. */ +@StableApi public abstract class DistributionDataPointSnapshot extends DataPointSnapshot { private final long count; // optional, negative value means no count. private final double sum; // optional, Double.NaN means no sum. diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DuplicateLabelsException.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DuplicateLabelsException.java index 721655105..fd1e6d838 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DuplicateLabelsException.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/DuplicateLabelsException.java @@ -1,9 +1,12 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; + /** * Thrown when a collector tries to create a {@link MetricSnapshot} where multiple data points have * the same labels (same label names and label values). */ +@StableApi public class DuplicateLabelsException extends IllegalArgumentException { private static final long serialVersionUID = 0L; diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplar.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplar.java index 418603580..07dc811f8 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplar.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplar.java @@ -2,9 +2,11 @@ import static java.util.Objects.requireNonNull; +import io.prometheus.metrics.annotations.StableApi; import javax.annotation.Nullable; /** Immutable representation of an Exemplar. */ +@StableApi public class Exemplar { /** Label name for trace id. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplars.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplars.java index 887a80fff..1408419b7 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplars.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Exemplars.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import java.util.ArrayList; import java.util.Arrays; import java.util.Collection; @@ -14,6 +15,7 @@ *

This is currently backed by a {@code List}. May be refactored later to use a more * efficient data structure. */ +@StableApi public class Exemplars implements Iterable { /** EMPTY means no Exemplars. */ diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/GaugeSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/GaugeSnapshot.java index 03474852f..7a4208b05 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/GaugeSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/GaugeSnapshot.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import java.util.ArrayList; import java.util.Collection; @@ -7,6 +8,7 @@ import javax.annotation.Nullable; /** Immutable snapshot of a Gauge. */ +@StableApi public final class GaugeSnapshot extends MetricSnapshot { /** diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/HistogramSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/HistogramSnapshot.java index acc78d3d3..06c687c9f 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/HistogramSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/HistogramSnapshot.java @@ -1,11 +1,13 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import java.util.ArrayList; import java.util.Collection; import java.util.List; /** Immutable snapshot of a Histogram. */ +@StableApi public final class HistogramSnapshot extends MetricSnapshot { private final boolean gaugeHistogram; diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/InfoSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/InfoSnapshot.java index 20f9038b1..0178eea2e 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/InfoSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/InfoSnapshot.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import java.util.ArrayList; import java.util.Collection; @@ -7,6 +8,7 @@ import javax.annotation.Nullable; /** Immutable snapshot of an Info metric. */ +@StableApi public final class InfoSnapshot extends MetricSnapshot { /** diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Label.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Label.java index 45acd56ee..7af8d3310 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Label.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/Label.java @@ -1,8 +1,10 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import java.util.Objects; /** Utility for iterating over {@link Labels}. */ +@StableApi public final class Label implements Comparable

Note that in Prometheus, units are largely based on SI base units (seconds, bytes, joules, * grams, meters, ratio, volts, amperes, and Celsius). */ +@StableApi public final class Unit { private final String name; diff --git a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/UnknownSnapshot.java b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/UnknownSnapshot.java index 09574d6cd..66e09abe0 100644 --- a/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/UnknownSnapshot.java +++ b/prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/UnknownSnapshot.java @@ -1,5 +1,6 @@ package io.prometheus.metrics.model.snapshots; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.EscapingScheme; import java.util.ArrayList; import java.util.Collection; @@ -7,6 +8,7 @@ import javax.annotation.Nullable; /** Immutable snapshot of an Unknown (Untyped) metric. */ +@StableApi public final class UnknownSnapshot extends MetricSnapshot { /** diff --git a/prometheus-metrics-simpleclient-bridge/pom.xml b/prometheus-metrics-simpleclient-bridge/pom.xml index 02e768c82..b33e0e020 100644 --- a/prometheus-metrics-simpleclient-bridge/pom.xml +++ b/prometheus-metrics-simpleclient-bridge/pom.xml @@ -21,6 +21,12 @@ + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + io.prometheus prometheus-metrics-model diff --git a/prometheus-metrics-simpleclient-bridge/src/main/java/io/prometheus/metrics/simpleclient/bridge/SimpleclientCollector.java b/prometheus-metrics-simpleclient-bridge/src/main/java/io/prometheus/metrics/simpleclient/bridge/SimpleclientCollector.java index 3a96453e7..b2d724997 100644 --- a/prometheus-metrics-simpleclient-bridge/src/main/java/io/prometheus/metrics/simpleclient/bridge/SimpleclientCollector.java +++ b/prometheus-metrics-simpleclient-bridge/src/main/java/io/prometheus/metrics/simpleclient/bridge/SimpleclientCollector.java @@ -5,6 +5,7 @@ import io.prometheus.client.Collector; import io.prometheus.client.CollectorRegistry; +import io.prometheus.metrics.annotations.StableApi; import io.prometheus.metrics.config.PrometheusProperties; import io.prometheus.metrics.model.registry.MultiCollector; import io.prometheus.metrics.model.registry.PrometheusRegistry; @@ -54,6 +55,7 @@ * .register(prometheusRegistry); * } */ +@StableApi public class SimpleclientCollector implements MultiCollector { private final CollectorRegistry simpleclientRegistry; diff --git a/prometheus-metrics-tracer/prometheus-metrics-tracer-common/pom.xml b/prometheus-metrics-tracer/prometheus-metrics-tracer-common/pom.xml index 88ed86387..011b40217 100644 --- a/prometheus-metrics-tracer/prometheus-metrics-tracer-common/pom.xml +++ b/prometheus-metrics-tracer/prometheus-metrics-tracer-common/pom.xml @@ -20,4 +20,13 @@ io.prometheus.metrics.tracer.common + + + io.prometheus + prometheus-metrics-annotations + ${project.version} + true + + + diff --git a/prometheus-metrics-tracer/prometheus-metrics-tracer-common/src/main/java/io/prometheus/metrics/tracer/common/SpanContext.java b/prometheus-metrics-tracer/prometheus-metrics-tracer-common/src/main/java/io/prometheus/metrics/tracer/common/SpanContext.java index f2c171a10..4da3b13ea 100644 --- a/prometheus-metrics-tracer/prometheus-metrics-tracer-common/src/main/java/io/prometheus/metrics/tracer/common/SpanContext.java +++ b/prometheus-metrics-tracer/prometheus-metrics-tracer-common/src/main/java/io/prometheus/metrics/tracer/common/SpanContext.java @@ -1,7 +1,9 @@ package io.prometheus.metrics.tracer.common; +import io.prometheus.metrics.annotations.StableApi; import javax.annotation.Nullable; +@StableApi public interface SpanContext { String EXEMPLAR_ATTRIBUTE_NAME = "exemplar"; From c42945c2586811b3ce07d2425936c075e3900990 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 2 Jun 2026 11:36:53 +0200 Subject: [PATCH 2/2] docs: remove stable-api-rationale.md review aid Signed-off-by: Gregor Zeitlinger --- docs/stable-api-rationale.md | 325 ----------------------------------- 1 file changed, 325 deletions(-) delete mode 100644 docs/stable-api-rationale.md diff --git a/docs/stable-api-rationale.md b/docs/stable-api-rationale.md deleted file mode 100644 index 5a8a3235b..000000000 --- a/docs/stable-api-rationale.md +++ /dev/null @@ -1,325 +0,0 @@ -# Stable API rationale - -This file records the first-pass guess for the `@StableApi` surface. - -The guess is intentionally conservative about user-facing entry points, but it also includes -supporting public value types when they appear in signatures of those entry points. The -annotation is currently applied to top-level types. Public nested builders and data point -snapshots are treated as part of the annotated enclosing type. - -Evidence labels: - -- D-core: documented in getting-started metric, label, callback, registry, or - multi-target docs. -- D-config: documented in `docs/content/config/config.md`. -- D-exporter: documented in exporter docs under `docs/content/exporters/`. -- D-instr: documented in instrumentation docs under `docs/content/instrumentation/`. -- D-migration: documented in `docs/content/migration/simpleclient.md`. -- D-otel: documented in OpenTelemetry docs under `docs/content/otel/`. -- M: imported or used by Micrometer's Prometheus registry or samples. -- J: imported or used by Prometheus JMX Exporter's collector, common, agent, or tests. -- S: support type in the public signatures or returned snapshots of another stable API. -- T: tooling contract for the API diff mechanism itself. - -Entries justified only by S are the weakest guesses. They are included because excluding them -would make a documented or externally used API hard to use without unstable public types. - -## Annotation module - -### `io.prometheus.metrics.annotations` - -- `StableApi`: T. This is the opt-in marker used by japicmp and by humans to decide - which public types are part of the published compatibility contract. - -## Config - -### `io.prometheus.metrics.config` - -- `EscapingScheme`: D-config, D-exporter. PushGateway and unicode docs expose escaping - selection, and the type is accepted by documented builder methods. -- `ExemplarsProperties`: D-config, M. Micrometer constructs exemplar sampler config from - this type, and the config docs link its getters directly. -- `ExporterFilterProperties`: D-config. Exporter filtering is documented as runtime - configuration and maps to this public properties type. -- `ExporterHttpServerProperties`: D-config. The HTTP server exporter settings are - documented and map to this public properties type. -- `ExporterOpenTelemetryProperties`: D-config, D-otel. OTLP exporter settings are - documented and map to this public properties type. -- `ExporterProperties`: D-config. Exporter-wide options such as exemplar behavior are - documented and exposed through this public type. -- `ExporterPushgatewayProperties`: D-config, D-exporter. PushGateway runtime settings are - documented and map to this public properties type. -- `MetricsProperties`: D-config. Core metric defaults such as histogram and summary - options are documented and exposed through this type. -- `OpenMetrics2Properties`: D-config, D-exporter. OM2 is experimental, but the public - docs link this type and its getters explicitly. -- `PrometheusProperties`: D-config, D-exporter, D-otel, M, J. It is the root config type - used by docs, Micrometer, and JMX Exporter. -- `PrometheusPropertiesException`: S. Public exception thrown by the public config loader - and builder path; callers may catch it. -- `PrometheusPropertiesLoader`: D-config, M. The config docs describe loading runtime - configuration, and Micrometer imports this loader. - -## Core datapoints and timers - -### `io.prometheus.metrics.core.datapoints` - -- `CounterDataPoint`: S. Returned by documented `Counter` label accessors and callback - APIs, so users can increment labeled counters. -- `DataPoint`: S. Common public supertype for metric child handles returned by stable - metric APIs. -- `DistributionDataPoint`: S. Common public supertype behind histogram and summary child - handles, including observe and exemplar operations. -- `GaugeDataPoint`: S. Returned by documented `Gauge` label accessors and callback APIs, - so users can set and adjust labeled gauges. -- `StateSetDataPoint`: S. Returned by documented `StateSet` APIs, so users can set named - state values. -- `Timer`: D-core, S. Returned by documented timer helpers used to time histogram and - summary observations. -- `TimerApi`: D-core. The metric type docs link this interface for timing APIs on - histogram and summary metrics. - -## Core exemplars - -### `io.prometheus.metrics.core.exemplars` - -- `ExemplarSampler`: M, D-otel. Micrometer imports it for exemplar sampling, and the OTel - tracing docs describe exemplar behavior as an integration surface. -- `ExemplarSamplerConfig`: M. Micrometer imports it to configure exemplar sampler - creation. - -## Core metrics - -### `io.prometheus.metrics.core.metrics` - -- `Counter`: D-core, D-migration, D-otel, J. It is a primary metric type in docs and is - imported by JMX Exporter. -- `CounterWithCallback`: D-core. The callback docs list it as the counter callback metric - type. -- `Gauge`: D-core, D-exporter, J. It is a primary metric type in docs and is imported by - JMX Exporter. -- `GaugeWithCallback`: D-core. The callback docs list it as the gauge callback metric - type and show examples. -- `Histogram`: D-core, D-config. It is a primary metric type in docs, including classic - and native histogram configuration. -- `Info`: D-core, D-exporter, J. The metric type and OM2 docs describe info metrics, and - JMX Exporter imports it for build info. -- `Metric`: S. Public common base for documented metric classes and their shared builder - behavior. -- `MetricWithFixedMetadata`: S. Public base for documented metric classes whose metadata - is fixed at build time. -- `SlidingWindow`: S. Public summary configuration type used by summary implementation - and exposed through public summary behavior. -- `StateSet`: D-core. The metric type docs document StateSet as an OpenMetrics metric - type and show builder usage. -- `StatefulMetric`: S. Public base for documented metric classes that expose label child - handles. -- `Summary`: D-core, D-config, D-migration. It is a primary metric type in docs and is - covered by documented quantile and age configuration. -- `SummaryWithCallback`: D-core. The callback docs list it as the summary callback metric - type and show examples. - -## Exporter common - -### `io.prometheus.metrics.exporter.common` - -- `PrometheusHttpExchange`: S. Public exchange abstraction used by the stable scrape - handler so non-server adapters can plug in. -- `PrometheusHttpRequest`: S. Public request abstraction used by `PrometheusScrapeHandler`. -- `PrometheusHttpResponse`: S. Public response abstraction used by `PrometheusScrapeHandler`. -- `PrometheusScrapeHandler`: S, D-exporter. Shared public scrape handler behind documented - HTTP and servlet exporters. - -## HTTP server exporter - -### `io.prometheus.metrics.exporter.httpserver` - -- `DefaultHandler`: J, D-exporter. JMX Exporter imports it to configure HTTP endpoints; - HTTP server docs mention default endpoint behavior. -- `HTTPServer`: D-core, D-exporter, D-otel, J. It is the documented standalone exporter - and is imported by JMX Exporter. -- `HealthyHandler`: J, D-exporter. JMX Exporter imports it for the health endpoint; the - HTTP server docs document health endpoint behavior. -- `MetricsHandler`: J, D-exporter. JMX Exporter imports it for the metrics endpoint; the - HTTP server docs document metrics endpoint behavior. - -## OpenTelemetry exporter - -### `io.prometheus.metrics.exporter.opentelemetry` - -- `OpenTelemetryExporter`: D-config, D-otel, J. The OTLP docs use its builder directly, - and JMX Exporter imports it for OTel mode. - -## PushGateway exporter - -### `io.prometheus.metrics.exporter.pushgateway` - -- `DefaultHttpConnectionFactory`: S. Public default implementation of the documented - PushGateway connection extension point. -- `Format`: S, D-exporter. Public enum controlling the documented PushGateway wire format. -- `HttpConnectionFactory`: S. Public extension point accepted by `PushGateway.Builder`. -- `PushGateway`: D-config, D-exporter. The PushGateway docs use this type and its builder - throughout. -- `Scheme`: S, D-config. Public scheme enum accepted by documented PushGateway builder - and config paths. - -## Servlet exporters - -### `io.prometheus.metrics.exporter.servlet.jakarta` - -- `PrometheusMetricsServlet`: D-exporter. Servlet and Spring docs show direct - registration of the Jakarta servlet class. - -### `io.prometheus.metrics.exporter.servlet.javax` - -- `PrometheusMetricsServlet`: D-exporter. The javax artifact is the legacy servlet - counterpart of the documented Jakarta servlet entry point. - -## Exposition formats - -### `io.prometheus.metrics.expositionformats` - -- `ExpositionFormatWriter`: S. Public writer interface behind the documented exposition - format selection and custom writer implementations. -- `ExpositionFormats`: M, D-exporter. Micrometer imports it for scraping, and exporter - docs describe content negotiation between formats. -- `OpenMetrics2TextFormatWriter`: D-exporter. OM2 preview docs document the experimental - OM2 writer path. -- `OpenMetricsTextFormatWriter`: M, D-exporter. Micrometer tests import it, and exporter - docs describe OpenMetrics text output. -- `PrometheusProtobufWriter`: D-exporter. Exporter docs mention this class by name for - shaded PushGateway jars. -- `PrometheusTextFormatWriter`: M, D-exporter. Micrometer tests import it, and exporter - docs describe Prometheus text output. - -## Instrumentation - -### `io.prometheus.metrics.instrumentation.caffeine` - -- `CacheMetricsCollector`: D-instr. The caffeine instrumentation docs describe registering - this collector for cache metrics. - -### `io.prometheus.metrics.instrumentation.dropwizard` - -- `DropwizardExports`: S. Dropwizard 4 is a shipped instrumentation module and equivalent - public entry point to the documented Dropwizard 5 exporter. - -### `io.prometheus.metrics.instrumentation.dropwizard5` - -- `DropwizardExports`: S. Dropwizard 5 is a shipped instrumentation module with public - registration entry point. -- `InvalidMetricHandler`: S. Public extension point used by Dropwizard exports to decide - how invalid Dropwizard metrics are handled. - -### `io.prometheus.metrics.instrumentation.dropwizard5.labels` - -- `CustomLabelMapper`: S. Public extension point for Dropwizard 5 custom label mapping. -- `MapperConfig`: S. Public configuration value consumed by `CustomLabelMapper`. - -### `io.prometheus.metrics.instrumentation.guava` - -- `CacheMetricsCollector`: D-instr. The guava instrumentation docs describe registering - this collector for cache metrics. - -### `io.prometheus.metrics.instrumentation.jvm` - -- `JvmBufferPoolMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `JvmClassLoadingMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `JvmCompilationMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `JvmGarbageCollectorMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `JvmMemoryMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `JvmMemoryPoolAllocationMetrics`: S, D-instr. Public component metric used by aggregate - JVM instrumentation. -- `JvmMetrics`: D-core, D-instr, D-migration, J. Quickstart, migration, and JMX Exporter - use this aggregate JVM instrumentation entry point. -- `JvmNativeMemoryMetrics`: D-instr. Native memory tracking is documented as part of JVM - instrumentation. -- `JvmRuntimeInfoMetric`: D-instr. The JVM docs link this metric class directly. -- `JvmThreadsMetrics`: S, D-instr. Public component metric used by aggregate JVM - instrumentation. -- `ProcessMetrics`: S, D-instr. Public process metric component used by aggregate JVM - instrumentation. - -## Registry - -### `io.prometheus.metrics.model.registry` - -- `Collector`: D-core, S. Public extension point for custom collectors registered in a - `PrometheusRegistry`. -- `MetricNameFilter`: S. Public filter accepted by registry scrape collection paths. -- `MetricType`: S. Public enum used in metadata and snapshot APIs. -- `MultiCollector`: M, J, D-core. Micrometer and JMX Exporter implement or import it, and - multi-target docs show a custom collector pattern. -- `PrometheusRegistry`: D-core, D-migration, D-otel, M, J. It is the central registry in - docs and a direct dependency of Micrometer and JMX Exporter. -- `PrometheusScrapeRequest`: D-core, S. Multi-target docs show scrape-request-aware - collection; the type is required for that extension point. - -## Snapshots - -### `io.prometheus.metrics.model.snapshots` - -- `ClassicHistogramBucket`: M, S. Micrometer uses classic histogram bucket snapshots, and - this is the public value type for one bucket. -- `ClassicHistogramBuckets`: M, S. Micrometer uses it when reading histogram snapshots. -- `CounterSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in - multi-target custom collector examples. -- `DataPointSnapshot`: M, J, D-core. Common public base for snapshot data points used by - Micrometer, JMX Exporter, and custom collector docs. -- `DistributionDataPointSnapshot`: S. Public base for histogram and summary data point - snapshots returned by documented distribution metrics. -- `DuplicateLabelsException`: J, S. JMX Exporter tests catch duplicate-label behavior; - custom collectors can encounter this public validation exception. -- `Exemplar`: M, D-otel. Micrometer creates exemplar snapshots, and OTel tracing docs - describe exemplar output. -- `Exemplars`: M, D-otel. Micrometer creates exemplar containers, and OTel tracing docs - describe exemplar output. -- `GaugeSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in - multi-target custom collector examples. -- `HistogramSnapshot`: M, D-core. Micrometer reads histogram snapshots, and histogram is a - documented primary metric type. -- `InfoSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter for info metrics. -- `Label`: S. Public value type contained by `Labels` and snapshot APIs. -- `Labels`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in label and - multi-target docs. -- `MetricMetadata`: M, J, S. Used by Micrometer and JMX Exporter when building custom - snapshots. -- `MetricFamilyDescriptor`: S. Registration-time descriptor returned by the stable - `Collector` and `MultiCollector` extension points. -- `MetricSnapshot`: M, J, D-core. Used by Micrometer and JMX Exporter, and shown in - registry and multi-target docs. -- `MetricSnapshots`: M, J, D-core. Used by Micrometer and JMX Exporter, and returned by - custom collector examples. -- `NativeHistogramBucket`: S. Public value type for native histogram snapshots, needed - because native histograms are documented metric output. -- `NativeHistogramBuckets`: S. Public container for native histogram snapshot buckets. -- `PrometheusNaming`: M, J, D-core. Micrometer and JMX Exporter use it for name - sanitizing, and multi-target docs show it directly. -- `Quantile`: S, D-core. Public value type for summary quantiles, which are documented in - summary and callback APIs. -- `Quantiles`: M, D-core. Micrometer uses it and summary docs expose quantile behavior. -- `StateSetSnapshot`: S, D-core. Public snapshot type for the documented StateSet metric. -- `SummarySnapshot`: M, D-core. Micrometer reads summary snapshots, and summary is a - documented primary metric type. -- `Unit`: J, S. JMX Exporter imports it, and unit metadata appears throughout documented - metric and naming behavior. -- `UnknownSnapshot`: J, S. JMX Exporter builds unknown snapshots for untyped JMX metrics. - -## Simpleclient bridge - -### `io.prometheus.metrics.simpleclient.bridge` - -- `SimpleclientCollector`: D-migration. Migration docs use this bridge as the supported - path for simpleclient 0.x metrics. - -## Tracer common - -### `io.prometheus.metrics.tracer.common` - -- `SpanContext`: M, D-otel. Micrometer imports it for exemplars, and OTel tracing docs - describe span context propagation into exemplars.