metrics

package module
v1.5.1 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2023 License: CC0-1.0 Imports: 10 Imported by: 1

README

API Build

About

Metrics are measures of quantitative assessment commonly used for comparing, and tracking performance or production. This library offers atomic counters, gauges and historgrams for the Go programming language. Users have the option to expose snapshots in the Prometheus text-format.

This is free and unencumbered software released into the public domain.

Use

Static regisration on package level comes recommened. The declarations also help to document the funcionality that is covered in the code.

// Package Metrics
var (
	ConnectCount = metrics.MustCounter("db_connects_total", "Number of established initiations.")
	CacheBytes   = metrics.MustInteger("db_cache_bytes", "Size of collective responses.")
	DiskUsage    = metrics.Must1LabelRealSample("db_disk_usage_ratio", "device")
)

Update methods operate error free by design, e.g., CacheBytes.Add(-72) or DiskUsage(dev.Name).Set(1 - dev.Free, time.Now()).

Serve HTTP with just http.HandleFunc("/metrics", metrics.ServeHTTP).

< HTTP/1.1 200 OK
< Content-Type: text/plain;version=0.0.4
< Date: Sun, 07 Mar 2021 15:22:47 GMT
< Content-Length: 351
< 
# Prometheus Samples

# TYPE db_connects_total counter
# HELP db_connects_total Number of established initiations.
db_connects_total 4 1615130567389

# TYPE db_cache_bytes gauge
# HELP db_cache_bytes Size of collective responses.
db_cache_bytes 7600 1615130567389

# TYPE db_disk_usage_ratio gauge
db_disk_usage_ratio{device="sda"} 0.19 1615130563595

Package github.com/pascaldekloe/metrics/gostat provides a standard collection of Go metrics which is similar to the setup as provided by the original Prometheus library.

Samples may be fetched in a lazy manner, like how the lazy example does.

Performance

The following results were measured on an Apple M1 with Go 1.20.

name                          time/op
Label/sequential/4-8            14.4ns ± 0%
Label/sequential/4x4-8          17.1ns ± 0%
Label/sequential/4x4x4-8        29.6ns ± 0%
Label/parallel/4-8              85.3ns ± 2%
Label/parallel/4x4-8            89.2ns ± 1%
Label/parallel/4x4x4-8           103ns ± 0%
Get/histogram5/sequential-8     45.0ns ± 0%
Get/histogram5/2routines-8      85.1ns ± 0%
Set/real/sequential-8           5.64ns ± 0%
Set/real/2routines-8            16.5ns ± 2%
Set/sample/sequential-8         13.6ns ± 1%
Set/sample/2routines-8          38.7ns ± 7%
Add/counter/sequential-8        6.88ns ± 0%
Add/counter/2routines-8         16.1ns ± 2%
Add/integer/sequential-8        6.88ns ± 0%
Add/integer/2routines-8         16.1ns ± 1%
Add/histogram5/sequential-8     16.1ns ± 1%
Add/histogram5/2routines-8      69.5ns ± 1%
ServeHTTP/32/counter-8           687ns ± 0%
ServeHTTP/32/real-8             1.87µs ± 0%
ServeHTTP/32/integer-8           694ns ± 0%
ServeHTTP/32/histogram5-8       6.05µs ± 0%
ServeHTTP/32/label5-8           1.97µs ± 0%
ServeHTTP/32/label2x3x5-8       1.98µs ± 0%
ServeHTTP/32/sample-8           2.06µs ± 0%
ServeHTTP/1024/counter-8        18.5µs ± 0%
ServeHTTP/1024/real-8           50.9µs ± 0%
ServeHTTP/1024/integer-8        18.8µs ± 0%
ServeHTTP/1024/histogram5-8      192µs ± 0%
ServeHTTP/1024/label5-8         54.4µs ± 0%
ServeHTTP/1024/label2x3x5-8     54.4µs ± 0%
ServeHTTP/1024/sample-8         57.6µs ± 0%

Documentation

Overview

Package metrics provides atomic measures and Prometheus exposition.

Counter, Integer, Real and Histogram are live representations of events. Value updates should be part of the respective implementation. Otherwise, use Sample for captures with a timestamp.

The Must functions deal with registration. Their use is intended for setup during application launch only. All metrics are permanent-the API offers no deletion by design.

Example (Labels) 
package main

import (
	"os"

	"github.com/pascaldekloe/metrics"
)

func main() {
	// setup
	demo := metrics.NewRegister()
	Building := demo.Must2LabelInteger("hitpoints_total", "ground", "building")
	Arsenal := demo.Must3LabelInteger("hitpoints_total", "ground", "arsenal", "side")
	demo.MustHelp("hitpoints_total", "Damage Capacity")

	// measures
	Building("Genesis Pit", "Civilian Hospital").Set(800)
	Arsenal("Genesis Pit", "Tech Center", "Nod").Set(500)
	Arsenal("Genesis Pit", "Cyborg", "Nod").Set(900)
	Arsenal("Genesis Pit", "Cyborg", "Nod").Add(-596)
	Building("Genesis Pit", "Civilian Hospital").Add(-490)
	Arsenal("Genesis Pit", "Cyborg", "Nod").Add(110)

	// print
	metrics.SkipTimestamp = true
	demo.WriteTo(os.Stdout)
}

Output:

# Prometheus Samples

# TYPE hitpoints_total gauge
# HELP hitpoints_total Damage Capacity
hitpoints_total{building="Civilian Hospital",ground="Genesis Pit"} 310
hitpoints_total{arsenal="Tech Center",ground="Genesis Pit",side="Nod"} 500
hitpoints_total{arsenal="Cyborg",ground="Genesis Pit",side="Nod"} 414

Index

Examples

Constants

This section is empty.

Variables

View Source 
var SkipTimestamp = false

SkipTimestamp controls time inclusion with sample serialisation. When false, then live running values are stamped with the current time and Samples provide their own time.

Functions

func Must1LabelCounter 

func Must1LabelCounter(name, labelName string) func(labelValue string) *Counter

Must1LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func Must1LabelCounterSample 

func Must1LabelCounterSample(name, labelName string) func(labelValue string) *Sample

Must1LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func Must1LabelHistogram 

func Must1LabelHistogram(name, labelName string, buckets ...float64) func(labelValue string) *Histogram

Must1LabelHistogram returns a function which registers a dedicated Histogram for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Histogram represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func Must1LabelInteger 

func Must1LabelInteger(name, labelName string) func(labelValue string) *Integer

Must1LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func Must1LabelReal 

func Must1LabelReal(name, labelName string) func(labelValue string) *Real

Must1LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func Must1LabelRealSample 

func Must1LabelRealSample(name, labelName string) func(labelValue string) *Sample

Must1LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func Must2LabelCounter 

func Must2LabelCounter(name, label1Name, label2Name string) func(label1Value, label2Value string) *Counter

Must2LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must2LabelCounterSample 

func Must2LabelCounterSample(name, label1Name, label2Name string) func(label1Value, label2Value string) *Sample

Must2LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must2LabelHistogram 

func Must2LabelHistogram(name, label1Name, label2Name string, buckets ...float64) func(label1Value, label2Value string) *Histogram

Must2LabelHistogram returns a function which registers a dedicated Histogram for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Histogram represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func Must2LabelInteger 

func Must2LabelInteger(name, label1Name, label2Name string) func(label1Value, label2Value string) *Integer

Must2LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must2LabelReal 

func Must2LabelReal(name, label1Name, label2Name string) func(label1Value, label2Value string) *Real

Must2LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must2LabelRealSample 

func Must2LabelRealSample(name, label1Name, label2Name string) func(label1Value, label2Value string) *Sample

Must2LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must3LabelCounter 

func Must3LabelCounter(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Counter

Must3LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must3LabelCounterSample 

func Must3LabelCounterSample(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Sample

Must3LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must3LabelInteger 

func Must3LabelInteger(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Integer

Must3LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must3LabelReal 

func Must3LabelReal(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Real

Must3LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func Must3LabelRealSample 

func Must3LabelRealSample(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Sample

Must3LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func MustHelp 

func MustHelp(name, text string)

MustHelp sets the comment for the metric name. Any previous text is replaced. The function panics when name is not in use.

func ServeHTTP 

func ServeHTTP(resp http.ResponseWriter, req *http.Request)

ServeHTTP provides a sample of each metric as an http.HandlerFunc.

func WriteText 

func WriteText(w io.Writer)

WriteText serialises a sample of each metric in a simple text format. All errors returned by Writer are ignored by design. Deprecated: Use WriteTo instead.

func WriteTo added in v1.3.0 

func WriteTo(w io.Writer) (n int64, err error)

WriteTo serialises a sample of each metric in a simple text format as an io.WriterTo.

Types

type Counter 

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

Counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. The default/initial value is zero. Multiple goroutines may invoke methods on a Counter simultaneously.

func MustCounter 

func MustCounter(name, help string) *Counter

MustCounter registers a new Counter. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Counter) Add 

func (m *Counter) Add(n uint64)

Add increments the current value with n.

func (*Counter) Get 

func (m *Counter) Get() uint64

Get returns the current value.

func (*Counter) Labels added in v1.5.0 

func (m *Counter) Labels() map[string]string

Labels returns a new map if m has labels.

func (*Counter) Name added in v1.2.0 

func (m *Counter) Name() string

Name returns the metric identifier.

type Histogram 

type Histogram struct {

	// Upper value for each bucket, sorted, +Inf omitted.
	// This field is read-only.
	BucketBounds []float64
	// contains filtered or unexported fields
}

Histogram samples observations and counts them in configurable buckets. It also provides a sum of all observed values. Multiple goroutines may invoke methods on a Histogram simultaneously.

Example 
package main

import (
	"os"

	"github.com/pascaldekloe/metrics"
)

func main() {
	// setup
	demo := metrics.NewRegister()
	Duration := demo.Must2LabelHistogram("http_latency_seconds", "method", "status", 0.001, 0.005, 0.025, 0.125)
	demo.MustHelp("http_latency_seconds", "Time from request initiation until response body retrieval.")

	// measures
	Duration("GET", "2xx").Add(0.076875)
	Duration("GET", "3xx").Add(0.000141)
	Duration("OPTIONS", "2xx").Add(0.000009)
	Duration("GET", "2xx").Add(0.002277)
	Duration("GET", "2xx").Add(0.001871)
	Duration("GET", "2xx").Add(0.002378)

	// print
	metrics.SkipTimestamp = true
	demo.WriteTo(os.Stdout)
}

Output:

# Prometheus Samples

# TYPE http_latency_seconds histogram
# HELP http_latency_seconds Time from request initiation until response body retrieval.
http_latency_seconds_count{method="GET",status="2xx"} 4
http_latency_seconds{le="0.001",method="GET",status="2xx"} 0
http_latency_seconds{le="0.005",method="GET",status="2xx"} 3
http_latency_seconds{le="0.025",method="GET",status="2xx"} 3
http_latency_seconds{le="0.125",method="GET",status="2xx"} 4
http_latency_seconds{le="+Inf",method="GET",status="2xx"} 4
http_latency_seconds_sum{method="GET",status="2xx"} 0.083401
http_latency_seconds_count{method="GET",status="3xx"} 1
http_latency_seconds{le="0.001",method="GET",status="3xx"} 1
http_latency_seconds{le="0.005",method="GET",status="3xx"} 1
http_latency_seconds{le="0.025",method="GET",status="3xx"} 1
http_latency_seconds{le="0.125",method="GET",status="3xx"} 1
http_latency_seconds{le="+Inf",method="GET",status="3xx"} 1
http_latency_seconds_sum{method="GET",status="3xx"} 0.000141
http_latency_seconds_count{method="OPTIONS",status="2xx"} 1
http_latency_seconds{le="0.001",method="OPTIONS",status="2xx"} 1
http_latency_seconds{le="0.005",method="OPTIONS",status="2xx"} 1
http_latency_seconds{le="0.025",method="OPTIONS",status="2xx"} 1
http_latency_seconds{le="0.125",method="OPTIONS",status="2xx"} 1
http_latency_seconds{le="+Inf",method="OPTIONS",status="2xx"} 1
http_latency_seconds_sum{method="OPTIONS",status="2xx"} 9e-06

func MustHistogram 

func MustHistogram(name, help string, buckets ...float64) *Histogram

MustHistogram registers a new Histogram. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func (*Histogram) Add 

func (h *Histogram) Add(value float64)

Add applies value to the countings.

func (*Histogram) AddSince 

func (h *Histogram) AddSince(start time.Time)

AddSince applies the number of seconds since start to the countings. The following one-liner measures the execution time of a function. 

defer DurationHistogram.AddSince(time.Now())

func (*Histogram) Get 

func (h *Histogram) Get(a []uint64) (buckets []uint64, count uint64, sum float64)

Get appends the observation counts for each Histogram.BucketBounds to a and returns the resulting slice (as buckets). The count return has the total number of observations, a.k.a. the positive inifinity bucket.

func (*Histogram) Labels added in v1.5.0 

func (m *Histogram) Labels() map[string]string

Labels returns a new map if m has labels.

func (*Histogram) Name added in v1.2.0 

func (m *Histogram) Name() string

Name returns the metric identifier.

type Integer 

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

Integer gauge is a metric that represents a single numerical value that can arbitrarily go up and down. The default/initial value is zero. Multiple goroutines may invoke methods on a Integer simultaneously.

func MustInteger 

func MustInteger(name, help string) *Integer

MustInteger registers a new gauge. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Integer) Add 

func (m *Integer) Add(n int64)

Add summs the current value with n. Note that n can be negative (for subtraction).

func (*Integer) Get 

func (m *Integer) Get() int64

Get returns the current value.

func (*Integer) Labels added in v1.5.0 

func (m *Integer) Labels() map[string]string

Labels returns a new map if m has labels.

func (*Integer) Name added in v1.2.0 

func (m *Integer) Name() string

Name returns the metric identifier.

func (*Integer) Set 

func (m *Integer) Set(update int64)

Set defines the current value.

type Real 

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

Real gauge is a metric that represents a single numerical value that can arbitrarily go up and down. The default/initial value is zero. Multiple goroutines may invoke methods on a Real simultaneously.

func MustReal 

func MustReal(name, help string) *Real

MustReal registers a new gauge. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Real) Get 

func (m *Real) Get() float64

Get returns the current value.

func (*Real) Labels added in v1.5.0 

func (m *Real) Labels() map[string]string

Labels returns a new map if m has labels.

func (*Real) Name added in v1.2.0 

func (m *Real) Name() string

Name returns the metric identifier.

func (*Real) Set 

func (m *Real) Set(update float64)

Set defines the current value.

func (*Real) SetSeconds added in v1.4.0 

func (m *Real) SetSeconds(update time.Duration)

SetSeconds defines the current value.

type Register 

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

Register is a metric bundle.

func NewRegister 

func NewRegister() *Register

NewRegister returns an empty metric bundle. The corresponding functions of each Register method operate on the (hidden) default instance.

func (*Register) Must1LabelCounter 

func (reg *Register) Must1LabelCounter(name, labelName string) func(labelValue string) *Counter

Must1LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func (*Register) Must1LabelCounterSample 

func (reg *Register) Must1LabelCounterSample(name, labelName string) func(labelValue string) *Sample

Must1LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func (*Register) Must1LabelHistogram 

func (reg *Register) Must1LabelHistogram(name, labelName string, buckets ...float64) func(labelValue string) *Histogram

Must1LabelHistogram returns a function which registers a dedicated Histogram for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Histogram represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func (*Register) Must1LabelInteger 

func (reg *Register) Must1LabelInteger(name, labelName string) func(labelValue string) *Integer

Must1LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func (*Register) Must1LabelReal 

func (reg *Register) Must1LabelReal(name, labelName string) func(labelValue string) *Real

Must1LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func (*Register) Must1LabelRealSample 

func (reg *Register) Must1LabelRealSample(name, labelName string) func(labelValue string) *Sample

Must1LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) labelName does not match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) labelName is already in use.

func (*Register) Must2LabelCounter 

func (reg *Register) Must2LabelCounter(name, label1Name, label2Name string) func(label1Value, label2Value string) *Counter

Must2LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must2LabelCounterSample 

func (reg *Register) Must2LabelCounterSample(name, label1Name, label2Name string) func(label1Value, label2Value string) *Sample

Must2LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must2LabelHistogram 

func (reg *Register) Must2LabelHistogram(name, label1Name, label2Name string, buckets ...float64) func(label1Value, label2Value string) *Histogram

Must2LabelHistogram returns a function which registers a dedicated Histogram for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Histogram represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func (*Register) Must2LabelInteger 

func (reg *Register) Must2LabelInteger(name, label1Name, label2Name string) func(label1Value, label2Value string) *Integer

Must2LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must2LabelReal 

func (reg *Register) Must2LabelReal(name, label1Name, label2Name string) func(label1Value, label2Value string) *Real

Must2LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must2LabelRealSample 

func (reg *Register) Must2LabelRealSample(name, label1Name, label2Name string) func(label1Value, label2Value string) *Sample

Must2LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must3LabelCounter 

func (reg *Register) Must3LabelCounter(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Counter

Must3LabelCounter returns a function which registers a dedicated Counter for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Counter represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must3LabelCounterSample 

func (reg *Register) Must3LabelCounterSample(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Sample

Must3LabelCounterSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must3LabelInteger 

func (reg *Register) Must3LabelInteger(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Integer

Must3LabelInteger returns a function which registers a dedicated Integer for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Integer represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must3LabelReal 

func (reg *Register) Must3LabelReal(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Real

Must3LabelReal returns a function which registers a dedicated Real for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Real represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) Must3LabelRealSample 

func (reg *Register) Must3LabelRealSample(name, label1Name, label2Name, label3Name string) func(label1Value, label2Value, label3Value string) *Sample

Must3LabelRealSample returns a function which registers a dedicated Sample for each unique label combination. Multiple goroutines may invoke the returned simultaneously. Remember that each Sample represents a new time series, which can dramatically increase the amount of data stored.

Must panics on any of the following: (1) name in use as another metric type, (2) name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*, (3) label names don't match regular expression [a-zA-Z_][a-zA-Z0-9_]* or (4) label names are already in use.

func (*Register) MustCounter 

func (reg *Register) MustCounter(name, help string) *Counter

MustCounter registers a new Counter. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Register) MustCounterSample 

func (reg *Register) MustCounterSample(name, help string) *Sample

MustCounterSample registers a new Sample. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Register) MustHelp 

func (reg *Register) MustHelp(name, text string)

MustHelp sets the comment for the metric name. Any previous text is replaced. The function panics when name is not in use.

func (*Register) MustHistogram 

func (reg *Register) MustHistogram(name, help string, buckets ...float64) *Histogram

MustHistogram registers a new Histogram. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

Buckets are defined as upper boundary values, with positive infinity implied when absent. Any ∞ or not-a-number (NaN) value is ignored.

func (*Register) MustInteger 

func (reg *Register) MustInteger(name, help string) *Integer

MustInteger registers a new gauge. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Register) MustReal 

func (reg *Register) MustReal(name, help string) *Real

MustReal registers a new gauge. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Register) MustRealSample 

func (reg *Register) MustRealSample(name, help string) *Sample

MustRealSample registers a new Sample. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Register) ServeHTTP 

func (reg *Register) ServeHTTP(resp http.ResponseWriter, req *http.Request)

ServeHTTP provides a sample of each metric as an http.Handler.

func (*Register) WriteText 

func (reg *Register) WriteText(w io.Writer)

WriteText serialises a sample of each metric in a simple text format. All errors returned by Writer are ignored by design. Deprecated: Use WriteTo instead.

func (*Register) WriteTo added in v1.3.0 

func (reg *Register) WriteTo(w io.Writer) (n int64, err error)

WriteTo serialises a sample of each metric in a simple text format as an io.WriterTo.

type Sample 

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

Sample is a specialised metric for measurement captures, as opposed to holding the current value at all times. The precision is enhanced with a timestamp, at the cost of performance degradation. Serialisation omits samples with a zero timestamp. The default/initial value is zero with a zero timestamp. Multiple goroutines may invoke methods on a Sample simultaneously.

Example (Lazy) 
package main

import (
	"net/http"
	"os"
	"time"

	"github.com/pascaldekloe/metrics"
	"github.com/pascaldekloe/metrics/gostat"
)

var (
	LogSize = metrics.MustRealSample("log_bytes", "Size reported by the filesystem.")
	LogIdle = metrics.MustRealSample("log_idle_seconds", "Duration since last change.")
)

func main() {
	// mount exposition point
	http.HandleFunc("/metrics", func(w http.ResponseWriter, r *http.Request) {
		// update standard samples
		gostat.Capture()

		// update custom samples
		log, err := os.Stat("./mission.log")
		if err == nil { // ⚠️ reverse error check
			now := time.Now()
			LogSize.Set(float64(log.Size()), now)
			LogIdle.SetSeconds(now.Sub(log.ModTime()), now)
		}

		// serve serialized
		metrics.ServeHTTP(w, r)
	})
}

Output:

func MustCounterSample 

func MustCounterSample(name, help string) *Sample

MustCounterSample registers a new Sample. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func MustRealSample 

func MustRealSample(name, help string) *Sample

MustRealSample registers a new Sample. Registration panics when name was registered before, or when name doesn't match regular expression [a-zA-Z_:][a-zA-Z0-9_:]*. Help is an optional comment text.

func (*Sample) Get 

func (m *Sample) Get() (value float64, timestamp uint64)

Get returns the current value with its Unix time in milliseconds.

func (*Sample) Labels added in v1.5.0 

func (m *Sample) Labels() map[string]string

Labels returns a new map if m has labels.

func (*Sample) Name added in v1.2.0 

func (m *Sample) Name() string

Name returns the metric identifier.

func (*Sample) Set 

func (m *Sample) Set(value float64, timestamp time.Time)

Set defines the current value.

func (*Sample) SetSeconds added in v1.4.0 

func (m *Sample) SetSeconds(value time.Duration, timestamp time.Time)

SetSeconds defines the current value.

Source Files

View all Source files

Directories

Path Synopsis
Package gostat provides Go statistics to the default registry.
 Package gostat provides Go statistics to the default registry.

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.