Documentation
¶
Overview ¶
Package testappender exposes utilities to test code which writes to Prometheus storage.Appenders.
Example ¶
package main
import (
"fmt"
"github.com/grafana/alloy/internal/util/testappender"
"github.com/prometheus/prometheus/model/labels"
"github.com/prometheus/prometheus/model/metadata"
"github.com/prometheus/prometheus/model/textparse"
)
func main() {
var app testappender.Appender
app.Append(0, labels.FromStrings("__name__", "example_metric", "foo", "bar"), 60, 1234)
app.UpdateMetadata(0, labels.FromStrings("__name__", "example_metric"), metadata.Metadata{
Type: textparse.MetricTypeGauge,
})
expect := `
# TYPE example_metric gauge
example_metric{foo="bar"} 1234 60
`
_ = app.Commit()
families, _ := app.MetricFamilies()
err := testappender.Compare(families, expect)
if err != nil {
fmt.Println("Metrics do not match:", err)
} else {
fmt.Println("Metrics match!")
}
}
Output: Metrics match!
Index ¶
- func Compare(families []*dto.MetricFamily, expect string) error
- type Appender
- func (app *Appender) Append(ref storage.SeriesRef, l labels.Labels, t int64, v float64) (storage.SeriesRef, error)
- func (app *Appender) AppendExemplar(ref storage.SeriesRef, l labels.Labels, e exemplar.Exemplar) (storage.SeriesRef, error)
- func (app *Appender) AppendHistogram(ref storage.SeriesRef, l labels.Labels, t int64, h *histogram.Histogram, ...) (storage.SeriesRef, error)
- func (app *Appender) Commit() error
- func (app *Appender) MetricFamilies() ([]*dto.MetricFamily, error)
- func (app *Appender) Rollback() error
- func (app *Appender) UpdateMetadata(ref storage.SeriesRef, l labels.Labels, m metadata.Metadata) (storage.SeriesRef, error)
- type Comparer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Compare ¶
func Compare(families []*dto.MetricFamily, expect string) error
Compare compares the text representation of families to an expected input string. Families is converted into the Prometheus text exposition format.
To make testing less error-prone, expect is cleaned by removing leading whitespace, trailing whitespace, and empty lines. The cleaned version of expect is then compared directly against the text representation of families.
Types ¶
type Appender ¶
type Appender struct {
// HideTimestamps, when true, will omit timestamps from results.
HideTimestamps bool
// contains filtered or unexported fields
}
Appender implements storage.Appender. It keeps track of samples, metadata, and exemplars written to it.
When Commit is called, the written data will be converted into a slice of *dto.MetricFamily, when can then be used for asserting against expectations in tests.
The zero value of Appender is ready for use. Appender is only intended for test code, and is not optimized for production.
Appender is not safe for concurrent use.
func (*Appender) Append ¶
func (app *Appender) Append(ref storage.SeriesRef, l labels.Labels, t int64, v float64) (storage.SeriesRef, error)
Append adds or updates a sample for a given metric, identified by labels. l must not be empty. If Append is called twice for the same metric, older samples are discarded.
Upon calling Commit, a MetricFamily is created for each unique `__name__` label. If UpdateMetadata is not called for the named series, the series will be treated as untyped. The timestamp of the metric will be reported with the value denoted by t.
The ref field is ignored, and Append always returns 0 for the resulting storage.SeriesRef.
func (*Appender) AppendExemplar ¶
func (app *Appender) AppendExemplar(ref storage.SeriesRef, l labels.Labels, e exemplar.Exemplar) (storage.SeriesRef, error)
AppendExemplar adds an exemplar for a given metric, identified by labels. l must not be empty.
Upon calling Commit, exemplars are injected into the resulting Metrics for any Counter or Histogram.
The ref field is ignored, and AppendExemplar always returns 0 for the resulting storage.SeriesRef.
func (*Appender) AppendHistogram ¶
func (app *Appender) AppendHistogram(ref storage.SeriesRef, l labels.Labels, t int64, h *histogram.Histogram, fh *histogram.FloatHistogram) (storage.SeriesRef, error)
AppendHistogram implements storage.Appendable
func (*Appender) Commit ¶
Commit commits pending samples, exemplars, and metadata, converting them into a slice of *dto.MetricsFamily. Call MetricFamilies to get the resulting data.
After calling Commit, no other methods except MetricFamilies may be called.
func (*Appender) MetricFamilies ¶
func (app *Appender) MetricFamilies() ([]*dto.MetricFamily, error)
MetricFamilies returns the generated slice of *dto.MetricsFamily. MetricFamilies returns an error unless Commit was called.
MetricFamilies always returns a non-nil slice. If no data was appended, the resulting slice has a length of zero.
func (*Appender) Rollback ¶
Rollback discards pending samples, exemplars, and metadata.
After calling Rollback, no other methods may be called and the Appender must be discarded.
func (*Appender) UpdateMetadata ¶
func (app *Appender) UpdateMetadata(ref storage.SeriesRef, l labels.Labels, m metadata.Metadata) (storage.SeriesRef, error)
UpdateMetadata associates metadata for a given named metric. l must not be empty. Only the `__name__` label is used from the label set; other labels are ignored.
Upon calling Commit, the metadata will be injected into the associated MetricFamily. If m represents a histogram, metrics suffixed with `_bucket`, `_sum`, and `_count` will be brought into the same MetricFamily.
type Comparer ¶
type Comparer struct {
// OpenMetrics indicates that the Comparer should test the OpenMetrics
// representation instead of the Prometheus text exposition format.
OpenMetrics bool
}
Comparer can compare a slice of dto.MetricFamily to an expected list of metrics.
func (Comparer) Compare ¶
func (c Comparer) Compare(families []*dto.MetricFamily, expect string) error
Compare compares the text representation of families to an expected input string. If the OpenMetrics field of the Comparer is true, families is converted into the OpenMetrics text exposition format. Otherwise, families is converted into the Prometheus text exposition format.
To make testing less error-prone, expect is cleaned by removing leading whitespace, trailing whitespace, and empty lines. The cleaned version of expect is then compared directly against the text representation of families.
Source Files
Directories