1.2.1 / 2024-04-23

Minor release to help Spring Boot adopt client_java 1.x in the Micrometer Prometheus registry.

• [ENHANCEMENT] add a method for initializing PrometheusProperties with an external properties map. This can be used to load properties from Spring configuration. Thanks @jonatan-ivanov
• [ENHANCEMENT] remove import statement for SpanContextSupplier so that the code still runs if the prometheus-metrics-tracer-initializer dependency is excluded from the classpath (Micrometer implements it's own SpanContextSupplier and doesn't need the dependency).
• [BUGFIX] fix Javadoc links. Thanks @shakuzen.

1.2.0 / 2024-03-22

The 1.2.0 release has some nice features and enhancements. Thanks a lot to everyone who contributed.

• [FEATURE] new Dropwizard instrumentation module prometheus-metrics-instrumentation-dropwizard5. Thanks @kingster
• [FEATURE] new Javax exporter servlet module prometheus-metrics-exporter-servlet-javax. Thanks @kingster
• [FEATURE] expose native memory metrics when the JVM was started with -XX:NativeMemoryTracking=summary. Thanks @meier-christoph
• [FEATURE] minor API additions: get() methods for Counter and Gauge, clear() method for all metrics.
• [FEATURE] add Exemplars to Histogram _count if the config option exemplarsOnAllMetricTypes is enabled.
• [ENHANCEMENT] remove Exemplars from Summary _sum, because it's sufficient to have Exemplars on _count.
• [BUGFIX] error handling when the HTTP connection closes unexpectedly during scrape. Thanks @dhoard
• [ENHANCEMENT] add BOM (bill of materials) module prometheus-metrics-bom.

1.1.0 / 2023-11-12

This release contains lots of smaller fixes and enhancements to the 1.0.0 release. Thanks a lot to everyone who contributed.

• [ENHANCEMENT] Avoid duplicate call to the scrape() method in the default Collector implementation. This does not affect the core metrics, because the core metrics override getPrometheusName(), so they don't use the default implementation.
• [BUGFIX] Fix unit for process_cpu_seconds_total #881. Thanks @yrn1.
• [ENHANCEMENT] Add automatic module names #871. This removes a warning for users of Java 9 modules. Thanks @solomax.
• [FEATURE] Add API to support the multi target exporter pattern #873. Thanks @ganzuoni.
• [ENHANCEMENT] Add Exemplar support for the OpenTelemetry OTLP exporter #883. Thanks @0x006EA1E5.
• [BUGIFX] Fix histogram bucket boundaries in the prometheus-metrics-simpleclient-bridge #887. Thanks @turchenkoalex.
• [BUGFIX] Fix sliding window for Summary metrics #894. Thanks @yrn1.
• [ENHANCEMENT] Add equals() and hashCode() to Unit #897. Thanks @dhoard.
• [ENHANCEMENT] Bump dependency versions #899.

1.0.0 / 2023-09-27

The Prometheus Java client 1.0.0 is available!

The Prometheus Java client 1.0.0 release is a complete rewrite of the underlying data model.

The main new features are:

• Prometheus native histograms: Support for the new Prometheus histogram type.
• OpenTelemetry Exporter: Push metrics in OTLP format to an OpenTelemetry endpoint.
• Runtime configuration: Configure metrics, exporters, and more at runtime using a properties file or system properties.

Documentation and Examples

We launched a new documentation page on https://prometheus.github.io/client_java/, and created an examples/ directory with end-to-end scenarios (Docker compose) illustrating new features.

Performance Benchmarks

Initial performance benchmarks are looking great: All core metric types (including native histograms) allow concurrent updates, so if you instrument a performance critical Web service that utilizes all processor cores in parallel the metrics library will not introduce additional synchronization. See Javadoc comments in benchmarks/ for benchmark results.

More Info

The Grafana Labs Blog has a post Introducing the Prometheus Java Client 1.0.0 with a good overview of the release.

There will also be a presentation at the PromCon conference on 29 Sep 2023. Tune in to the live stream on https://promcon.io or watch the recording on YouTube.

For users of the 0.16.0 version and older

Updating to the 1.0.0 version is a breaking change. However, there's a prometheus-metrics-simpleclient-bridge module available that allows you to use your existing simpleclient 0.16.0 metrics with the new 1.0.0 PrometheusRegistry. So you don't need to upgrade your instrumentation code, you can keep using your existing metrics. See the simpleclient section on the new docs page.

The pre 1.0.0 code is now maintained on the simpleclient feature branch.

Not all simpleclient modules from 0.16.0 are included in the initial 1.0.0 release. Over the next couple of weeks we will work on porting the remaining modules, starting with pushgateway and the Servlet filter.

1.0.0-beta-1 / 2023-09-16

The first beta of the upcoming Prometheus metrics library 1.0.0 is available!

It's a major breaking change, because we refactored the builder pattern to be aligned with Lombok conventions. Example of the new API:

Counter counter = Counter.builder()
    .name("events_total")
    .help("total number of events")
    .labelNames("status")
    .register();

This replaces the verbose builders from the alpha releases:

// old API, no longer available
Counter counter = Counter.newBuilder()
    .withName("events_total")
    .withHelp("total number of events")
    .withLabelNames("status")
    .register();

Moreover, we started publishing docs on https://prometheus.github.io/client_java/.

If you want to get started, the new docs have a quickstart guide: https://prometheus.github.io/client_java/getting-started/quickstart/.

The target is to finalize the docs and the 1.0.0 release before PromCon, which is 28/29 September 2023. We do not expect any more breaking changes, except for smaller things that come up while writing documentation.

1.0.0-alpha-5 / 2023-09-13

This is the current pre-release of the upcoming 1.0.0 version.

It adds the prometheus-metrics-simpleclinet-bridge module, which is the backwards-compatibility module for existing simpleclient metrics (client_java <= 0.16.0).

To include all metrics from the default simpliclient CollectorRegistry in the new default PrometheusRegistry, just add this line:

SimpleclientCollector
        .newBuilder()
        .register();

See the examples/example-simpleclient-bridge on the 1.0.x branch.

This completes the initial functionality for the 1.0.0 release. Next step is some refactoring (we want to rename all Builder methods to Lombok naming conventions because that's what people are used to from Spring). And finally, we need to add a lot of documentation!

1.0.0-alpha-4 / 2023-09-07

This is the current pre-release for the upcoming 1.0.0 version.

It adds the prometheus-metrics-instrumentation-jvm module, which is a port of the simpleclient default exports to the new metrics library:

JvmMetrics
        .newBuilder()
        .register();

If a unit is present, the new metrics library requires the unit to be the last part of the metric name, as defined in Prometheus Metric and Label Naming. Therefore we had to rename a few default metrics:

• jvm_memory_bytes_init -> jvm_memory_init_bytes
• jvm_memory_bytes_committed -> jvm_memory_committed_bytes
• jvm_memory_bytes_max -> jvm_memory_max_bytes
• jvm_memory_bytes_used -> jvm_memory_used_bytes
• jvm_memory_pool_bytes_init -> jvm_memory_pool_init_bytes
• jvm_memory_pool_bytes_committed -> jvm_memory_pool_committed_bytes
• jvm_memory_pool_bytes_max -> jvm_memory_pool_max_bytes
• jvm_memory_pool_bytes_used -> jvm_memory_pool_used_bytes

Apart from that, jvm_info was renamed to jvm_runtime_info.

If these breaking changes are an issue: There will be a compatibility module that will allow you to use the old simpleclient default exports with the new metrics library.

There still isn't much documentation yet, but for each new module there's an end-to-end example and a README in the examples/ directory (on the 1.0.x branch).

The next features on the roadmap towards 1.0.0 is a backwards-compatibility module for existing simpleclient.

1.0.0-alpha-3 / 2023-08-29

This is the current pre-release for the upcoming 1.0.0 version.

It adds two major new modules:

• prometheus-metrics-exporter-httpserver is a built-in HTTP server for exposing Promtheus metrics (this is a port of simpleclient_httpserver).
• prometheus-metrics-exporter-opentelemetry is an exporter for pushing metrics to an OpenTelemetry endpoint in OTLP format.

In addition to these new features, there was a lot of internal refactoring.

There isn't much documentation yet, but for each new module there's an end-to-end example and a README in the examples/ directory (on the 1.0.x branch).

The next features on the roadmap towards 1.0.0 are a port of the built-in JVM metrics, and a backwards-compatibility module for existing simpleclient.

1.0.0-alpha-2 / 2023-07-27

This release is an internal refactoring to prepare for better integration with OpenTelemetry metrics in the future.

User facing functionality like API and exposition formats are the same as in 1.0.0-alpha-1.

We also started adding more documentation

• example-tomcat-servlet: Simple example with a Tomcat servlet to get started with Prometheus native histograms.
• example-exemplars-tail-sampling: Example of how to use Exemplars with OpenTelemetry's Tail Sampling.

The source code is on the 1.0.x branch.

1.0.0-alpha-1 / 2023-07-17

First pre-release of the upcoming Prometheus metrics library. The main feature is support for the new Prometheus native histograms. This release contains the following modules:

• prometheus-metrics-core - core metric library.
• prometheus-metrics-model - data model for read-only immutable Prometheus metrics snapshots.
• prometheus-metrics-exposition-formats - text format, OpenMetrics format, Prometheus protobuf format.
• prometheus-metrics-config - runtime configuration, e.g. for configuring new histogram buckets at runtime.
• prometheus-metrics-exporter-servlet-jakarta - exporter servlet.

These modules are currently independent of the existing simpleclient modules. Before releasing 1.0.0 we will implement a bridge from simpleclient_* to prometheus-metrics-* for backwards compatibility.

The source code is on the 1.0.x branch.

There is a tomcat-servlet-example project for trying the new metrics library (see README).