RW 2.0-rc.5: allow exemplar-only time series

[thc1006]

This changes the 2.0 specification so that a TimeSeries carrying only exemplars is described rather than forbidden, and keeps the expectation that those exemplars travel with the series they belong to.

Why the current wording does not cover what a sender produces

Prometheus stores exemplars per series, not per sample. populateV2TimeSeries in storage/remote/queue_manager.go writes one output TimeSeries per queue item, and for an exemplar item it appends only an exemplar, having already reset that entry's samples and histograms. So an exemplar can leave the sender in a TimeSeries of its own.

The specification currently says:

At least one element in samples or in histograms MUST be provided. A TimeSeries MUST NOT include both samples and histograms.

That shape therefore has no wording behind it, and a receiver has nothing to rely on when it arrives.

What this changes

Three sentences, one file:

• the "at least one element" rule accepts exemplars as well, and says what a TimeSeries carrying only exemplars means;
• the #### Exemplars section says the same thing from the exemplar's side;
• it adds the SHOULD that exemplars travel in the same request as the samples or histograms of their series, which is the second half of the decision and the part that keeps this from becoming a licence to detach them freely.

That last one matters because a sender does usually keep them together. QueueManager.Append and AppendExemplars are called separately by the WAL watcher, so the batch can be cut between a sample and its exemplar, but that is the exception rather than the intent. SHOULD says exactly that.

No field, field number or wire layout changes, and senders are not asked to do anything differently.

What this leaves alone

The proto comments in prompb/io/prometheus/write/v2/types.proto still say exemplars are "attached to this series' samples", and the receiver tests in prometheus/compliance only cover exemplars sent alongside a sample. Both would want the same treatment, but they are separate changes.

On versioning

Retitled with the version, the way rc.4 was done in #2762, so the title is the record of what went into the release. #3080 still carries the single bump and #3081 is the other change in this one.

Related to prometheus/prometheus#17857 and prometheus/prometheus#16944.

[bwplotka]

This looks what wanted as per https://docs.google.com/document/d/1ZcyKVF87Xf6FhaGkb33LgVLb27FH5NIlRXWEGO2Cc4Q/edit?tab=t.0#bookmark=id.nllt8bbnl0i decision. However we need strict versioning.

I initially planned to pack this and async change under rc.5 for an easy reference -- we don't use git tags so it's a bit challenging to pack two separate changes under same version (:

[thc1006]

Retitled with the version, the way rc.4 was done in #2762, so the title carries the record that git tags would otherwise hold. #3080 keeps the single bump and #3081 is the other change in rc.5, so nothing has to be packed together beyond the two titles saying the same version.

Also added the second half of the decision, which I had left out: exemplars SHOULD be sent in the same request as the samples or histograms of their series, including when they travel in a TimeSeries of their own. Without it the wording read as a licence to detach them freely, which is not what the sender does today.

Out of draft now.

[bwplotka]

I changed base to #3085 so we can squash it all as a rc.5, hope that's ok

[bwplotka]

Ups I think you need to manually rebase, sorry @thc1006 - do you mind doing this?

[krajorama]

This would be updated once the proto is updated then?

[bwplotka]

Let's update it at one go and prep a PR.

[thc1006]

Both done: the copy here in this PR, the original in prometheus/prometheus#19530.

[krajorama]

LGTM, except the question about the copied protobuf

[thc1006]

Rebased onto rw2-spec-rc5, so this is one commit against that branch again. No trouble at all, and moving the base was the right call for keeping rc.5 in one place.

@krajorama good catch on the copied protobuf. The comment you pointed at turned out to be one of three saying the same thing: that one says a TimeSeries specifies samples or histograms, the exemplars field says they belong to the series' samples, and the Exemplar message says it too. All three are in this PR now.

The originals live in prompb/io/prometheus/write/v2/types.proto, so those go in prometheus/prometheus#19530. That one does not depend on this PR: populateV2TimeSeries clears Samples and Histograms and appends only an exemplar when the queue item is a tExemplar, so the comment already disagrees with the sender sitting next to it.

One thing I would rather ask than guess. In prometheus/prometheus#17857 back in January you proposed two halves, "Add SHOULD for per sample, but allow per series by spec". This PR has the second one. The SHOULD I added after your first comment here is about sending exemplars in the same request, not about preferring per sample association. Should the per sample SHOULD go in as well, or does the August decision replace it? Your 26 August comment on that issue reads as moving away from the per sample model for now, which is why I left it out.

Last thing, unrelated to the diff: prometheus/prometheus#18014 has been open since February taking the other route, dropping exemplars that arrive without a matching sample. @AftAb-25 wrote it against the spec as it read then. If this lands, they deserve to hear that the direction moved. The bot has already marked it stale.