diff --git a/README.md b/README.md index 6216afb..d45eb6d 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,20 @@ -_(If you are reading this because you are interested in Prometheus's native -histograms, pay special attention to the last paragraph below.)_ - # Deprecation note -This repository used to contain the [protocol -buffer](https://developers.google.com/protocol-buffers) code that defined both -the data model and the exposition format of Prometheus metrics. - -Starting with v2.0.0, the [Prometheus -server](https://github.com/prometheus/prometheus) does not ingest the -protobuf-based exposition format anymore. Currently, all but one of the -[official instrumentation -libraries](https://prometheus.io/docs/instrumenting/clientlibs/) do not expose -the protobuf-based exposition format. The [Go instrumentation -library](https://github.com/prometheus/client_golang), however, has been built -around the protobuf-based data model. As a byproduct thereof, it is still able -to expose the protobuf-based exposition format. The Go instrumentation library -is the only remaining repository within the [Prometheus GitHub -org](https://github.com/prometheus) directly using the prometheus/client_model -repository. - -Therefore, formerly existing support for languages other than Go (namely C++, -Java, Python, Ruby) has been removed from this repository. If you are a 3rd -party user of those languages, you can go back to [commit -14fe0d1](https://github.com/prometheus/client_model/commit/14fe0d1b01d4d5fc031dd4bec1823bd3ebbe8016) -to keep using the old code, or you can consume -[`metrics.proto`](https://github.com/prometheus/client_model/blob/master/metrics.proto) -directly with your own protobuf tooling. Note, however, that changes of -`metrics.proto` after [commit -14fe0d1](https://github.com/prometheus/client_model/commit/14fe0d1b01d4d5fc031dd4bec1823bd3ebbe8016) -are solely informed by requirements of the Go instrumentation library and will -not take into account any requirements of other languages or stability concerns -for the protobuf-based exposition format. - -Check out the [OpenMetrics project](https://openmetrics.io/) for the future of -the data model and exposition format used by Prometheus and others. - -Note, though, that in an ironic twist of fate, the protobuf-based exposition -format got revived to suppert native histograms in Prometheus. Therefore, -starting with v2.40.0, the Prometheus server is again capable of ingesting the -protobuf-based exposition format. Eventually, native histogram support will be -added in some form to OpenMetrics, too. +This repository used to contain the [protocol buffer](https://developers.google.com/protocol-buffers) code that defined both the data model and [the exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) of Prometheus metrics. `client_model` was originally created because robust protobuf import tooling was non-existent at the time. Since then, tooling has improved (see [Buf](https://buf.build/)). + +The generated Go code is still used in the [public, stable API of `client_golang`](https://github.com/prometheus/client_golang/blob/74560058a7af7a695db8196c8e84a0754032c6af/prometheus/metric.go#L54) until v2. + +The source of truth for [the exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) has moved to [prometheus/prometheus](https://github.com/prometheus/prometheus/tree/main/prompb/io/prometheus/client) and is also available in the [Buf registry](https://buf.build/prometheus/prometheus/docs/main%3Aio.prometheus.client). + +## History + +Starting with v2.0.0, the [Prometheus server](https://github.com/prometheus/prometheus) stopped ingesting the protobuf-based exposition format. However, in v3.0.0 this restriction was lifted, and new features like native histograms were first introduced in the protobuf format. As of now, [the PrometheusProto exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) is an officially supported protocol that allows the community to experiment with new features. + +## Recommended Usage & Buf Tooling + +Formerly existing support for languages other than Go (namely C++, Java, Python, and Ruby) has been removed from this repository. + +For new consumers and SDKs in other languages (such as Rust, C++, Java, Python, and Ruby), **we do not recommend manually copying proto files or depending on `client_model`**. Instead, the modern preferred solution is to use [Buf tooling](https://buf.build/) to generate bindings directly on the SDK side with specific language options, maintaining a clean dependency chain. + +The centralized Prometheus protobuf definitions are available in the Buf registry, sourced directly from the main Prometheus repository: +[buf.build/prometheus/prometheus (io.prometheus.client)](https://buf.build/prometheus/prometheus/docs/main:io.prometheus.client)