prometheus

README

A buffered Prometheus reporter

See examples/prometheus_main.go for an end to end example.

Options

You can use a specific Prometheus registry, and you can use either summaries or histograms for timers.

The reporter options are:

// Options is a set of options for the tally reporter.
type Options struct {
	// Registerer is the prometheus registerer to register
	// metrics with. Use nil to specify the default registerer.
	Registerer prom.Registerer

	// DefaultTimerType is the default type timer type to create
	// when using timers. It's default value is a histogram timer type.
	DefaultTimerType TimerType

	// DefaultHistogramBuckets is the default histogram buckets
	// to use. Use nil to specify the default histogram buckets.
	DefaultHistogramBuckets []float64

	// DefaultSummaryObjectives is the default summary objectives
	// to use. Use nil to specify the default summary objectives.
	DefaultSummaryObjectives map[float64]float64

	// OnRegisterError defines a method to call to when registering
	// a metric with the registerer fails. Use nil to specify
	// to panic by default when registering a metric fails.
	OnRegisterError func(err error)
}

The timer types are:

// TimerType describes a type of timer
type TimerType int

const (
	// SummaryTimerType is a timer type that reports into a summary
	SummaryTimerType TimerType = iota

	// HistogramTimerType is a timer type that reports into a histogram
	HistogramTimerType
)

You can also pre-register help description text ahead of using a metric that will be named and tagged identically with tally. You can also access the Prometheus HTTP handler directly.

The returned reporter interface:

// Reporter is a Prometheus backed tally reporter.
type Reporter interface {
	tally.CachedStatsReporter

	// HTTPHandler provides the Prometheus HTTP scrape handler.
	HTTPHandler() http.Handler

	// RegisterCounter is a helper method to initialize a counter
	// in the Prometheus backend with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	RegisterCounter(
		name string,
		tagKeys []string,
		desc string,
	) (*prom.CounterVec, error)

	// RegisterGauge is a helper method to initialize a gauge
	// in the prometheus backend with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	RegisterGauge(
		name string,
		tagKeys []string,
		desc string,
	) (*prom.GaugeVec, error)

	// RegisterTimer is a helper method to initialize a timer
	// summary or histogram vector in the prometheus backend
	// with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	// You may pass opts as nil to get the default timer type
	// and objectives/buckets.
	// You may also pass objectives/buckets as nil in opts to
	// get the default objectives/buckets for the specified
	// timer type.
	RegisterTimer(
		name string,
		tagKeys []string,
		desc string,
		opts *RegisterTimerOptions,
	) (TimerUnion, error)
}

The register timer options:

// RegisterTimerOptions provides options when registering a timer on demand.
// By default you can pass nil for the options to get the reporter defaults.
type RegisterTimerOptions struct {
	TimerType         TimerType
	HistogramBuckets  []float64
	SummaryObjectives map[float64]float64
}

Documentation

Index

• Constants
• Variables
• func DefaultHistogramBuckets() []float64
• func DefaultSummaryObjectives() map[float64]float64
• type Configuration
  • func (c Configuration) NewReporter(configOpts ConfigurationOptions) (Reporter, error)
• type ConfigurationOptions
• type HistogramObjective
• type Options
• type RegisterTimerOptions
• type Reporter
  • func NewReporter(opts Options) Reporter
• type SummaryObjective
• type TimerType
• type TimerUnion

Constants

const (
	// DefaultSeparator is the default separator that should be used with
	// a tally scope for a prometheus reporter.
	DefaultSeparator = "_"
)

Variables

var (
	// DefaultSanitizerOpts are the options for the default Prometheus sanitizer.
	DefaultSanitizerOpts = tally.SanitizeOptions{
		NameCharacters: tally.ValidCharacters{
			Ranges:     tally.AlphanumericRange,
			Characters: tally.UnderscoreCharacters,
		},
		KeyCharacters: tally.ValidCharacters{
			Ranges:     tally.AlphanumericRange,
			Characters: tally.UnderscoreCharacters,
		},
		ValueCharacters: tally.ValidCharacters{
			Ranges:     tally.AlphanumericRange,
			Characters: tally.UnderscoreCharacters,
		},
		ReplacementCharacter: tally.DefaultReplacementCharacter,
	}
)

Functions

func DefaultHistogramBuckets

func DefaultHistogramBuckets() []float64

DefaultHistogramBuckets is the default histogram buckets used when creating a new Histogram in the prometheus registry. See: https://godoc.org/github.com/prometheus/client_golang/prometheus#HistogramOpts

func DefaultSummaryObjectives

func DefaultSummaryObjectives() map[float64]float64

DefaultSummaryObjectives is the default objectives used when creating a new Summary in the prometheus registry. See: https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts

Types

type Configuration

type Configuration struct {
	// HandlerPath if specified will be used instead of using the default
	// HTTP handler path "/metrics".
	HandlerPath string `yaml:"handlerPath"`

	// ListenNetwork if specified will be used instead of using tcp network.
	// Supported networks: tcp, tcp4, tcp6 and unix.
	ListenNetwork string `yaml:"listenNetwork"`

	// ListenAddress if specified will be used instead of just registering the
	// handler on the default HTTP serve mux without listening.
	ListenAddress string `yaml:"listenAddress"`

	// TimerType is the default Prometheus type to use for Tally timers.
	TimerType string `yaml:"timerType"`

	// DefaultHistogramBuckets if specified will set the default histogram
	// buckets to be used by the reporter.
	DefaultHistogramBuckets []HistogramObjective `yaml:"defaultHistogramBuckets"`

	// DefaultSummaryObjectives if specified will set the default summary
	// objectives to be used by the reporter.
	DefaultSummaryObjectives []SummaryObjective `yaml:"defaultSummaryObjectives"`

	// OnError specifies what to do when an error either with listening
	// on the specified listen address or registering a metric with the
	// Prometheus. By default the registerer will panic.
	OnError string `yaml:"onError"`
}

Configuration is a configuration for a Prometheus reporter.

func (Configuration) NewReporter

func (c Configuration) NewReporter(
	configOpts ConfigurationOptions,
) (Reporter, error)

NewReporter creates a new M3 reporter from this configuration.

type ConfigurationOptions

type ConfigurationOptions struct {
	// Registry if not nil will specify the specific registry to use
	// for registering metrics.
	Registry *prom.Registry
	// OnError allows for customization of what to do when a metric
	// registration error fails, the default is to panic.
	OnError func(e error)
}

ConfigurationOptions allows some programatic options, such as using a specific registry and what error callback to register.

type HistogramObjective

type HistogramObjective struct {
	Upper float64 `yaml:"upper"`
}

HistogramObjective is a Prometheus histogram bucket. See: https://godoc.org/github.com/prometheus/client_golang/prometheus#HistogramOpts

type Options

type Options struct {
	// Registerer is the prometheus registerer to register
	// metrics with. Use nil to specify the default registerer.
	Registerer prom.Registerer

	// Gatherer is the prometheus gatherer to gather
	// metrics with. Use nil to specify the default gatherer.
	Gatherer prom.Gatherer

	// DefaultTimerType is the default type timer type to create
	// when using timers. It's default value is a summary timer type.
	DefaultTimerType TimerType

	// DefaultHistogramBuckets is the default histogram buckets
	// to use. Use nil to specify the default histogram buckets.
	DefaultHistogramBuckets []float64

	// DefaultSummaryObjectives is the default summary objectives
	// to use. Use nil to specify the default summary objectives.
	DefaultSummaryObjectives map[float64]float64

	// OnRegisterError defines a method to call to when registering
	// a metric with the registerer fails. Use nil to specify
	// to panic by default when registering fails.
	OnRegisterError func(err error)
}

Options is a set of options for the tally reporter.

type RegisterTimerOptions

type RegisterTimerOptions struct {
	TimerType         TimerType
	HistogramBuckets  []float64
	SummaryObjectives map[float64]float64
}

RegisterTimerOptions provides options when registering a timer on demand. By default you can pass nil for the options to get the reporter defaults.

type Reporter

type Reporter interface {
	tally.CachedStatsReporter

	// HTTPHandler provides the Prometheus HTTP scrape handler.
	HTTPHandler() http.Handler

	// RegisterCounter is a helper method to initialize a counter
	// in the Prometheus backend with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	RegisterCounter(
		name string,
		tagKeys []string,
		desc string,
	) (*prom.CounterVec, error)

	// RegisterGauge is a helper method to initialize a gauge
	// in the prometheus backend with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	RegisterGauge(
		name string,
		tagKeys []string,
		desc string,
	) (*prom.GaugeVec, error)

	// RegisterTimer is a helper method to initialize a timer
	// summary or histogram vector in the prometheus backend
	// with a given help text.
	// If not called explicitly, the Reporter will create one for
	// you on first use, with a not super helpful HELP string.
	// You may pass opts as nil to get the default timer type
	// and objectives/buckets.
	// You may also pass objectives/buckets as nil in opts to
	// get the default objectives/buckets for the specified
	// timer type.
	RegisterTimer(
		name string,
		tagKeys []string,
		desc string,
		opts *RegisterTimerOptions,
	) (TimerUnion, error)
}

Reporter is a Prometheus backed tally reporter.

func NewReporter

func NewReporter(opts Options) Reporter

NewReporter returns a new Reporter for Prometheus client backed metrics objectives is the objectives used when creating a new Summary histogram for Timers. See https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts for more details.

type SummaryObjective

type SummaryObjective struct {
	Percentile   float64 `yaml:"percentile"`
	AllowedError float64 `yaml:"allowedError"`
}

SummaryObjective is a Prometheus summary objective. See: https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts

type TimerType

type TimerType int

TimerType describes a type of timer

const (
	// SummaryTimerType is a timer type that reports into a summary
	SummaryTimerType TimerType = iota

	// HistogramTimerType is a timer type that reports into a histogram
	HistogramTimerType
)

type TimerUnion

type TimerUnion struct {
	TimerType TimerType
	Histogram *prom.HistogramVec
	Summary   *prom.SummaryVec
}

TimerUnion is a representation of either a summary or a histogram described by the TimerType.