metrics

README

Metrics

Package to register metrics into Prometheus from Go

Package usage

Include this package into your project with:

go get github.com/Travix-International/go-metrics

Usage

Note: please refer to the Prometheus documentation for the exact details on each counter and on how to choose the counters that best fit your use cases.

// Initialization
metrics := metrics.NewMetrics("namespace", logger.New())

// Example: simple count
metrics.Count("searchcache", "hit", "SearchCache cache hits")

// Example: count with labels
metrics.CountLabels("service", "get_liveness_request_duration_milliseconds", 
	"Response times for GET requests to liveness in milliseconds.",
	[]string{"status", "method"}, []string{strconv.Itoa(ww.status), r.Method})

// Example: increase counter by 5
metrics.IncreaseCounter("kpimetrics", "fullflowpublishing_errors_count", 
	"total number of errors while publishing fares to Datastore.", 5)

// Example: histogram of processing times
func UseHistogram(req *someRequest) someResponse {
		histogram := metrics.AddHistogram("datastore", "getroutefare_request_duration_milliseconds", 
			"Response times for getRouteFare requests to Datastore in milliseconds.")
		
		start := time.Now()
		defer func() {
			histogram.RecordTimeElapsed(start)
		}()

		// Do work that runs for some time

		return myResponse
	}

Dependencies

• logger
• Prometheus

Known limitations

Histograms

When adding a histogram, the library will create both a summary and histogram. The summary is currently hard-coded to use the following percentiles: 0.5 / 0.75 / 0.9 / 0.95 / 0.99 / 0.999. This should cover most use cases. As for the histogram, this is currently using the default buckets from the Prometheus library, which will not fit all use cases. It will work correctly for simple network traffic, but not for cases which typically have a higher value (more than one second). The buckets are currently not configurable.

Documentation

Index

• func DefaultObjectives() map[float64]float64
• type HistogramVec
  • func (vec *HistogramVec) Observe(value float64)
  • func (vec *HistogramVec) RecordDuration(start time.Time, unit time.Duration)
  • func (vec *HistogramVec) RecordTimeElapsed(start time.Time)
• type Metrics
  • func NewMetrics(namespace string, logger *logger.Logger) *Metrics
  • func (m *Metrics) AddHistogram(subsystem, name, help string) *MetricsHistogram
  • func (m *Metrics) AddHistogramVec(subsystem, name, help string, labels, labelValues []string) *HistogramVec
  • func (m *Metrics) AddHistogramVecWithCustomBuckets(subsystem, name, help string, labels, labelValues []string, buckets []float64) *HistogramVec
  • func (m *Metrics) AddHistogramWithCustomBuckets(subsystem, name, help string, buckets []float64) *MetricsHistogram
  • func (m *Metrics) AddSummaryVec(subsystem, name, help string, labels, labelValues []string) *SummaryVec
  • func (m *Metrics) AddSummaryVecWithCustomObjectives(subsystem, name, help string, labels, labelValues []string, ...) *SummaryVec
  • func (m *Metrics) Count(subsystem, name, help string)
  • func (m *Metrics) CountLabels(subsystem, name, help string, labels, values []string)
  • func (m *Metrics) IncreaseCounter(subsystem, name, help string, increment int)
  • func (m *Metrics) SetGauge(value float64, subsystem, name, help string)
• type MetricsHistogram
  • func (histogram *MetricsHistogram) Observe(value float64)
  • func (histogram *MetricsHistogram) RecordDuration(start time.Time, unit time.Duration)
  • func (histogram *MetricsHistogram) RecordTimeElapsed(start time.Time)
• type SummaryVec
  • func (vec *SummaryVec) RecordDuration(start time.Time, unit time.Duration)
  • func (vec *SummaryVec) RecordTimeElapsed(start time.Time)

Functions

func DefaultObjectives

func DefaultObjectives() map[float64]float64

DefaultObjectives returns a default map of quantiles to be used in summaries.

Types

type HistogramVec

type HistogramVec struct {
	Key         string
	Labels      []string
	LabelValues []string
	// contains filtered or unexported fields
}

HistogramVec wraps prometheus.HistogramVec

func (*HistogramVec) Observe

func (vec *HistogramVec) Observe(value float64)

Observe adds the specified value to the histogram.

func (*HistogramVec) RecordDuration

func (vec *HistogramVec) RecordDuration(start time.Time, unit time.Duration)

RecordDuration adds the elapsed time since the specified start to the histogram in the specified unit of time.

func (*HistogramVec) RecordTimeElapsed

func (vec *HistogramVec) RecordTimeElapsed(start time.Time)

RecordTimeElapsed adds the elapsed time since the specified start to the histogram in seconds.

type Metrics

type Metrics struct {
	Namespace     string
	Counters      map[string]prometheus.Counter
	CounterVecs   map[string]*prometheus.CounterVec
	Summaries     map[string]prometheus.Summary
	SummaryVecs   map[string]*prometheus.SummaryVec
	Histograms    map[string]prometheus.Histogram
	HistogramVecs map[string]*prometheus.HistogramVec
	Gauges        map[string]prometheus.Gauge
	Logger        *logger.Logger
	// contains filtered or unexported fields
}

Metrics provides a set of convenience functions that wrap Prometheus

func NewMetrics

func NewMetrics(namespace string, logger *logger.Logger) *Metrics

NewMetrics will instantiate a new Metrics wrapper object

func (*Metrics) AddHistogram

func (m *Metrics) AddHistogram(subsystem, name, help string) *MetricsHistogram

AddHistogram returns the MetricsHistogram for the specified subsystem and name.

func (*Metrics) AddHistogramVec

func (m *Metrics) AddHistogramVec(subsystem, name, help string, labels, labelValues []string) *HistogramVec

AddHistogramVec returns the HistogramVec for the specified subsystem and name.

func (*Metrics) AddHistogramVecWithCustomBuckets

func (m *Metrics) AddHistogramVecWithCustomBuckets(subsystem, name, help string, labels, labelValues []string,
	buckets []float64) *HistogramVec

AddHistogramVecWithCustomBuckets returns the HistogramVec for the specified subsystem and name with the specified buckets.

func (*Metrics) AddHistogramWithCustomBuckets

func (m *Metrics) AddHistogramWithCustomBuckets(subsystem, name, help string, buckets []float64) *MetricsHistogram

AddHistogramWithCustomBuckets returns the MetricsHistogram for the specified subsystem and name with the specified buckets.

func (*Metrics) AddSummaryVec

func (m *Metrics) AddSummaryVec(subsystem, name, help string, labels, labelValues []string) *SummaryVec

AddSummaryVec returns the SummaryVec for the specified subsystem and name.

func (*Metrics) AddSummaryVecWithCustomObjectives

func (m *Metrics) AddSummaryVecWithCustomObjectives(subsystem, name, help string, labels, labelValues []string,
	objectives map[float64]float64) *SummaryVec

AddSummaryVecWithCustomObjectives returns the SummaryVec for the specified subsystem and name with the specified objectives.

func (*Metrics) Count

func (m *Metrics) Count(subsystem, name, help string)

Count increases the counter for the specified subsystem and name.

func (*Metrics) CountLabels

func (m *Metrics) CountLabels(subsystem, name, help string, labels, values []string)

CountLabels increases the counter for the specified subsystem and name and adds the specified labels with values.

func (*Metrics) IncreaseCounter

func (m *Metrics) IncreaseCounter(subsystem, name, help string, increment int)

IncreaseCounter increases the counter for the specified subsystem and name with the specified increment.

func (*Metrics) SetGauge

func (m *Metrics) SetGauge(value float64, subsystem, name, help string)

SetGauge sets the gauge value for the specified subsystem and name.

type MetricsHistogram

type MetricsHistogram struct {
	Key string
	// contains filtered or unexported fields
}

MetricsHistogram combines a histogram and summary

func (*MetricsHistogram) Observe

func (histogram *MetricsHistogram) Observe(value float64)

Observe adds the specified value to the histogram.

func (*MetricsHistogram) RecordDuration

func (histogram *MetricsHistogram) RecordDuration(start time.Time, unit time.Duration)

RecordDuration adds the elapsed time since the specified start to the histogram in the specified unit of time and to the linked summary in milliseconds.

func (*MetricsHistogram) RecordTimeElapsed

func (histogram *MetricsHistogram) RecordTimeElapsed(start time.Time)

RecordTimeElapsed adds the elapsed time since the specified start to the histogram in seconds and to the linked summary in milliseconds.

type SummaryVec

type SummaryVec struct {
	Key         string
	Labels      []string
	LabelValues []string
	// contains filtered or unexported fields
}

SummaryVec wraps prometheus.SummaryVec

func (*SummaryVec) RecordDuration

func (vec *SummaryVec) RecordDuration(start time.Time, unit time.Duration)

RecordDuration adds the elapsed time since the specified start to the histogram in the specified unit of time.

func (*SummaryVec) RecordTimeElapsed

func (vec *SummaryVec) RecordTimeElapsed(start time.Time)

RecordTimeElapsed adds the elapsed time since the specified start to the summary in milliseconds.