prometheus
Improve documentation for Enum and Info classes
In Instrumenting section of documentation (https://github.com/prometheus/client_python#instrumenting) there is written:
Four types of metric are offered: Counter, Gauge, Summary and Histogram.
Classes for exposing these metrics are then described and in addition there are mentioned also Info and Enum classes without explanation how these classes should be used and what type of metrics they expose. These should be documented in more detail.
Would you like to send a PR fixing that line?
The docs on the metrics themselves are in line with the others.
I'd like to but as I'm new to Prometheus and this Python client, I'm not sure what is the purpose and intended use of the Info and Enum classes.
For a newcomer these classes are hard to use:
- I tried to use the Info class for exposing information about the current state of a service.
- Without proper documentation I had to try to implement it (or inspect the source code) to find out it actually exposes a gauge metric where the keys/values are the label names/label values.
- Then I had to investigate how to display the labels properly: https://community.grafana.com/t/extract-labels-values-from-prometheus-metrics/2087
There is not any documentation about Info/Enum like usage in the official Prometheus docs (nor in this client docs or in Grafana). E.g. one of the Info values in my case changes every few seconds so the label in the gauge changes with each scrape. This usage is explicitly discouraged in Prometheus docs because it results in labels with high cardinality: https://prometheus.io/docs/practices/naming/#labels
This is reference documentation about how to use the API, not a guide on how to use Prometheus/OpenMetrics metrics and common practices.
If you've usage questions, then the user mailing list is a better place.
I believe that more detail description of Info and Enum would help many users. Or a link to an external documentation as it is done for counter, gauge, histogram and summary which are clearly described in Prometheus docs.
We don't link elsewhere on the others, and general docs don't exist yet - however they're both existing practices within Prometheus.