touchbundle

Documentation

Overview

Package touchbundle provides a simple way to create bundles of metrics from configuration. The basic idea is that a single description of metrics can be used to both (1) create application metrics, and (2) verify those metrics for tests.

SPDX-FileCopyrightText: 2022 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2022 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

Index

• Constants
• func MetricName(f reflect.StructField) string
• func Populate(f *touchstone.Factory, b Bundle) error
• func Provide(prototype interface{}) fx.Option
• type Bundle
• type FieldError
  • func (fe *FieldError) Error() string
  • func (fe *FieldError) Unwrap() error

Constants

const (
	// TagTouchstone is the struct field tag that controls whether touchstone
	// ignores the field.  Setting this tag to "-" will cause the field to be
	// ignored and not populated.
	//
	// Use this tag to ignore struct fields that would otherwise be populated,
	// e.g. if a prometheus.Counter field should be ignored.
	TagTouchstone = "touchstone"

	// TagNamespace is the struct field tag that specifies the metric namespace.
	// If absent, the default namespace from the Factory is used.
	TagNamespace = "namespace"

	// TagSubsystem is the struct field tag that specifies the metric subsystem.
	// If absent, the default subsystem from the Factory is used.
	TagSubsystem = "subsystem"

	// TagName is the struct field tag that specifies the metric name.  If absent,
	// the struct field name is snakecased and used as the metric name, e.g.
	// a field such as "MyAppCounter *prometheus.CounterVec" has a default name
	// of "my_app_counter".
	TagName = "name"

	// TagHelp is the struct field tag that specifies the metric help.  There is
	// no default for this tag.
	TagHelp = "help"

	// TagBuckets is the struct field tag specifying the set of histogram buckets.
	// The format of this tag is a comma-delimited string containing float64 values.
	// Internal whitespace is allowed.
	TagBuckets = "buckets"

	// TagObjectives is the struct field tag specifying the set of summary objectives.
	// The format of this tag is a comma-delimited string containing float64 pairs
	// separated by semi-colons, e.g. "1.0:2.5, 3.5:6.7".  Internal whitespace
	// is allowed, e.g. "1.0: 2.5,  3.5: 6.7".
	TagObjectives = "objectives"

	// TagMaxAge is the struct field tag specifying the summary MaxAge.  This tag's
	// value must parse as a uint32.
	TagMaxAge = "maxAge"

	// TagAgeBuckets is the struct field tag specifying the summary AgeBuckets.  This
	// tag's value must parse as a uint32.
	TagAgeBuckets = "ageBuckets"

	// TagBufCap is the struct field tag specifying the summary BufCap.  This tag's
	// value must parse as a uint32.
	TagBufCap = "bufCap"

	// TagLabelNames specifies the set of label names for the metric.  Only permitted
	// for vector metrics, e.g. *prometheus.CounterVec.  This type is only valid for
	// vector types.
	TagLabelNames = "labelNames"

	// TagType is the struct field tag indicating the type of metric, e.g. histogram
	// or summary.  This tag is only valid when the struct field type doesn't
	// uniquely specify a metric, e.g. prometheus.Observer.  If the struct field type
	// does specify a metric, this tag cannot be supplied or an error is raised.
	TagType = "type"

	// TypeHistogram is the TagType value indicating that the metric is a histogram
	// or histogram vector.
	TypeHistogram = "histogram"

	// TypeSummary is the TagType value indicating that the metric is a summary
	// or summary vector.
	TypeSummary = "summary"
)

Functions

func MetricName

func MetricName(f reflect.StructField) string

MetricName determines the metric name of a struct field. A metric name is generated by first looking at the TagName struct field tag, failling back to the snakecase of the field name if that tag is not provide or is empty. The first occurrence of "*" in the tag will be replaced by the snakecase of the field name, allowing for easy prefixes and suffixes.

For example:

type Bundle struct {
    // metric name is:  something_count
    SomethingCount *prometheus.CounterVec `labelNames:"foo,bar"`

    // metric name is: prefix_my_gauge
    MyGauge *prometheus.GaugeVec `name:"prefix_*" labelNames:"foo,bar"`

    // metric name is: custom_name
    AnotherCounter prometheus.Counter `name:"custom_name"`
}

func Populate

func Populate(f *touchstone.Factory, b Bundle) error

Populate fills out a bundle with metrics created by the given Factory.

func Provide

func Provide(prototype interface{}) fx.Option

Provide emits a bundle as an uber/fx component. The supplied prototype must be either a struct or a pointer to struct. The returned component will be a new instance of the same type as the prototype.

For example:

app := fx.New(
    touchbundle.Provide(MyMetrics{}),
    fx.Invoke(
        func(m MyMetrics) {
            // m's metric fields will have been populated
        },
    ),
)

app := fx.New(
    touchbundle.Provide((*MyStruct)(nil)),
    fx.Invoke(
        func(m *MyMetrics) {
            // m's metric fields will have been populated
            // m will point to a distinct, new instance of MyMetrics
        },
    ),
)

Types

type Bundle

type Bundle interface{}

Bundle represents a group of metrics. A bundle must always be a non-nil pointer to struct.

type FieldError

type FieldError struct {
	// Field is the struct field corresponding to the metric.
	Field reflect.StructField

	// Cause is the wrapped error that caused this field error.
	Cause error

	// Message is the error message associated with the field.
	Message string
}

FieldError represents an error while processing a metric field.

func (*FieldError) Error

func (fe *FieldError) Error() string

func (*FieldError) Unwrap

func (fe *FieldError) Unwrap() error