Remove mentions of the Protobuf format #1083
Conversation
| that implement this format for you. If your preferred language doesn't have a client | ||
| library you can [create your own](/docs/instrumenting/writing_clientlibs/). | ||
|
|
||
| NOTE: Some earlier versions of Prometheus supported an exposition format based on |
There was a problem hiding this comment.
The NOTE: here should probably still be NOTE: **NOTE:**, as the initial NOTE: is translated into a formatting directive that creates a call-out box and is otherwise not displayed, see https://prometheus.io/docs/instrumenting/exposition_formats/
Or was your intention to get rid of the displayed "NOTE" text within that box?
There was a problem hiding this comment.
Yes, I'm aware of the NOTE syntax. In my view the styling makes it unnecessary to include NOTE but I'm not dogmatic about that. Your call.
There was a problem hiding this comment.
Hmm, I just tried removing it on the live site and it looks a bit odd to me in context without the "NOTE" text:
I'd be for keeping it. If we do decide to remove it, we should make that a conscious decision and remove the extra callout words throughout the site, not just in one instance.
There was a problem hiding this comment.
Okay, I'll make that change. In a future PR I'll adjust the template of admonition blocks so that the admonition type is included automatically.
|
|
||
| ### Text format details | ||
|
|
||
| The protocol is line-oriented. A line-feed character (`\n`) separates lines. | ||
| The last line must end with a line-feed character. Empty lines are ignored. | ||
| Prometheus text-based format is line oriented. Lines are separated by a line |
There was a problem hiding this comment.
Should "Prometheus" be "Prometheus's" (or "Prometheus'") here?
|
|
||
| Within a line, tokens can be separated by any number of blanks and/or tabs (and | ||
| have to be separated by at least one if they would otherwise merge with the | ||
| previous token). Leading and trailing whitespace is ignored. | ||
| must separated by at least one if they would otherwise merge with the previous |
| metric_name [ | ||
| "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}" | ||
| ] value [ timestamp ] | ||
| `metric_name` and `label_name` have the usual Prometheus expression language restrictions: |
There was a problem hiding this comment.
The following bullet points that are introduced here don't actually further describe this sentence, they are completely separate points. So either everything should be a bullet point (with a different intro statement) or nothing should be...
There was a problem hiding this comment.
Ah, okay. I'm just going to restructure this list.
| `metric_name` and `label_name` have the usual Prometheus expression language restrictions. `label_value` can be any sequence of UTF-8 characters, but the backslash, the double-quote, and the line-feed characters have to be escaped as `\\`, `\"`, and `\n`, respectively. | ||
| `value` is a float, and timestamp an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by the [Go strconv package](http://golang.org/pkg/strconv/) (see functions `ParseInt` and `ParseFloat`). In particular, `Nan`, `+Inf`, and `-Inf` are valid values. | ||
| * `label_value` can be any sequence of UTF-8 characters, but the backslash, the double-quote, and the line-feed characters have to be escaped as `\\`, `\"`, and `\n`, respectively. | ||
| * `value` is a float |
There was a problem hiding this comment.
Period missing on this bullet point (the others have periods).
| `value` is a float, and timestamp an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by the [Go strconv package](http://golang.org/pkg/strconv/) (see functions `ParseInt` and `ParseFloat`). In particular, `Nan`, `+Inf`, and `-Inf` are valid values. | ||
| * `label_value` can be any sequence of UTF-8 characters, but the backslash, the double-quote, and the line-feed characters have to be escaped as `\\`, `\"`, and `\n`, respectively. | ||
| * `value` is a float | ||
| * the `timestamp` is an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by the [Go strconv package](http://golang.org/pkg/strconv/) (see functions [`ParseInt`](https://golang.org/pkg/strconv/#ParseInt) and [`ParseFloat`](https://golang.org/pkg/strconv/#ParseFloat)). In addition to standard integers, `Nan`, `+Inf`, and `-Inf` are valid values representing not a number, positive infinity, and negative infinity, respectively. |
There was a problem hiding this comment.
The last sentence and the floaty bit of the previous one are actually still about the sample value, which would be the previous bullet point.
| the ingestion behavior is undefined. | ||
|
|
||
| #### Histograms and summaries |
There was a problem hiding this comment.
When introducing these new sub-headers, we'll then have to introduce them for all sub-sections of the text format, including the example section below (the example is no longer about histograms and summaries in particular, but about the text format in general).
There was a problem hiding this comment.
Yep, you're right. Missed this one.
|
👍 besides comments, thanks! |
|
@juliusv Okay, I think I've addressed all of the issues you've pointed out. One question, though: in the "Optional Text Representation" section you'll see that Protobuf is still mentioned as an optional format. Is that still the case? Or should mention be removed entirely? |
| * `metric_name` and `label_name` carry the usual Prometheus expression language restrictions. | ||
| * `label_value` can be any sequence of UTF-8 characters, but the backslash (`\`, double-quote (`"`}, and line feed (`\n`) characters have to be escaped as `\\`, `\"`, and `\n`, respectively. | ||
| * `value` is a float. | ||
| * the `timestamp` is an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by the [Go strconv package](http://golang.org/pkg/strconv/) (see functions [`ParseInt`](https://golang.org/pkg/strconv/#ParseInt) and [`ParseFloat`](https://golang.org/pkg/strconv/#ParseFloat)). In addition to standard integers, `Nan`, `+Inf`, and `-Inf` are valid values representing not a number, positive infinity, and negative infinity, respectively. |
There was a problem hiding this comment.
This comment still applies: d6e75b7#r198996763
The last sentence is about sample values and the ParseFloat bit of the previous sentence too (since sample values are floats, timestamps are ints).
I am not aware of anyone ever having implemented any of those optional text representations. I think we should just nuke that entire section, as it has little bearing on reality. |
|
@juliusv Makes sense. Less material --> less to maintain 👍 |
Signed-off-by: lucperkins <lucperkins@gmail.com>
|
@lucperkins #1083 (comment) still needs to be fixed |
In response to issue #927. Although there are still some stray mentions of the Protobuf format in the documentation, this PR should remove the mentions that are the most likely to cause confusion and consternation. In the future we should conduct a more thorough sweep.