-
Notifications
You must be signed in to change notification settings - Fork 171
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Clarify compatibility and content negotiation #273
base: main
Are you sure you want to change the base?
Changes from 1 commit
878c675
220e969
52e43d9
b1542be
8ee74eb
80a1363
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -34,6 +34,7 @@ normative: | |||||||||||||
RFC2119: | ||||||||||||||
RFC5234: | ||||||||||||||
RFC8174: | ||||||||||||||
RFC9110: | ||||||||||||||
|
||||||||||||||
informative: | ||||||||||||||
normalization: | ||||||||||||||
|
@@ -307,11 +308,35 @@ The text format compresses well, and protobuf is already binary and efficiently | |||||||||||||
|
||||||||||||||
Partial or invalid expositions MUST be considered erroneous in their entirety. | ||||||||||||||
|
||||||||||||||
## Versioning and compatibility | ||||||||||||||
|
||||||||||||||
### ABNF specification | ||||||||||||||
|
||||||||||||||
Versioning follows a semantic versioning model on the specification level. Breaking semantic changes (for example removal from ABNF) MUST result in major version bump, however additions MUST be in a minor version bump. Multiple changes may be bundled in the same version update and the version bump will be the biggest version bump in those changes. | ||||||||||||||
|
||||||||||||||
### Ingestor | ||||||||||||||
|
||||||||||||||
Ingestors MUST implement at least version 1.0.0 of the standard. | ||||||||||||||
Ingestors MUST implement protocol negotiation to be able to support higher than 1.0.0 version. | ||||||||||||||
If exposer doesn't support content negotiation, version 1.0.0 SHOULD be assumed. | ||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We can change the "MUST 1.0.0" to "SHOULD 1.0.0" in 2.x if we need to. It's a bit of a cop-out, but long term, say Prometheus 4.0, it might be defensible. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe, but I'm not sure we'll ever be able to get rid of 1.0.0 |
||||||||||||||
|
||||||||||||||
An ingestor that supports version "m.y" of the standard MUST support versions "m.x" where "x" and "y" are natural numbers, such that "x < y". | ||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think supporting e.g. 1.0 and 1.5 would be OK. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'll remove this line There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we should state this explicitly, because that's not what backwards compatibility means. I would expect that a parser can read anything that lower semantic version (on the same major version). |
||||||||||||||
|
||||||||||||||
Ingestors MAY refuse to ingest the exposed metrics if content negotiation yields an empty list of versions. | ||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That seems self-evident? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. But they SHOULD negotiate the latest version as well? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is pretty academic, as negotiation currently takes place in the exposer, but the alternative would be to try and parse the content as 1.0.0. I'll remove it as not very useful for now. |
||||||||||||||
|
||||||||||||||
### Exposer | ||||||||||||||
|
||||||||||||||
Exposers MUST implement at least version 1.0.0 of the standard. | ||||||||||||||
Exposers MUST implement protocol negotiation to be able to support higher than 1.0.0 version. | ||||||||||||||
Exposers SHOULD negotiate the highest common version with the exposer. | ||||||||||||||
krajorama marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||
|
||||||||||||||
## Protocol Negotiation | ||||||||||||||
|
||||||||||||||
All ingestor implementations MUST be able to ingest data secured with TLS 1.2 or later. All exposers SHOULD be able to emit data secured with TLS 1.2 or later. ingestor implementations SHOULD be able to ingest data from HTTP without TLS. All implementations SHOULD use TLS to transmit data. | ||||||||||||||
|
||||||||||||||
Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested. | ||||||||||||||
Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP the standard HTTP content type negotiation MUST be used. The ingestor MUST send the "Accept" header according to RFC 9110 and indicate the versions it supports, for example | ||||||||||||||
|
||||||||||||||
application/openmetrics-text;version=1.0.0;q=0.7,application/openmetrics-text;version=1.1.0;q=0.8 | ||||||||||||||
|
||||||||||||||
Push-based negotiation is inherently more complex, as the exposer typically initiates the connection. Producers MUST use the oldest version of the standard (i.e. 1.0.0) unless requested otherwise by the ingestor. | ||||||||||||||
|
||||||||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Semantic versioning needs a reference in line 38 and following, now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added to informative references