Histogram spec: Rework and amend operators section

[beorn7]

• Divide operators section into sub-sections and reformat accordingly.

• Add that negative results of multiplication count as gauge histogram.

• Correct and complete the sub-section about trim operators.

[beorn7]

Now that we have nailed down what to do in prometheus/prometheus#17904 , we can finalize this. @krajorama & @linasm what do you think about this? I'm wondering how detailed we should describe the edge cases in the spec (or pseudo-spec, as I prefer to call it) here. One could argue that they are all implied with the current wording, but another line of argument would say we should spell out the edge cases here explicitly. (I currently tend towards the former, as it is more in line with the other parts of this document.)

[beorn7]

As per discussion over on prometheus/prometheus#17904, I'll add a detailed edge case description here (hopefully tomorrow).

[beorn7]

I think the current version should cover all edge cases.

@krajorama @linasm please verify.

[krajorama]

looks good over all, made two suggestions

[krajorama]

I don't think we check for negative value, so maybe

Suggested change

	their flavor is left unchanged by the operation, with the exception that a
	negative histogram is always considered to be a gauge histogram.
	their flavor is left unchanged by the operation, with the exception that
	multiplying by a negative value always results in a gauge histogram.

[krajorama]

I'd like to get my use case in here, because I think it's particularly useful.

I'm suggesting the following, but this buries "Their sum of observations is considered to be of limited use." a little bit, so needs some work:

Suggested change

	deliberately simple to make it easier to reason with. In general, the
	histograms resulting from trim operations are meant to be used for quantile
	estimation. Their sum of observations is considered to be of limited use.
	deliberately simple to make it easier to reason with.
	Their sum of observations is considered to be of limited use.
	In general, the histograms resulting from trim operations are
	meant to be used for quantile estimation or filtering. The trim
	operator can be a good replacement of `histogram_fraction` in
	cases when one boundary is infinite, such as calculating number
	of observations below a certain threshold for an alert.
	For example using `histogram_count(h </ x)` instead of
	`histogram_fraction(-Inf, x, h) * histogram_count(h)` is simpler
	and also yields `0` instead of `NaN` in case `h` has no observations,
	because the fraction would divide 0 by 0 in the later case.

Or we can flip it around and just mention this case here and elaborate in histogram_fraction ?