Write an example showing how to create a histogram from a value recorder

[atoulme]

Write a complete representation of what it takes to create a histogram that aggregates values from a value recorder.

The sample should have code that:

• Creates a recorder
• Creates a basic pull associated with the recorder
• Creates a histogram representation of the values

[seanhoughton]

Is there an example available anywhere of how to do this? I can wait for the docs for a complete explanation, but for now just somewhere to start with a working example would be helpful.

It seems like you create a histogram with h := histogram.New(...) and then update the values using h.Update(...) but what do you do next? There doesn't seem to be any way to bridge the histogram you've created with an actual instrument that will cause metrics to be sent through an exporter. I have a sneaking suspicion that I'm using a low-level library that isn't intended to be used by end-users. I watched the metrics deep dive presentation by Lightstep on youtube which didn't help.

[seanhoughton]

I would be happy to write this example if someone could provide some hint about how to do this? I've been searching through the code trying to understand how histogram/aggregator/accumulation all relate and how to actually create a histogram, measure a value, and have it reflected as a set of _bucket and _count metrics. Maybe this isn't implemented or possible yet, but it would be really helpful if someone could at least update this thread with a quick sample and starting point.

[seanhoughton]

For anyone else trying to solve the mystery of how to get a histogram it's actually very easy - it's just not documented anywhere (that I can find). I found it as a passing mention in another issue (#689). Now it's making more sense, it's just difficult to decipher due to differences in API choices made by the opentelemetry api and the prometheus api.

OpenTelemetry Metrics is explicitly moving away from instruments named for the action they perform, and moving toward instruments named for how they are used. There is no Histogram instrument, which is part of the reason buckets can't be configured at the instrument level. In the forthcoming 0.4 metrics specification, there will be two instruments that will translate into Prometheus histograms by default, those are going to be named ValueRecorder and ValueObserver

So you just create a value recorder and it will be automatically translated into a histogram with automatic bucket boundaries.

examplehisto, err = meter.NewFloat64ValueRecorder(
		"example",
		metric.WithDescription(string(unit.Dimensionless)),
		metric.WithDescription("Some values that will become a histogram in the prometheus exporter"),
	)

Now to add values you use

global.Meter("name").RecordBatch(ctx, labels, examplehisto.Measurement(myvalue))

[jpkrohling]

Looks like there's an example now, under example/prometheus. I'm still unsure how to set the boundaries for specific metrics, though.

[MrAlias]

Stale, closing. There is an example of how to manage histograms added in #3177 FWIW