testappender

Documentation

Overview

Package testappender exposes utilities to test code which writes to Prometheus storage.Appenders.

Example

package main

import (
	"fmt"

	"github.com/grafana/agent/pkg/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
  • func (c Comparer) Compare(families []*dto.MetricFamily, expect string) error

Examples

• Package

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, but always returns an error as native histograms are not supported.

func (*Appender) Commit

func (app *Appender) Commit() error

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

func (app *Appender) Rollback() error

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.