touchstone

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2021 License: Apache-2.0 Imports: 3 Imported by: 20

README

touchstone

Touchstone is an integration between go.uber.org/fx and prometheus.

Build Status codecov.io Go Report Card Apache V2 License Quality Gate Status GitHub release PkgGoDev

Summary

Touchstone provides easy bootstrapping of a prometheus client environment within a go.uber.org/fx application container. Key features include:

  • External configuration that can drive how the Registry and other components are initialized
  • Simple constructors that allow individual metrics to fully participate in dependency injection
  • Prebundled HTTP metrics with a simpler and more efficient instrumentation than what promhttp provides

Table of Contents

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Install

go get -u github.com/xmidt-org/touchstone

Contributing

Refer to CONTRIBUTING.md.

Documentation

Overview

Package touchstone is an integration between go.uber.org/fx and prometheus.

Example 
type In struct {
	fx.In
	Counter  prometheus.Counter   `name:"example_counter"`
	GaugeVec *prometheus.GaugeVec `name:"example_gaugevec"`
}

_ = fx.New(
	fx.Logger(log.New(ioutil.Discard, "", 0)),
	fx.Supply(
		// this Config instance can come from anywhere
		Config{
			DefaultNamespace: "example",
			DefaultSubsystem: "touchstone",
		},
	),
	Provide(),
	Counter(prometheus.CounterOpts{
		// this will use the default namespace and subsystem
		Name: "example_counter",
	}),
	GaugeVec(prometheus.GaugeOpts{
		Subsystem: "override",
		Name:      "example_gaugevec",
	}, "label"),
	fx.Invoke(
		func(in In) {
			in.Counter.Inc()
			in.GaugeVec.WithLabelValues("value").Add(2.0)

			fmt.Println("counter", testutil.ToFloat64(in.Counter))
			fmt.Println("gaugevec", testutil.ToFloat64(in.GaugeVec))
		},
	),
)

Output:

counter 1
gaugevec 2

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoMetricName indicates that a prometheus *Opts struct did not set the Name field.
	ErrNoMetricName = errors.New("A metric Name is required")
)

Functions

func Counter 

func Counter(o prometheus.CounterOpts) fx.Option

Counter uses a Factory instance from the enclosing fx.App to create and register a prometheus.Counter with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func CounterVec 

func CounterVec(o prometheus.CounterOpts, labelNames ...string) fx.Option

CounterVec uses a Factory instance from the enclosing fx.App to create and register a *prometheus.CounterVec with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func Gauge 

func Gauge(o prometheus.GaugeOpts) fx.Option

Gauge uses a Factory instance from the enclosing fx.App to create and register a prometheus.Gauge with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func GaugeVec 

func GaugeVec(o prometheus.GaugeOpts, labelNames ...string) fx.Option

GaugeVec uses a Factory instance from the enclosing fx.App to create and register a *prometheus.GaugeVec with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func Histogram 

func Histogram(o prometheus.HistogramOpts) fx.Option

Histogram uses a Factory instance from the enclosing fx.App to create and register a prometheus.Observer with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func HistogramVec 

func HistogramVec(o prometheus.HistogramOpts, labelNames ...string) fx.Option

HistogramVec uses a Factory instance from the enclosing fx.App to create and register a prometheus.ObserverVec with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func Metric 

func Metric(name string, target interface{}) fx.Option

Metric emits a named component using the specified target. The target is expected to be a function (constructor) of the same form accepted by fx.Annotated.Target.

If name is empty, application startup is short-circuited with an error.

See: https://pkg.go.dev/go.uber.org/fx#Annotated

func New 

func New(cfg Config) (g prometheus.Gatherer, r prometheus.Registerer, err error)

New bootstraps a prometheus registry given a Config instance. Note that the returned Registerer may be decorated to arbitrary depth.

func Provide 

func Provide() fx.Option

Provide bootstraps a prometheus environment for an uber/fx App. The following component types are provided by this function:

  • prometheus.Gatherer
  • promtheus.Registerer NOTE: Do not rely on the Registerer actually being a *prometheus.Registry. It may be decorated to arbitrary depth.
  • *touchstone.Factory

func Summary 

func Summary(o prometheus.SummaryOpts) fx.Option

Summary uses a Factory instance from the enclosing fx.App to create and register a prometheus.Observer with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

func SummaryVec 

func SummaryVec(o prometheus.SummaryOpts, labelNames ...string) fx.Option

SummaryVec uses a Factory instance from the enclosing fx.App to create and register a prometheus.ObserverVec with the same component name as the metric Name.

If no Name is set, application startup is short-circuited with an error.

Types

type Config 

type Config struct {
	// DefaultNamespace is the prometheus namespace to apply when a metric has no namespace.
	DefaultNamespace string `json:"defaultNamespace" yaml:"defaultNamespace"`

	// DefaultSubsystem is the prometheus subsystem to apply when a metric has no subsystem.
	DefaultSubsystem string `json:"defaultSubsystem" yaml:"defaultSubsystem"`

	// Pedantic controls whether a pedantic Registerer is used as the prometheus backend.
	//
	// See: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewPedanticRegistry
	Pedantic bool `json:"pedantic" yaml:"pedantic"`

	// DisableGoCollector controls whether the go collector is registered on startup.
	// By default, the go collector is registered.
	//
	// See: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector
	DisableGoCollector bool `json:"disableGoCollector" yaml:"disableGoCollector"`

	// DisableProcessCollector controls whether the process collector is registered on startup.
	// By default, this collector is registered.
	//
	// See: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector
	DisableProcessCollector bool `json:"disableProcessCollector" yaml:"disableProcessCollector"`

	// DisableBuildInfoCollector controls whether the build info collector is registered on startup.
	// By default, this collector is registered.
	//
	// See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewBuildInfoCollector
	DisableBuildInfoCollector bool `json:"disableBuildInfoCollector" yaml:"disableBuildInfoCollector"`
}

Config defines the configuration options for bootstrapping a prometheus-based metrics environment.

type Factory 

type Factory struct {
	// contains filtered or unexported fields
}

Factory handles creation and registration of metrics.

This type serves a similar purpose to the promauto package. Instead of registering metrics with a global singleton, it uses the injected prometheus.Registerer. In addition, any DefaultNamespace and DefaultSubsystem set on the Config object are enforced for every metric created through the Factory instance.

If an fx.Printer is supplied, it is used to log warnings about missing Help in *Opts structs.

This package's functions that match metric types, e.g. Counter, CounterVec, etc, use a Factory instance injected from the enclosing fx.App. Those functions are generally preferred to using a Factory directly, since they emit their metrics as components which can then be injected as needed.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/promauto

Example 
var f *Factory
_ = fx.New(
	fx.Logger(log.New(ioutil.Discard, "", 0)),
	Provide(),
	fx.Populate(&f),
)

c, err := f.NewCounterVec(
	prometheus.CounterOpts{
		Name: "example",
		Help: "here is a lovely example",
	}, "label",
)

if err != nil {
	fmt.Println(err)
	return
}

c.WithLabelValues("value").Inc()
fmt.Println(testutil.ToFloat64(c))

Output:

1

func NewFactory 

func NewFactory(cfg Config, p fx.Printer, r prometheus.Registerer) *Factory

NewFactory produces a Factory that uses the supplied registry.

func (*Factory) DefaultNamespace 

func (f *Factory) DefaultNamespace() string

DefaultNamespace returns the namespace used to register metrics when no Namespace is specified in the *Opts struct. This may be empty to indicate that there is no default.

func (*Factory) DefaultSubsystem 

func (f *Factory) DefaultSubsystem() string

DefaultSubsystem returns the subsystem used to register metrics when no Subsystem is specified in the *Opts struct. This may be empty to indicate that there is no default.

func (*Factory) NewCounter 

func (f *Factory) NewCounter(o prometheus.CounterOpts) (m prometheus.Counter, err error)

NewCounter creates and registers a new counter using the supplied options.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewCounter

func (*Factory) NewCounterFunc 

func (f *Factory) NewCounterFunc(o prometheus.CounterOpts, fn func() float64) (m prometheus.CounterFunc, err error)

NewCounterFunc creates and registers a new counter backed by the given function.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewCounterFunc

func (*Factory) NewCounterVec 

func (f *Factory) NewCounterVec(o prometheus.CounterOpts, labelNames ...string) (m *prometheus.CounterVec, err error)

NewCounterVec creates and registers a new counter vector using the supplied options.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewCounterVec

func (*Factory) NewGauge 

func (f *Factory) NewGauge(o prometheus.GaugeOpts) (m prometheus.Gauge, err error)

NewGauge creates and registers a new gauge using the supplied options.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewGauge

func (*Factory) NewGaugeFunc 

func (f *Factory) NewGaugeFunc(o prometheus.GaugeOpts, fn func() float64) (m prometheus.GaugeFunc, err error)

NewGaugeFunc creates and registers a new gauge backed by the given function.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewGaugeFunc

func (*Factory) NewGaugeVec 

func (f *Factory) NewGaugeVec(o prometheus.GaugeOpts, labelNames ...string) (m *prometheus.GaugeVec, err error)

NewGaugeVec creates and registers a new gauge vector using the supplied options.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewGaugeVec

func (*Factory) NewHistogram 

func (f *Factory) NewHistogram(o prometheus.HistogramOpts) (m prometheus.Observer, err error)

NewHistogram creates and registers a new observer using the supplied options. The Observer component is backed by a prometheus.Histogram.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewHistogram

func (*Factory) NewHistogramVec 

func (f *Factory) NewHistogramVec(o prometheus.HistogramOpts, labelNames ...string) (m prometheus.ObserverVec, err error)

NewHistogramVec creates and registers a new observer vector using the supplied options. The ObserverVec component is backed by a prometheus.HistogramVec.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewHistogramVec

func (*Factory) NewSummary 

func (f *Factory) NewSummary(o prometheus.SummaryOpts) (m prometheus.Observer, err error)

NewSummary creates and registers a new observer using the supplied options. The Observer component is backed by a prometheus.Summary.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewSummary

func (*Factory) NewSummaryVec 

func (f *Factory) NewSummaryVec(o prometheus.SummaryOpts, labelNames ...string) (m prometheus.ObserverVec, err error)

NewSummaryVec creates and registers a new observer vector using the supplied options. The ObserverVec component is backed by a prometheus.SummaryVec.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewSummaryVec

func (*Factory) NewUntypedFunc 

func (f *Factory) NewUntypedFunc(o prometheus.UntypedOpts, fn func() float64) (m prometheus.UntypedFunc, err error)

NewUntypedFunc creates and registers a new metric backed by the given function.

This method returns an error if the options do not specify a name. Both namespace and subsystem are defaulted appropriately if not set in the options.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewUntypedFunc

type In 

type In struct {
	fx.In

	// Config is the prometheus configuration.  This is optional,
	// as a zero value for Config will result in a default environment.
	Config Config `optional:"true"`

	// Printer is the fx.Printer to which this package writes messages.
	// This is optional, and if unset no messages are written.
	Printer fx.Printer `optional:"true"`
}

In represents the components used by this package to bootstrap a prometheus environment. Provide uses these components.

Source Files

View all Source files

Directories

Path Synopsis
Package touchhttp defines the HTTP-specific behavior for metrics within an uber/fx app which uses the touchstone package.
 Package touchhttp defines the HTTP-specific behavior for metrics within an uber/fx app which uses the touchstone package.
Package touchkit adds integration with go-kit's metrics API with prometheus as the backend.
 Package touchkit adds integration with go-kit's metrics API with prometheus as the backend.
Package touchtest exposes common prometheus testing utilities.
 Package touchtest exposes common prometheus testing utilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.