Documentation
¶
Overview ¶
Package testutil provides helpers to test code using the prometheus package of client_golang.
While writing unit tests to verify correct instrumentation of your code, it's a common mistake to mostly test the instrumentation library instead of your own code. Rather than verifying that a prometheus.Counter's value has changed as expected or that it shows up in the exposition after registration, it is in general more robust and more faithful to the concept of unit tests to use mock implementations of the prometheus.Counter and prometheus.Registerer interfaces that simply assert that the Add or Register methods have been called with the expected arguments. However, this might be overkill in simple scenarios. The ToFloat64 function is provided for simple inspection of a single-value metric, but it has to be used with caution.
End-to-end tests to verify all or larger parts of the metrics exposition can be implemented with the CollectAndCompare or GatherAndCompare functions. The most appropriate use is not so much testing instrumentation of your code, but testing custom prometheus.Collector implementations and in particular whole exporters, i.e. programs that retrieve telemetry data from a 3rd party source and convert it into Prometheus metrics.
In a similar pattern, CollectAndLint and GatherAndLint can be used to detect metrics that have issues with their name, type, or metadata without being necessarily invalid, e.g. a counter with a name missing the “_total” suffix.
Index ¶
- func CollectAndCompare(c prometheus.Collector, expected io.Reader, metricNames ...string) error
- func CollectAndCount(c prometheus.Collector, metricNames ...string) int
- func CollectAndLint(c prometheus.Collector, metricNames ...string) ([]promlint.Problem, error)
- func GatherAndCompare(g prometheus.Gatherer, expected io.Reader, metricNames ...string) error
- func GatherAndCount(g prometheus.Gatherer, metricNames ...string) (int, error)
- func GatherAndLint(g prometheus.Gatherer, metricNames ...string) ([]promlint.Problem, error)
- func ScrapeAndCompare(url string, expected io.Reader, metricNames ...string) error
- func ToFloat64(c prometheus.Collector) float64
- func TransactionalGatherAndCompare(g prometheus.TransactionalGatherer, expected io.Reader, metricNames ...string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CollectAndCompare ¶
CollectAndCompare registers the provided Collector with a newly created pedantic Registry. It then calls GatherAndCompare with that Registry and with the provided metricNames.
func CollectAndCount ¶
func CollectAndCount(c prometheus.Collector, metricNames ...string) int
CollectAndCount registers the provided Collector with a newly created pedantic Registry. It then calls GatherAndCount with that Registry and with the provided metricNames. In the unlikely case that the registration or the gathering fails, this function panics. (This is inconsistent with the other CollectAnd… functions in this package and has historical reasons. Changing the function signature would be a breaking change and will therefore only happen with the next major version bump.)
func CollectAndLint ¶
CollectAndLint registers the provided Collector with a newly created pedantic Registry. It then calls GatherAndLint with that Registry and with the provided metricNames.
func GatherAndCompare ¶
GatherAndCompare gathers all metrics from the provided Gatherer and compares it to an expected output read from the provided Reader in the Prometheus text exposition format. If any metricNames are provided, only metrics with those names are compared.
func GatherAndCount ¶
func GatherAndCount(g prometheus.Gatherer, metricNames ...string) (int, error)
GatherAndCount gathers all metrics from the provided Gatherer and counts them. It returns the number of metric children in all gathered metric families together. If any metricNames are provided, only metrics with those names are counted.
func GatherAndLint ¶
GatherAndLint gathers all metrics from the provided Gatherer and checks them with the linter in the promlint package. If any metricNames are provided, only metrics with those names are checked.
func ScrapeAndCompare ¶
ScrapeAndCompare calls a remote exporter's endpoint which is expected to return some metrics in plain text format. Then it compares it with the results that the `expected` would return. If the `metricNames` is not empty it would filter the comparison only to the given metric names.
func ToFloat64 ¶
func ToFloat64(c prometheus.Collector) float64
ToFloat64 collects all Metrics from the provided Collector. It expects that this results in exactly one Metric being collected, which must be a Gauge, Counter, or Untyped. In all other cases, ToFloat64 panics. ToFloat64 returns the value of the collected Metric.
The Collector provided is typically a simple instance of Gauge or Counter, or – less commonly – a GaugeVec or CounterVec with exactly one element. But any Collector fulfilling the prerequisites described above will do.
Use this function with caution. It is computationally very expensive and thus not suited at all to read values from Metrics in regular code. This is really only for testing purposes, and even for testing, other approaches are often more appropriate (see this package's documentation).
A clear anti-pattern would be to use a metric type from the prometheus package to track values that are also needed for something else than the exposition of Prometheus metrics. For example, you would like to track the number of items in a queue because your code should reject queuing further items if a certain limit is reached. It is tempting to track the number of items in a prometheus.Gauge, as it is then easily available as a metric for exposition, too. However, then you would need to call ToFloat64 in your regular code, potentially quite often. The recommended way is to track the number of items conventionally (in the way you would have done it without considering Prometheus metrics) and then expose the number with a prometheus.GaugeFunc.
func TransactionalGatherAndCompare ¶
func TransactionalGatherAndCompare(g prometheus.TransactionalGatherer, expected io.Reader, metricNames ...string) error
TransactionalGatherAndCompare gathers all metrics from the provided Gatherer and compares it to an expected output read from the provided Reader in the Prometheus text exposition format. If any metricNames are provided, only metrics with those names are compared.
Types ¶
This section is empty.
Source Files
Directories