rust-prometheus

rust-prometheus copied to clipboard

I have just started using this crate and am new to Prometheus. It took me a while to figure out what exporters actually are. I believe this crate doesn't have a built-in exporter. If that is the case, won't it be better if we document that in the README?

For someone like me who's new to it, the question flow was:

1. How do I create a counter metric?
2. How do I get my metric to show up on Prometheus?

The first part is documented with example code showing how to create a counter metric, but the second question wasn't answered from the README.

I had to look at implementations in other languages (e.g. Python/Java) which have a section about Exporter in their README, to understand they allow support for automatically exposing a /metrics endpoint, which makes me think:

1. I have to expose a /metrics endpoint myself
2. From the help of docs, I understand that I'll have to call gather, encode and return the String from the endpoint

So I think it would be better to have an Exporter section in the README.

I noticed this example about using hyper but I don't see it setting up an endpoint named /metrics.

Wouldn't it be better to integrate this into the crate so we can use a command to create a proper /metrics endpoint? There is also this crate that does that.

I do agree this should be better documented, somehow.

In general the Rust ecosystem has several frameworks for building web-services, and this library is not trying to directly integrate with each one of them to avoid getting tangled in a dependency mess. So yes, a reasonable way is to plug gather+encode into your web logic for the /metrics route handler.

That seems fair. Thanks for the clarification.

So I believe we can simply tell this flow of using gather and encode with any web framework for rust since exporters are somewhat a fundamental part of Prometheus pull-based flow, and people reading up docs of Python and Java clients would expect some documentation about exporters here as well.

Are you guys open to fixing this? I can work on creating a small PR to mention a few things about using exporters as mentioned in this issue.

Are you guys open to fixing this? I can work on creating a small PR to mention a few things about using exporters as mentioned in this issue.

Yes. We very much appreciate any contributions, especially ones that add documentation.

Just to make sure we use the same vocabulary:

A Prometheus exporter is a small binary running along side the monitoring target (e.g. a database) exposing metrics about that target.

A Prometheus endpoint is an (HTTP) endpoint on a monitoring target itself that exports metrics about the target.

You can use the prometheus Rust crate for both use cases with the latter (direct monitoring via an endpoint) being the preferred one.

@mxinden thanks for the distinction b/w exporter and endpoint!