open-telemetry / opentelemetry-proto

OpenTelemetry protocol (OTLP) specification and Protobuf definitions
https://opentelemetry.io/docs/specs/otlp/
Apache License 2.0
575 stars 254 forks source link

Allow `sum` to present with negative measurements in Histogram #303

Open jsuereth opened 3 years ago

jsuereth commented 3 years ago

Follow on to #187 - We currently limit the sum field in Histogram to be 100% compatible with OpenMetrics/Prometheus histograms so we know we can do a conversion when it exists. However, we think there's value to having sum available when there are negative measurements as well.

Tentative proposal:

message Histogram {.
  .. 
  // When this is true, a histogram allows negative measurements.  This means
  // the sum is non monotonic, and may be 0 even if there are recorded events.
  bool has_negative_measurements = ?;
}
jmacd commented 3 years ago

~I do not feel enthusiastic about about has_negative_measurements.~

There could be finer-grain statements people might like to specify about their instruments, like a range between [0, 100] for example, so maybe we'll find other solutions.

If the definition for repeated double explicit_bounds = 7; were slightly different, we could avoid the indefinite-size buckets and address this problem at the same time. The exponential histogram option can just get this right, e.g., an exponential histogram with no negative buckets implies the desired property. If this is extremely important for explicit boundaries, it can be solved with a new even-more-explicit boundaries array (one extra element to erase this ambiguity).

jmacd commented 3 years ago

Referring to the contents of https://github.com/open-telemetry/oteps/pull/156, there are three semantics for the Sum field of a Histogram, corresponding with a Histogram of values to synchronous Counter, UpDownCounter, and Gauge API events, where the sum is:

This suggests an enum value with three states, indicating which of the primitive instruments the measurements in the histogram semantically correspond with.

jmacd commented 3 years ago

Taken together with #308, the pair of proposals to me suggest a new field that contains extra semantic bits, two states for Count being monotonic or not, and three states for Sum being monotonic, non-monotonic, or non-meaningful.