Add Histogram::count() and ::sum()

[drbrain]

These methods are useful when testing that a Histogram has correctly observed values in a test. ::count() to determine if the correct number of samples have been observed and ::sum() to determine if the correct sample values have been observed.

I don't feel there's a need to get the values in each bucket because this crate has its own tests that a user could rely on.

These methods match the Histogram::get_sample_count() Histogram::get_sample_sum() from the prometheus crate.

[drbrain]

Can you expand on the issue you were trying to test?

I have instrumented a section of code with a histogram metric records latencies for various disk operations. Creating a directory, opening a file, writing chunks into the file.

I want to ensure that for N operations that I intended to instrument I have recorded N operations in the histogram through ::count()

For this same section I record bytes-written-to-disk in a separate histogram metric. To ensure my instrumentation is correct I want to retrieve the total ::sum() of bytes recorded in the metric and compare that to the number of bytes I provided for writing.

In case it was directly related to this crate, why not add a unit test here which could then access the private methods.

In my opinion, these methods are equivalent to Counter::get() or Gauge::get() and must be public to ensure I am recording metrics correctly when using your crate. They provide feature-parity with the unofficial prometheus crate.

(I think you were asking if I need this for use in code that uses this crate, or if this is a new, internal test only for this crate. I would like these methods added for code that uses this crate. Apologies if I missed your intent.)

For a section of code that handles transactions I have a counter for total requests and a gauge for active-requests. I can use the existing ::get() methods in a test to ensure the total-requests counter is incremented only once per transaction, and that the active-requests gauge is incremented and decremented correctly.

Adding these two histogram methods allows me to be sure my use of a histogram metric is correct and I can trust the instrumentation I’ve added to the same level as counters and gauges.

A workaround without this PR would require encoding then parsing the histogram metric to retrieve the value to compare against the expected values. This seems like a lot of burden for users of histograms compared to counters and gauges.

[mxinden]

I am still hesitant to expose these internals for the sake of testing downstream logic. Increasing the API surface of this library makes it harder to maintain in the future. Given that I am resource constrained, i.e. constrained in the number of hours I want to spend on this library, I prioritize maintainability here.

I want to ensure that for N operations that I intended to instrument I have recorded N operations in the histogram through ::count()

Could you wrap your Histogram and record (when testing) each method call, assert!ing the values from the wrapper at the end of the test?

In my opinion, these methods are equivalent to Counter::get() or Gauge::get()

I acknowledge this. In a perfect consistent world either Counter and Gauge would not expose get or Histogram would expose ``countandsum`.

[mxinden]

Closing here with the concerns above. Feel free to open an issue in case you want to continue the discussion.