Expand event-model description to more clearly delineate instrument v…

[jsuereth]

…s. metric stream and some reasoning behind it.

Fixes ##1366

Changes

Improve the documentation around the "Event Model" and the relationship of "Instruments" to "metrics"

[punya]

Where does this leave things like quantiles?

[jsuereth]

Quantile is a form of grouping.

[jmacd]

I still believe this is a useful concept, but I am worried we've lost the connection to the API design by now. There's something about how Gauge and Histogram instruments are the same semantics with different default aggregations: both group individual measurements.

The point is that Gauge and Histogram inputs are semantically different than Sum inputs, because of individuality. This is meant to help the user choose between Counter and Histogram, for example. @reyang I mean to follow up on last week's API/SDK SIG meeting, in which we discussed some of this.

[jsuereth]

The goal of this is NOT to define what instruments the API uses, but show the flexibility of the model to adapt to differing instruments.

I'm thinking about doing the following:

• Focus on adapting instruments (OTel + non-otel) into the data model
• Focus on general concepts that may be used (quantiles, grouping, etc.)
• Direct to the API specification for specific instruments / instrument names.

This specification should be about WHAT metrics mean, not what instruments are available in the API.

[SergeyKanzhelev]

does total_latency aggregation ever makes sense? It may not be the best idea to include example like this

[jsuereth]

I do want an example that shows how a single instrument could turn into all of Sum, Histogram + Gauge.

While I can synthesize hair-brained scenarios where I think "total latency" might make sense (e.g. ridiculous statistics like How many days have users waited for our website in aggregate), You're right it's not a super useful example. Going to take a day to brainstorm and looking for other ideas on this example.

[jmacd]

If the example was a count (e.g., request_size), then max, sum, and histogram outputs all make sense.

However, one drawback with this example (sum alongside a histogram) is that a histogram data point already contains a sum, so exposing a separate metric with the sum is somehow not useful. The max function makes a better example, you could export the maximum over [1m], [10m], [1hr], and so on. (Related: open-telemetry/opentelemetry-proto#279)

The example export one histogram by metric_by_a_and_b{attributeA,attributeB}, one one histogram by metric_by_a_and_c{attributeA,attributeC}, maybe? I would emphasize that when doing this kind of output, separate metric names MUST be used to avoid metric data being recombined with itself.

[jsuereth]

I updated to use request size. I agree that histogram already has sum. I've also added some caveats to the image to denote it's meant to show the power, not a practical sceanrio.

PTAL at the new verbage. Also, I don't want to throw the baby out with the bathwater here. Look at the whole context of the doc as an introduction to the space of metrics. We need to both:

• Give people a mental model of why/how Instruments differ from Metric.
• Give people a grounding in what mapping from Event => Metric Stream looks like and the decisions that need to be made.

We do not need to specify the Otel API or its behavior here. We only need to specify what concepts are allowed in OTel metric streams. Lots of these nuances and details belong in the API docs.

I see these docs server two users primarily:

• API authors looking to generate OTLP by mapping their Events/Instruments into streams.
• Exporter authors looking to consume OTLP by mapping streams into their backend timeseries.

Instrumentation users who are generating metrics should be using the API specification.

[SergeyKanzhelev]

lgtm except the example on the picture. I suggest to fix it before merging

[jmacd]

If the example was a count (e.g., request_size), then max, sum, and histogram outputs all make sense.

However, one drawback with this example (sum alongside a histogram) is that a histogram data point already contains a sum, so exposing a separate metric with the sum is somehow not useful. The max function makes a better example, you could export the maximum over [1m], [10m], [1hr], and so on. (Related: open-telemetry/opentelemetry-proto#279)

The example export one histogram by metric_by_a_and_b{attributeA,attributeB}, one one histogram by metric_by_a_and_c{attributeA,attributeC}, maybe? I would emphasize that when doing this kind of output, separate metric names MUST be used to avoid metric data being recombined with itself.

[jmacd]

I still believe this is a useful concept, but I am worried we've lost the connection to the API design by now. There's something about how Gauge and Histogram instruments are the same semantics with different default aggregations: both group individual measurements.

The point is that Gauge and Histogram inputs are semantically different than Sum inputs, because of individuality. This is meant to help the user choose between Counter and Histogram, for example. @reyang I mean to follow up on last week's API/SDK SIG meeting, in which we discussed some of this.

[reyang]

LGTM.

[SergeyKanzhelev]

@jmacd do you want more changes in PR or merge as-is for now?