When would someone use a Manual Reader?

[iamkirkbater]

I'm looking to add some telemetry to some internal cobra-cli tooling. First iteration is to start to track how often certain commands are called so that we can prioritize what commands to prioritize our improvements on.

I've successfully figured out how to create a small proof of concept off of the example files within the repo, but I'm intrigued by the NewManualReader() functionality and wondering when that would be used. At first glance, a manual reader sounds like it's exactly what I would need to instrument a command line application, something that collects the telemetry that's provided and just attempts to push it out all at once at the end of the invocation of the command.

However, compared to the Periodic Reader you can't pass an exporter to the Manual Reader, so something like provider.Shutdown() at the end of the command invocation doesn't seem to do anything, because there's no exporter to write to.

I have seen from my testing, though, that the Periodic Reader will push the metrics at the end of the command line invocation, provided that it has been shut down properly. Are there any exceptions to this? Would that be appropriate for all command-line invocation use-cases?

So, I guess my actual question is - what's the purpose of the Manual Reader and when would you use it, or - better yet - how would you use it?

[pellared]

I have seen from my testing, though, that the Periodic Reader will push the metrics at the end of the command line invocation, provided that it has been shut down properly. Are there any exceptions to this? Would that be appropriate for all command-line invocation use-cases?

I think you should be fine using a Periodic Reader.

So, I guess my actual question is - what's the purpose of the Manual Reader and when would you use it, or - better yet - how would you use it?

1. When writing your own custom exporter. E.g. "Pull based" exporters like Prometheus are implementing the metric.Reader interface and also use it under the hood. See https://github.com/open-telemetry/opentelemetry-go/blob/main/exporters/prometheus/exporter.go.
2. You could also use a manual reader for any custom exporting logic (custom reader) e.g. collect and export only during application shutdown (but I am not sure if it is a good idea).
3. When testing metrics instrumentation. See https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/instrumentation/net/http/otelhttp/test/handler_test.go

Maybe there are other use cases but these are the ones that initially come to my mind.

EDIT: Do you think it would be worth to document it here?

[iamkirkbater]

I think it would be a great idea to document there. I'm also planning on writing a small blog series on instrumentation from what I'm learning working through this proof of concept, would you mind potentially being a proofreader for that to ensure technical accuracy in my comments when I have that ready?

As I tend to do often, shortly after I posted this everything ended up clicking into place with how this is actually used, and the examples and test files ended up making a bit more sense.

A 4th use case to the ones that you added there I've ended up accomplishing in my proof of concept is doing something like having multiple exporters run off of the same set of metrics, something that I'm not sure is possible with a periodic reader alone. Where I see this use case coming into play would be specifically for testing, similar to what you noted above.

Once I gather my notes and thoughts a bit, I'll throw up a PR to try to improve the documentation on the Manual Reader itself, and maybe throw another example.go together for it.

[pellared]

would you mind potentially being a proofreader for that to ensure technical accuracy in my comments when I have that ready?

Sure 👍 You can also ask for review in Discussions.

A 4th use case to the ones that you added there I've ended up accomplishing in my proof of concept is doing something like having multiple exporters run off of the same set of metrics, something that I'm not sure is possible with a periodic reader alone.

It IMO falls into 3rd use case 😉

[iamkirkbater]

That's fair :)

I also think this is the first time I've used Github Discussions, so I'll be sure to also ask there for a review. Thanks! Appreciate the fast responses :D

[iamkirkbater]

I've compiled my first draft of the post here: https://github.com/iamkirkbater/personal-blog/pull/5/files#diff-e7c90e504af13ee7e3186843f1e51a66cbd3ab59643825ab4bf3bfeb52374157. If you get a chance and have any feedback, I'd be more than happy to hear it. Thanks!