metrics

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2019 License: Apache-2.0, CC-BY-SA-4.0 Imports: 6 Imported by: 1,526

README

go-metrics GoDoc Badge Badge

This package is small wrapper around the prometheus go client to help enforce convention and best practices for metrics collection in Docker projects.

Best Practices

This packages is meant to be used for collecting metrics in Docker projects. It is not meant to be used as a replacement for the prometheus client but to help enforce consistent naming across metrics collected. If you have not already read the prometheus best practices around naming and labels you can read the page here.

The following are a few Docker specific rules that will help you name and work with metrics in your project.

  1. Namespace and Subsystem

This package provides you with a namespace type that allows you to specify the same namespace and subsystem for your metrics.

ns := metrics.NewNamespace("engine", "daemon", metrics.Labels{
        "version": dockerversion.Version,
        "commit":  dockerversion.GitCommit,
})

In the example above we are creating metrics for the Docker engine's daemon package. engine would be the namespace in this example where daemon is the subsystem or package where we are collecting the metrics.

A namespace also allows you to attach constant labels to the metrics such as the git commit and version that it is collecting.

  1. Declaring your Metrics

Try to keep all your metric declarations in one file. This makes it easy for others to see what constant labels are defined on the namespace and what labels are defined on the metrics when they are created.

  1. Use labels instead of multiple metrics

Labels allow you to define one metric such as the time it takes to perform a certain action on an object. If we wanted to collect timings on various container actions such as create, start, and delete then we can define one metric called container_actions and use labels to specify the type of action.

containerActions = ns.NewLabeledTimer("container_actions", "The number of milliseconds it takes to process each container action", "action")

The last parameter is the label name or key. When adding a data point to the metric you will use the WithValues function to specify the action that you are collecting for.

containerActions.WithValues("create").UpdateSince(start)
  1. Always use a unit

The metric name should describe what you are measuring but you also need to provide the unit that it is being measured with. For a timer, the standard unit is seconds and a counter's standard unit is a total. For gauges you must provide the unit. This package provides a standard set of units for use within the Docker projects.

Nanoseconds Unit = "nanoseconds"
Seconds     Unit = "seconds"
Bytes       Unit = "bytes"
Total       Unit = "total"

If you need to use a unit but it is not defined in the package please open a PR to add it but first try to see if one of the already created units will work for your metric, i.e. seconds or nanoseconds vs adding milliseconds.

Docs

Package documentation can be found here.

HTTP Metrics

To instrument a http handler, you can wrap the code like this:

namespace := metrics.NewNamespace("docker_distribution", "http", metrics.Labels{"handler": "your_http_handler_name"})
httpMetrics := namespace.NewDefaultHttpMetrics()
metrics.Register(namespace)
instrumentedHandler = metrics.InstrumentHandler(httpMetrics, unInstrumentedHandler)

Note: The handler label must be provided when a new namespace is created.

Additional Metrics

Additional metrics are also defined here that are not available in the prometheus client. If you need a custom metrics and it is generic enough to be used by multiple projects, define it here.

Copyright © 2016 Docker, Inc. All rights reserved, except as follows. Code is released under the Apache 2.0 license. The README.md file, and files in the "docs" folder are licensed under the Creative Commons Attribution 4.0 International License under the terms and conditions set forth in the file "LICENSE.docs". You may obtain a duplicate copy of the same license, titled CC-BY-SA-4.0, at http://creativecommons.org/licenses/by/4.0/.

Documentation

Index

Constants

View Source 
const (
	InstrumentHandlerResponseSize = iota
	InstrumentHandlerRequestSize
	InstrumentHandlerDuration
	InstrumentHandlerCounter
	InstrumentHandlerInFlight
)

Variables

This section is empty.

Functions

func Deregister 

func Deregister(n *Namespace)

Deregister removes all the metrics in the provided namespace from the global metrics registry

func Handler 

func Handler() http.Handler

Handler returns the global http.Handler that provides the prometheus metrics format on GET requests. This handler is no longer instrumented.

func InstrumentHandler 

func InstrumentHandler(metrics []*HTTPMetric, handler http.Handler) http.HandlerFunc

func InstrumentHandlerFunc 

func InstrumentHandlerFunc(metrics []*HTTPMetric, handlerFunc http.HandlerFunc) http.HandlerFunc

func Register 

func Register(n *Namespace)

Register adds all the metrics in the provided namespace to the global metrics registry

func StartTimer 

func StartTimer(timer Timer) (done func())

StartTimer begins a timer observation at the callsite. When the target operation is completed, the caller should call the return done func().

Types

type Counter 

type Counter interface {
	// Inc adds Sum(vs) to the counter. Sum(vs) must be positive.
	//
	// If len(vs) == 0, increments the counter by 1.
	Inc(vs ...float64)
}

Counter is a metrics that can only increment its current count

type Gauge 

type Gauge interface {
	Inc(...float64)
	Dec(...float64)

	// Add adds the provided value to the gauge's current value
	Add(float64)

	// Set replaces the gauge's current value with the provided value
	Set(float64)
}

Gauge is a metric that allows incrementing and decrementing a value

type HTTPHandlerOpts 

type HTTPHandlerOpts struct {
	DurationBuckets     []float64
	RequestSizeBuckets  []float64
	ResponseSizeBuckets []float64
}

HTTPHandlerOpts describes a set of configurable options of http metrics

type HTTPMetric 

type HTTPMetric struct {
	prometheus.Collector
	// contains filtered or unexported fields
}

type LabeledCounter 

type LabeledCounter interface {
	WithValues(vs ...string) Counter
}

LabeledCounter is counter that must have labels populated before use.

type LabeledGauge 

type LabeledGauge interface {
	WithValues(labels ...string) Gauge
}

LabeledGauge describes a gauge the must have values populated before use.

type LabeledTimer 

type LabeledTimer interface {
	WithValues(labels ...string) *labeledTimerObserver
}

LabeledTimer is a timer that must have label values populated before use.

type Labels 

type Labels map[string]string

type Namespace 

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

Namespace describes a set of metrics that share a namespace and subsystem.

func NewNamespace 

func NewNamespace(name, subsystem string, labels Labels) *Namespace

NewNamespace returns a namespaces that is responsible for managing a collection of metrics for a particual namespace and subsystem

labels allows const labels to be added to all metrics created in this namespace and are commonly used for data like application version and git commit

func (*Namespace) Add 

func (n *Namespace) Add(collector prometheus.Collector)

func (*Namespace) Collect 

func (n *Namespace) Collect(ch chan<- prometheus.Metric)

func (*Namespace) Describe 

func (n *Namespace) Describe(ch chan<- *prometheus.Desc)

func (*Namespace) NewCounter 

func (n *Namespace) NewCounter(name, help string) Counter

func (*Namespace) NewDefaultHttpMetrics 

func (n *Namespace) NewDefaultHttpMetrics(handlerName string) []*HTTPMetric

func (*Namespace) NewDesc 

func (n *Namespace) NewDesc(name, help string, unit Unit, labels ...string) *prometheus.Desc

func (*Namespace) NewGauge 

func (n *Namespace) NewGauge(name, help string, unit Unit) Gauge

func (*Namespace) NewHttpMetrics 

func (n *Namespace) NewHttpMetrics(handlerName string, durationBuckets, requestSizeBuckets, responseSizeBuckets []float64) []*HTTPMetric

func (*Namespace) NewHttpMetricsWithOpts 

func (n *Namespace) NewHttpMetricsWithOpts(handlerName string, opts HTTPHandlerOpts) []*HTTPMetric

func (*Namespace) NewInFlightGaugeMetric 

func (n *Namespace) NewInFlightGaugeMetric(handlerName string) *HTTPMetric

func (*Namespace) NewLabeledCounter 

func (n *Namespace) NewLabeledCounter(name, help string, labels ...string) LabeledCounter

func (*Namespace) NewLabeledGauge 

func (n *Namespace) NewLabeledGauge(name, help string, unit Unit, labels ...string) LabeledGauge

func (*Namespace) NewLabeledTimer 

func (n *Namespace) NewLabeledTimer(name, help string, labels ...string) LabeledTimer

func (*Namespace) NewRequestDurationMetric 

func (n *Namespace) NewRequestDurationMetric(handlerName string, buckets []float64) *HTTPMetric

func (*Namespace) NewRequestSizeMetric 

func (n *Namespace) NewRequestSizeMetric(handlerName string, buckets []float64) *HTTPMetric

func (*Namespace) NewRequestTotalMetric 

func (n *Namespace) NewRequestTotalMetric(handlerName string) *HTTPMetric

func (*Namespace) NewResponseSizeMetric 

func (n *Namespace) NewResponseSizeMetric(handlerName string, buckets []float64) *HTTPMetric

func (*Namespace) NewTimer 

func (n *Namespace) NewTimer(name, help string) Timer

func (*Namespace) WithConstLabels 

func (n *Namespace) WithConstLabels(labels Labels) *Namespace

WithConstLabels returns a namespace with the provided set of labels merged with the existing constant labels on the namespace. 

Only metrics created with the returned namespace will get the new constant
labels.  The returned namespace must be registered separately.

type Timer 

type Timer interface {
	// Update records an observation, duration, and converts to the target
	// units.
	Update(duration time.Duration)

	// UpdateSince will add the duration from the provided starting time to the
	// timer's summary with the precisions that was used in creation of the timer
	UpdateSince(time.Time)
}

Timer is a metric that allows collecting the duration of an action in seconds

type Unit 

type Unit string

Unit represents the type or precision of a metric that is appended to the metrics fully qualified name 

const (
	Nanoseconds Unit = "nanoseconds"
	Seconds     Unit = "seconds"
	Bytes       Unit = "bytes"
	Total       Unit = "total"
)

Source Files

View all Source files

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.