prometheus

Documentation

Overview

Package prometheus implements plugin that allows to expose prometheus metrics. Metrics are grouped in registries. Each registry is exposed at defined URL path.

Index

• Constants
• Variables
• type API
• type Deps
• type Option
  • func UseDeps(cb func(*Deps)) Option
• type Plugin
  • func NewPlugin(opts ...Option) *Plugin
  • func (p *Plugin) AfterInit() error
  • func (p *Plugin) Close() error
  • func (p *Plugin) Init() error
  • func (p *Plugin) NewRegistry(path string, opts promhttp.HandlerOpts) error
  • func (p *Plugin) Register(registryPath string, collector prometheus.Collector) error
  • func (p *Plugin) RegisterGaugeFunc(registryPath string, namespace string, subsystem string, name string, ...) error
  • func (p *Plugin) Unregister(registryPath string, collector prometheus.Collector) bool

Constants

const DefaultRegistry = "/metrics"

DefaultRegistry default Prometheus metrics URL

Variables

var (
	// ErrPathInvalidFormat is returned if the path doesn't start with slash
	ErrPathInvalidFormat = errors.New("path is invalid, it must start with '/' character")
	// ErrPathAlreadyRegistry is returned on attempt to register a path used by a registry
	ErrPathAlreadyRegistry = errors.New("registry with the path is already registered")
	// ErrRegistryNotFound is returned on attempt to use register that has not been created
	ErrRegistryNotFound = errors.New("registry was not found")
)

var DefaultPlugin = *NewPlugin()

DefaultPlugin is a default instance of Plugin.

Types

type API

type API interface {
	// NewRegistry creates new registry exposed at defined URL path (must begin with '/' character), path is used to reference
	// registry while adding new metrics into registry, opts adjust the behavior of exposed registry. Must be called before
	// AfterInit phase of the Prometheus plugin. An attempt to create  a registry with path that is already used
	// by different registry returns an error.
	NewRegistry(path string, opts promhttp.HandlerOpts) error

	// Register registers prometheus metric (e.g.: created by prometheus.NewGaugeVec, prometheus.NewHistogram,...)
	// to a specified registry
	Register(registryPath string, collector prometheus.Collector) error

	// Unregister unregisters the given metric. The function
	// returns whether a Collector was unregistered.
	Unregister(registryPath string, collector prometheus.Collector) bool

	// RegisterGauge registers custom gauge with specific valueFunc to report status when invoked. RegistryPath identifies
	// the registry. The aim of this method is to simply common use case - adding Gauge with value func.
	RegisterGaugeFunc(registryPath string, namespace string, subsystem string, name string, help string,
		labels prometheus.Labels, valueFunc func() float64) error
}

API allows to create expose metrics using prometheus metrics.

type Deps

type Deps struct {
	infra.PluginName
	Log logging.PluginLogger
	// HTTP server used to expose metrics
	HTTP rest.HTTPHandlers // inject
}

Deps lists dependencies of the plugin.

type Option

type Option func(*Plugin)

Option is a function that can be used in NewPlugin to customize Plugin.

func UseDeps

func UseDeps(cb func(*Deps)) Option

UseDeps returns Option that can inject custom dependencies.

type Plugin

type Plugin struct {
	Deps

	sync.Mutex
	// contains filtered or unexported fields
}

Plugin struct holds all plugin-related data.

func NewPlugin

func NewPlugin(opts ...Option) *Plugin

NewPlugin creates a new Plugin with the provided Options.

func (*Plugin) AfterInit

func (p *Plugin) AfterInit() error

AfterInit registers HTTP handlers.

func (*Plugin) Close

func (p *Plugin) Close() error

Close cleans up the allocated resources.

func (*Plugin) Init

func (p *Plugin) Init() error

Init initializes the internal structures

func (*Plugin) NewRegistry

func (p *Plugin) NewRegistry(path string, opts promhttp.HandlerOpts) error

NewRegistry creates new registry exposed at defined URL path (must begin with '/' character), path is used to reference registry while adding new metrics into registry, opts adjust the behavior of exposed registry. Must be called before AfterInit phase of the Prometheus plugin. An attempt to create a registry with path that is already used by different registry returns an error.

func (*Plugin) Register

func (p *Plugin) Register(registryPath string, collector prometheus.Collector) error

Register registers prometheus metric to a specified registry. In order to add metrics to default registry use prometheus.DefaultRegistry const.

func (*Plugin) RegisterGaugeFunc

func (p *Plugin) RegisterGaugeFunc(registryPath string, namespace string, subsystem string, name string, help string,
	labels prometheus.Labels, valueFunc func() float64) error

RegisterGaugeFunc registers custom gauge with specific valueFunc to report status when invoked. This method simplifies using of Register for common use case. If you want create metric different from GagugeFunc or you're adding a metric that will be unregister later on, use generic Register method instead. RegistryPath identifies the registry where gauge is added.

func (*Plugin) Unregister

func (p *Plugin) Unregister(registryPath string, collector prometheus.Collector) bool

Unregister unregisters the given metric. The function returns whether a Collector was unregistered.