Documentation ¶
Overview ¶
Package metrics implements Prometheus-compatible metrics for applications.
This package is lightweight alternative to https://github.com/prometheus/client_golang with simpler API and smaller dependencies.
Usage:
- Register the required metrics via New* functions.
- Expose them to `/metrics` page via WritePrometheus.
- Update the registered metrics during application lifetime.
The package has been extracted from https://victoriametrics.com/
Index ¶
- func ExposeMetadata(v bool)
- func InitPush(pushURL string, interval time.Duration, extraLabels string, ...) error
- func InitPushExt(pushURL string, interval time.Duration, extraLabels string, ...) error
- func InitPushExtWithOptions(ctx context.Context, pushURL string, interval time.Duration, ...) error
- func InitPushProcessMetrics(pushURL string, interval time.Duration, extraLabels string) error
- func InitPushWithOptions(ctx context.Context, pushURL string, interval time.Duration, ...) error
- func ListMetricNames() []string
- func PushMetrics(ctx context.Context, pushURL string, pushProcessMetrics bool, ...) error
- func PushMetricsExt(ctx context.Context, pushURL string, writeMetrics func(w io.Writer), ...) error
- func RegisterMetricsWriter(writeMetrics func(w io.Writer))
- func RegisterSet(s *Set)
- func UnregisterAllMetrics()
- func UnregisterMetric(name string) bool
- func UnregisterSet(s *Set, destroySet bool)
- func WriteCounterFloat64(w io.Writer, name string, value float64)
- func WriteCounterUint64(w io.Writer, name string, value uint64)
- func WriteFDMetrics(w io.Writer)
- func WriteGaugeFloat64(w io.Writer, name string, value float64)
- func WriteGaugeUint64(w io.Writer, name string, value uint64)
- func WriteMetadataIfNeeded(w io.Writer, metricName, metricType string)
- func WriteProcessMetrics(w io.Writer)
- func WritePrometheus(w io.Writer, exposeProcessMetrics bool)
- type Counter
- type FloatCounter
- type Gauge
- type Histogram
- type PushOptions
- type Set
- func (s *Set) GetOrCreateCounter(name string) *Counter
- func (s *Set) GetOrCreateFloatCounter(name string) *FloatCounter
- func (s *Set) GetOrCreateGauge(name string, f func() float64) *Gauge
- func (s *Set) GetOrCreateHistogram(name string) *Histogram
- func (s *Set) GetOrCreateSummary(name string) *Summary
- func (s *Set) GetOrCreateSummaryExt(name string, window time.Duration, quantiles []float64) *Summary
- func (s *Set) InitPush(pushURL string, interval time.Duration, extraLabels string) error
- func (s *Set) InitPushWithOptions(ctx context.Context, pushURL string, interval time.Duration, opts *PushOptions) error
- func (s *Set) ListMetricNames() []string
- func (s *Set) NewCounter(name string) *Counter
- func (s *Set) NewFloatCounter(name string) *FloatCounter
- func (s *Set) NewGauge(name string, f func() float64) *Gauge
- func (s *Set) NewHistogram(name string) *Histogram
- func (s *Set) NewSummary(name string) *Summary
- func (s *Set) NewSummaryExt(name string, window time.Duration, quantiles []float64) *Summary
- func (s *Set) PushMetrics(ctx context.Context, pushURL string, opts *PushOptions) error
- func (s *Set) RegisterMetricsWriter(writeMetrics func(w io.Writer))
- func (s *Set) UnregisterAllMetrics()
- func (s *Set) UnregisterMetric(name string) bool
- func (s *Set) WritePrometheus(w io.Writer)
- type Summary
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExposeMetadata ¶ added in v1.28.0
func ExposeMetadata(v bool)
ExposeMetadata allows enabling adding TYPE and HELP metadata to the exposed metrics globally.
It is safe to call this method multiple times. It is allowed to change it in runtime. ExposeMetadata is set to false by default.
Example ¶
package main import ( "bytes" "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { metrics.ExposeMetadata(true) defer metrics.ExposeMetadata(false) s := metrics.NewSet() sc := s.NewCounter("set_counter") sc.Inc() s.NewGauge(`unused_bytes{foo="bar"}`, func() float64 { return 58 }) s.NewGauge(`used_bytes{foo="bar"}`, func() float64 { return 42 }) s.NewGauge(`used_bytes{foo="baz"}`, func() float64 { return 43 }) h := s.NewHistogram(`request_duration_seconds{path="/foo/bar"}`) h.Update(1) h.Update(2) s.NewSummary("response_size_bytes").Update(1) // Dump metrics from s. var bb bytes.Buffer s.WritePrometheus(&bb) fmt.Printf("set metrics:\n%s\n", bb.String()) }
Output: set metrics: # HELP request_duration_seconds # TYPE request_duration_seconds histogram request_duration_seconds_bucket{path="/foo/bar",vmrange="8.799e-01...1.000e+00"} 1 request_duration_seconds_bucket{path="/foo/bar",vmrange="1.896e+00...2.154e+00"} 1 request_duration_seconds_sum{path="/foo/bar"} 3 request_duration_seconds_count{path="/foo/bar"} 2 # HELP response_size_bytes # TYPE response_size_bytes summary response_size_bytes_sum 1 response_size_bytes_count 1 response_size_bytes{quantile="0.5"} 1 response_size_bytes{quantile="0.9"} 1 response_size_bytes{quantile="0.97"} 1 response_size_bytes{quantile="0.99"} 1 response_size_bytes{quantile="1"} 1 # HELP set_counter # TYPE set_counter counter set_counter 1 # HELP unused_bytes # TYPE unused_bytes gauge unused_bytes{foo="bar"} 58 # HELP used_bytes # TYPE used_bytes gauge used_bytes{foo="bar"} 42 used_bytes{foo="baz"} 43
func InitPush ¶ added in v1.19.0
func InitPush(pushURL string, interval time.Duration, extraLabels string, pushProcessMetrics bool) error
InitPush sets up periodic push for globally registered metrics to the given pushURL with the given interval.
extraLabels may contain comma-separated list of `label="value"` labels, which will be added to all the metrics before pushing them to pushURL.
If pushProcessMetrics is set to true, then 'process_*' and `go_*` metrics are also pushed to pushURL.
The metrics are pushed to pushURL in Prometheus text exposition format. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPush multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
func InitPushExt ¶ added in v1.19.1
func InitPushExt(pushURL string, interval time.Duration, extraLabels string, writeMetrics func(w io.Writer)) error
InitPushExt sets up periodic push for metrics obtained by calling writeMetrics with the given interval.
extraLabels may contain comma-separated list of `label="value"` labels, which will be added to all the metrics before pushing them to pushURL.
The writeMetrics callback must write metrics to w in Prometheus text exposition format without timestamps and trailing comments. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPushExt multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
It is OK calling InitPushExt multiple times with different writeMetrics - in this case all the metrics generated by writeMetrics callbacks are written to pushURL.
func InitPushExtWithOptions ¶ added in v1.26.1
func InitPushExtWithOptions(ctx context.Context, pushURL string, interval time.Duration, writeMetrics func(w io.Writer), opts *PushOptions) error
InitPushExtWithOptions sets up periodic push for metrics obtained by calling writeMetrics with the given interval.
The writeMetrics callback must write metrics to w in Prometheus text exposition format without timestamps and trailing comments. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
The periodic push is stopped when the ctx is canceled. It is possible to wait until the background metrics push worker is stopped on a WaitGroup passed via opts.WaitGroup.
opts may contain additional configuration options if non-nil.
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPushExtWithOptions multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
It is OK calling InitPushExtWithOptions multiple times with different writeMetrics - in this case all the metrics generated by writeMetrics callbacks are written to pushURL.
func InitPushProcessMetrics ¶ added in v1.19.0
InitPushProcessMetrics sets up periodic push for 'process_*' metrics to the given pushURL with the given interval.
extraLabels may contain comma-separated list of `label="value"` labels, which will be added to all the metrics before pushing them to pushURL.
The metrics are pushed to pushURL in Prometheus text exposition format. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPushProcessMetrics multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
func InitPushWithOptions ¶ added in v1.26.0
func InitPushWithOptions(ctx context.Context, pushURL string, interval time.Duration, pushProcessMetrics bool, opts *PushOptions) error
InitPushWithOptions sets up periodic push for globally registered metrics to the given pushURL with the given interval.
The periodic push is stopped when ctx is canceled. It is possible to wait until the background metrics push worker is stopped on a WaitGroup passed via opts.WaitGroup.
If pushProcessMetrics is set to true, then 'process_*' and `go_*` metrics are also pushed to pushURL.
opts may contain additional configuration options if non-nil.
The metrics are pushed to pushURL in Prometheus text exposition format. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPushWithOptions multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
func ListMetricNames ¶ added in v1.19.1
func ListMetricNames() []string
ListMetricNames returns sorted list of all the metric names from default set.
func PushMetrics ¶ added in v1.27.0
func PushMetrics(ctx context.Context, pushURL string, pushProcessMetrics bool, opts *PushOptions) error
PushMetrics pushes globally registered metrics to pushURL.
If pushProcessMetrics is set to true, then 'process_*' and `go_*` metrics are also pushed to pushURL.
opts may contain additional configuration options if non-nil.
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
func PushMetricsExt ¶ added in v1.27.0
func PushMetricsExt(ctx context.Context, pushURL string, writeMetrics func(w io.Writer), opts *PushOptions) error
PushMetricsExt pushes metrics generated by wirteMetrics to pushURL.
The writeMetrics callback must write metrics to w in Prometheus text exposition format without timestamps and trailing comments. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
opts may contain additional configuration options if non-nil.
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
func RegisterMetricsWriter ¶ added in v1.31.0
RegisterMetricsWriter registers writeMetrics callback for including metrics in the output generated by WritePrometheus.
The writeMetrics callback must write metrics to w in Prometheus text exposition format without timestamps and trailing comments. The last line generated by writeMetrics must end with \n. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is OK to register multiple writeMetrics callbacks - all of them will be called sequentially for gererating the output at WritePrometheus.
func RegisterSet ¶ added in v1.22.0
func RegisterSet(s *Set)
RegisterSet registers the given set s for metrics export via global WritePrometheus() call.
See also UnregisterSet.
func UnregisterAllMetrics ¶ added in v1.23.0
func UnregisterAllMetrics()
UnregisterAllMetrics unregisters all the metrics from default set.
It also unregisters writeMetrics callbacks passed to RegisterMetricsWriter.
func UnregisterMetric ¶ added in v1.12.1
UnregisterMetric removes metric with the given name from default set.
See also UnregisterAllMetrics.
func UnregisterSet ¶ added in v1.22.0
UnregisterSet stops exporting metrics for the given s via global WritePrometheus() call.
If destroySet is set to true, then s.UnregisterAllMetrics() is called on s after unregistering it, so s becomes destroyed. Otherwise the s can be registered again in the set by passing it to RegisterSet().
func WriteCounterFloat64 ¶ added in v1.28.0
WriteCounterFloat64 writes counter metric with the given name and value to w in Prometheus text exposition format.
func WriteCounterUint64 ¶ added in v1.28.0
WriteCounterUint64 writes counter metric with the given name and value to w in Prometheus text exposition format.
func WriteFDMetrics ¶ added in v1.13.0
WriteFDMetrics writes `process_max_fds` and `process_open_fds` metrics to w.
func WriteGaugeFloat64 ¶ added in v1.28.0
WriteGaugeFloat64 writes gauge metric with the given name and value to w in Prometheus text exposition format.
func WriteGaugeUint64 ¶ added in v1.28.0
WriteGaugeUint64 writes gauge metric with the given name and value to w in Prometheus text exposition format.
func WriteMetadataIfNeeded ¶ added in v1.28.2
WriteMetadataIfNeeded writes HELP and TYPE metadata for the given metricName and metricType if this is globally enabled via ExposeMetadata().
If the metadata exposition isn't enabled, then this function is no-op.
func WriteProcessMetrics ¶ added in v1.11.0
WriteProcessMetrics writes additional process metrics in Prometheus format to w.
The following `go_*` and `process_*` metrics are exposed for the currently running process. Below is a short description for the exposed `process_*` metrics:
process_cpu_seconds_system_total - CPU time spent in syscalls
process_cpu_seconds_user_total - CPU time spent in userspace
process_cpu_seconds_total - CPU time spent by the process
process_major_pagefaults_total - page faults resulted in disk IO
process_minor_pagefaults_total - page faults resolved without disk IO
process_resident_memory_bytes - recently accessed memory (aka RSS or resident memory)
process_resident_memory_peak_bytes - the maximum RSS memory usage
process_resident_memory_anon_bytes - RSS for memory-mapped files
process_resident_memory_file_bytes - RSS for memory allocated by the process
process_resident_memory_shared_bytes - RSS for memory shared between multiple processes
process_virtual_memory_bytes - virtual memory usage
process_virtual_memory_peak_bytes - the maximum virtual memory usage
process_num_threads - the number of threads
process_start_time_seconds - process start time as unix timestamp
process_io_read_bytes_total - the number of bytes read via syscalls
process_io_written_bytes_total - the number of bytes written via syscalls
process_io_read_syscalls_total - the number of read syscalls
process_io_write_syscalls_total - the number of write syscalls
process_io_storage_read_bytes_total - the number of bytes actually read from disk
process_io_storage_written_bytes_total - the number of bytes actually written to disk
go_sched_latencies_seconds - time spent by goroutines in ready state before they start execution
go_mutex_wait_seconds_total - summary time spent by all the goroutines while waiting for locked mutex
go_gc_mark_assist_cpu_seconds_total - summary CPU time spent by goroutines in GC mark assist state
go_gc_cpu_seconds_total - summary time spent in GC
go_gc_pauses_seconds - duration of GC pauses
go_scavenge_cpu_seconds_total - CPU time spent on returning the memory to OS
go_memlimit_bytes - the GOMEMLIMIT env var value
go_memstats_alloc_bytes - memory usage for Go objects in the heap
go_memstats_alloc_bytes_total - the cumulative counter for total size of allocated Go objects
go_memstats_buck_hash_sys_bytes - bytes of memory in profiling bucket hash tables
go_memstats_frees_total - the cumulative counter for number of freed Go objects
go_memstats_gc_cpu_fraction - the fraction of CPU spent in Go garbage collector
go_memstats_gc_sys_bytes - the size of Go garbage collector metadata
go_memstats_heap_alloc_bytes - the same as go_memstats_alloc_bytes
go_memstats_heap_idle_bytes - idle memory ready for new Go object allocations
go_memstats_heap_inuse_bytes - bytes in in-use spans
go_memstats_heap_objects - the number of Go objects in the heap
go_memstats_heap_released_bytes - bytes of physical memory returned to the OS
go_memstats_heap_sys_bytes - memory requested for Go objects from the OS
go_memstats_last_gc_time_seconds - unix timestamp the last garbage collection finished
go_memstats_lookups_total - the number of pointer lookups performed by the runtime
go_memstats_mallocs_total - the number of allocations for Go objects
go_memstats_mcache_inuse_bytes - bytes of allocated mcache structures
go_memstats_mcache_sys_bytes - bytes of memory obtained from the OS for mcache structures
go_memstats_mspan_inuse_bytes - bytes of allocated mspan structures
go_memstats_mspan_sys_bytes - bytes of memory obtained from the OS for mspan structures
go_memstats_next_gc_bytes - the target heap size when the next garbage collection should start
go_memstats_other_sys_bytes - bytes of memory in miscellaneous off-heap runtime allocations
go_memstats_stack_inuse_bytes - memory used for goroutine stacks
go_memstats_stack_sys_bytes - memory requested fromthe OS for goroutine stacks
go_memstats_sys_bytes - memory requested by Go runtime from the OS
go_cgo_calls_count - the total number of CGO calls
go_cpu_count - the number of CPU cores on the host where the app runs
The WriteProcessMetrics func is usually called in combination with writing Set metrics inside "/metrics" handler:
http.HandleFunc("/metrics", func(w http.ResponseWriter, req *http.Request) { mySet.WritePrometheus(w) metrics.WriteProcessMetrics(w) })
See also WriteFDMetrics.
func WritePrometheus ¶
WritePrometheus writes all the metrics in Prometheus format from the default set, all the added sets and metrics writers to w.
Additional sets can be registered via RegisterSet() call. Additional metric writers can be registered via RegisterMetricsWriter() call.
If exposeProcessMetrics is true, then various `go_*` and `process_*` metrics are exposed for the current process.
The WritePrometheus func is usually called inside "/metrics" handler:
http.HandleFunc("/metrics", func(w http.ResponseWriter, req *http.Request) { metrics.WritePrometheus(w, true) })
Example ¶
package main import ( "net/http" "github.com/VictoriaMetrics/metrics" ) func main() { // Export all the registered metrics in Prometheus format at `/metrics` http path. http.HandleFunc("/metrics", func(w http.ResponseWriter, req *http.Request) { metrics.WritePrometheus(w, true) }) }
Output:
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
Counter is a counter.
It may be used as a gauge if Dec and Set are called.
Example ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { // Define a counter in global scope. var c = metrics.NewCounter(`metric_total{label1="value1", label2="value2"}`) // Increment the counter when needed. for i := 0; i < 10; i++ { c.Inc() } n := c.Get() fmt.Println(n) }
Output: 10
Example (Vec) ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { for i := 0; i < 3; i++ { // Dynamically construct metric name and pass it to GetOrCreateCounter. name := fmt.Sprintf(`metric_total{label1=%q, label2="%d"}`, "value1", i) metrics.GetOrCreateCounter(name).Add(i + 1) } // Read counter values. for i := 0; i < 3; i++ { name := fmt.Sprintf(`metric_total{label1=%q, label2="%d"}`, "value1", i) n := metrics.GetOrCreateCounter(name).Get() fmt.Println(n) } }
Output: 1 2 3
func GetOrCreateCounter ¶ added in v1.2.0
GetOrCreateCounter returns registered counter with the given name or creates new counter if the registry doesn't contain counter with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned counter is safe to use from concurrent goroutines.
Performance tip: prefer NewCounter instead of GetOrCreateCounter.
func NewCounter ¶
NewCounter registers and returns new counter with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned counter is safe to use from concurrent goroutines.
type FloatCounter ¶ added in v1.10.0
type FloatCounter struct {
// contains filtered or unexported fields
}
FloatCounter is a float64 counter guarded by RWmutex.
It may be used as a gauge if Add and Sub are called.
Example ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { // Define a float64 counter in global scope. var fc = metrics.NewFloatCounter(`float_metric_total{label1="value1", label2="value2"}`) // Add to the counter when needed. for i := 0; i < 10; i++ { fc.Add(1.01) } n := fc.Get() fmt.Println(n) }
Output: 10.1
Example (Vec) ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { for i := 0; i < 3; i++ { // Dynamically construct metric name and pass it to GetOrCreateFloatCounter. name := fmt.Sprintf(`float_metric_total{label1=%q, label2="%d"}`, "value1", i) metrics.GetOrCreateFloatCounter(name).Add(float64(i) + 1.01) } // Read counter values. for i := 0; i < 3; i++ { name := fmt.Sprintf(`float_metric_total{label1=%q, label2="%d"}`, "value1", i) n := metrics.GetOrCreateFloatCounter(name).Get() fmt.Println(n) } }
Output: 1.01 2.01 3.01
func GetOrCreateFloatCounter ¶ added in v1.10.0
func GetOrCreateFloatCounter(name string) *FloatCounter
GetOrCreateFloatCounter returns registered FloatCounter with the given name or creates new FloatCounter if the registry doesn't contain FloatCounter with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned FloatCounter is safe to use from concurrent goroutines.
Performance tip: prefer NewFloatCounter instead of GetOrCreateFloatCounter.
func NewFloatCounter ¶ added in v1.10.0
func NewFloatCounter(name string) *FloatCounter
NewFloatCounter registers and returns new counter of float64 type with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned counter is safe to use from concurrent goroutines.
func (*FloatCounter) Add ¶ added in v1.10.0
func (fc *FloatCounter) Add(n float64)
Add adds n to fc.
func (*FloatCounter) Get ¶ added in v1.10.0
func (fc *FloatCounter) Get() float64
Get returns the current value for fc.
func (*FloatCounter) Set ¶ added in v1.10.0
func (fc *FloatCounter) Set(n float64)
Set sets fc value to n.
func (*FloatCounter) Sub ¶ added in v1.10.0
func (fc *FloatCounter) Sub(n float64)
Sub substracts n from fc.
type Gauge ¶ added in v1.1.0
type Gauge struct {
// contains filtered or unexported fields
}
Gauge is a float64 gauge.
Example ¶
package main import ( "fmt" "runtime" "github.com/VictoriaMetrics/metrics" ) func main() { // Define a gauge exporting the number of goroutines. var g = metrics.NewGauge(`goroutines_count`, func() float64 { return float64(runtime.NumGoroutine()) }) // Obtain gauge value. fmt.Println(g.Get()) }
Output:
Example (Vec) ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { for i := 0; i < 3; i++ { // Dynamically construct metric name and pass it to GetOrCreateGauge. name := fmt.Sprintf(`metric{label1=%q, label2="%d"}`, "value1", i) iLocal := i metrics.GetOrCreateGauge(name, func() float64 { return float64(iLocal + 1) }) } // Read counter values. for i := 0; i < 3; i++ { name := fmt.Sprintf(`metric{label1=%q, label2="%d"}`, "value1", i) n := metrics.GetOrCreateGauge(name, func() float64 { return 0 }).Get() fmt.Println(n) } }
Output: 1 2 3
func GetOrCreateGauge ¶ added in v1.4.0
GetOrCreateGauge returns registered gauge with the given name or creates new gauge if the registry doesn't contain gauge with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned gauge is safe to use from concurrent goroutines.
Performance tip: prefer NewGauge instead of GetOrCreateGauge.
See also FloatCounter for working with floating-point values.
func NewGauge ¶
NewGauge registers and returns gauge with the given name, which calls f to obtain gauge value.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
f must be safe for concurrent calls. if f is nil, then it is expected that the gauge value is changed via Set(), Inc(), Dec() and Add() calls.
The returned gauge is safe to use from concurrent goroutines.
See also FloatCounter for working with floating-point values.
func (*Gauge) Add ¶ added in v1.32.0
Add adds fAdd to g. fAdd may be positive and negative.
The g must be created with nil callback in order to be able to call this function.
func (*Gauge) Dec ¶ added in v1.32.0
func (g *Gauge) Dec()
Dec decrements g by 1.
The g must be created with nil callback in order to be able to call this function.
type Histogram ¶ added in v1.8.0
type Histogram struct {
// contains filtered or unexported fields
}
Histogram is a histogram for non-negative values with automatically created buckets.
See https://medium.com/@valyala/improving-histogram-usability-for-prometheus-and-grafana-bc7e5df0e350
Each bucket contains a counter for values in the given range. Each non-empty bucket is exposed via the following metric:
<metric_name>_bucket{<optional_tags>,vmrange="<start>...<end>"} <counter>
Where:
- <metric_name> is the metric name passed to NewHistogram
- <optional_tags> is optional tags for the <metric_name>, which are passed to NewHistogram
- <start> and <end> - start and end values for the given bucket
- <counter> - the number of hits to the given bucket during Update* calls
Histogram buckets can be converted to Prometheus-like buckets with `le` labels with `prometheus_buckets(<metric_name>_bucket)` function from PromQL extensions in VictoriaMetrics. (see https://docs.victoriametrics.com/metricsql/ ):
prometheus_buckets(request_duration_bucket)
Time series produced by the Histogram have better compression ratio comparing to Prometheus histogram buckets with `le` labels, since they don't include counters for all the previous buckets.
Zero histogram is usable.
Example ¶
// Define a histogram in global scope. var h = metrics.NewHistogram(`request_duration_seconds{path="/foo/bar"}`) // Update the histogram with the duration of processRequest call. startTime := time.Now() processRequest() h.UpdateDuration(startTime)
Output:
Example (Vec) ¶
for i := 0; i < 3; i++ { // Dynamically construct metric name and pass it to GetOrCreateHistogram. name := fmt.Sprintf(`response_size_bytes{path=%q}`, "/foo/bar") response := processRequest() metrics.GetOrCreateHistogram(name).Update(float64(len(response))) }
Output:
func GetOrCreateHistogram ¶ added in v1.8.0
GetOrCreateHistogram returns registered histogram with the given name or creates new histogram if the registry doesn't contain histogram with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned histogram is safe to use from concurrent goroutines.
Performance tip: prefer NewHistogram instead of GetOrCreateHistogram.
func NewHistogram ¶ added in v1.8.0
NewHistogram creates and returns new histogram with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned histogram is safe to use from concurrent goroutines.
func (*Histogram) Reset ¶ added in v1.9.0
func (h *Histogram) Reset()
Reset resets the given histogram.
func (*Histogram) Update ¶ added in v1.8.0
Update updates h with v.
Negative values and NaNs are ignored.
func (*Histogram) UpdateDuration ¶ added in v1.8.0
UpdateDuration updates request duration based on the given startTime.
func (*Histogram) VisitNonZeroBuckets ¶ added in v1.8.3
VisitNonZeroBuckets calls f for all buckets with non-zero counters.
vmrange contains "<start>...<end>" string with bucket bounds. The lower bound isn't included in the bucket, while the upper bound is included. This is required to be compatible with Prometheus-style histogram buckets with `le` (less or equal) labels.
type PushOptions ¶ added in v1.26.0
type PushOptions struct { // ExtraLabels is an optional comma-separated list of `label="value"` labels, which must be added to all the metrics before pushing them to pushURL. ExtraLabels string // Headers is an optional list of HTTP headers to add to every push request to pushURL. // // Every item in the list must have the form `Header: value`. For example, `Authorization: Custom my-top-secret`. Headers []string // Whether to disable HTTP request body compression before sending the metrics to pushURL. // // By default the compression is enabled. DisableCompression bool // Method is HTTP request method to use when pushing metrics to pushURL. // // By default the Method is GET. Method string // Optional WaitGroup for waiting until all the push workers created with this WaitGroup are stopped. WaitGroup *sync.WaitGroup }
PushOptions is the list of options, which may be applied to InitPushWithOptions().
type Set ¶ added in v1.5.0
type Set struct {
// contains filtered or unexported fields
}
Set is a set of metrics.
Metrics belonging to a set are exported separately from global metrics.
Set.WritePrometheus must be called for exporting metrics from the set.
Example ¶
package main import ( "bytes" "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { // Create a set with a counter s := metrics.NewSet() sc := s.NewCounter("set_counter") sc.Inc() s.NewGauge(`set_gauge{foo="bar"}`, func() float64 { return 42 }) // Dump metrics from s. var bb bytes.Buffer s.WritePrometheus(&bb) fmt.Printf("set metrics:\n%s\n", bb.String()) }
Output: set metrics: set_counter 1 set_gauge{foo="bar"} 42
func GetDefaultSet ¶ added in v1.23.0
func GetDefaultSet() *Set
GetDefaultSet returns the default metrics set.
func NewSet ¶ added in v1.5.0
func NewSet() *Set
NewSet creates new set of metrics.
Pass the set to RegisterSet() function in order to export its metrics via global WritePrometheus() call.
func (*Set) GetOrCreateCounter ¶ added in v1.5.0
GetOrCreateCounter returns registered counter in s with the given name or creates new counter if s doesn't contain counter with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned counter is safe to use from concurrent goroutines.
Performance tip: prefer NewCounter instead of GetOrCreateCounter.
func (*Set) GetOrCreateFloatCounter ¶ added in v1.10.0
func (s *Set) GetOrCreateFloatCounter(name string) *FloatCounter
GetOrCreateFloatCounter returns registered FloatCounter in s with the given name or creates new FloatCounter if s doesn't contain FloatCounter with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned FloatCounter is safe to use from concurrent goroutines.
Performance tip: prefer NewFloatCounter instead of GetOrCreateFloatCounter.
func (*Set) GetOrCreateGauge ¶ added in v1.5.0
GetOrCreateGauge returns registered gauge with the given name in s or creates new gauge if s doesn't contain gauge with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned gauge is safe to use from concurrent goroutines.
Performance tip: prefer NewGauge instead of GetOrCreateGauge.
func (*Set) GetOrCreateHistogram ¶ added in v1.8.0
GetOrCreateHistogram returns registered histogram in s with the given name or creates new histogram if s doesn't contain histogram with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned histogram is safe to use from concurrent goroutines.
Performance tip: prefer NewHistogram instead of GetOrCreateHistogram.
func (*Set) GetOrCreateSummary ¶ added in v1.5.0
GetOrCreateSummary returns registered summary with the given name in s or creates new summary if s doesn't contain summary with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
Performance tip: prefer NewSummary instead of GetOrCreateSummary.
func (*Set) GetOrCreateSummaryExt ¶ added in v1.5.0
func (s *Set) GetOrCreateSummaryExt(name string, window time.Duration, quantiles []float64) *Summary
GetOrCreateSummaryExt returns registered summary with the given name, window and quantiles in s or creates new summary if s doesn't contain summary with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
Performance tip: prefer NewSummaryExt instead of GetOrCreateSummaryExt.
func (*Set) InitPush ¶ added in v1.19.0
InitPush sets up periodic push for metrics from s to the given pushURL with the given interval.
extraLabels may contain comma-separated list of `label="value"` labels, which will be added to all the metrics before pushing them to pushURL.
The metrics are pushed to pushURL in Prometheus text exposition format. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPush multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
func (*Set) InitPushWithOptions ¶ added in v1.26.0
func (s *Set) InitPushWithOptions(ctx context.Context, pushURL string, interval time.Duration, opts *PushOptions) error
InitPushWithOptions sets up periodic push for metrics from s to the given pushURL with the given interval.
The periodic push is stopped when the ctx is canceled. It is possible to wait until the background metrics push worker is stopped on a WaitGroup passed via opts.WaitGroup.
opts may contain additional configuration options if non-nil.
The metrics are pushed to pushURL in Prometheus text exposition format. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
It is OK calling InitPushWithOptions multiple times with different pushURL - in this case metrics are pushed to all the provided pushURL urls.
func (*Set) ListMetricNames ¶ added in v1.11.0
ListMetricNames returns sorted list of all the metrics in s.
The returned list doesn't include metrics generated by metricsWriter passed to RegisterMetricsWriter.
func (*Set) NewCounter ¶ added in v1.5.0
NewCounter registers and returns new counter with the given name in the s.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned counter is safe to use from concurrent goroutines.
func (*Set) NewFloatCounter ¶ added in v1.10.0
func (s *Set) NewFloatCounter(name string) *FloatCounter
NewFloatCounter registers and returns new FloatCounter with the given name in the s.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned FloatCounter is safe to use from concurrent goroutines.
func (*Set) NewGauge ¶ added in v1.5.0
NewGauge registers and returns gauge with the given name in s, which calls f to obtain gauge value.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
f must be safe for concurrent calls.
The returned gauge is safe to use from concurrent goroutines.
func (*Set) NewHistogram ¶ added in v1.8.0
NewHistogram creates and returns new histogram in s with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned histogram is safe to use from concurrent goroutines.
func (*Set) NewSummary ¶ added in v1.5.0
NewSummary creates and returns new summary with the given name in s.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
func (*Set) NewSummaryExt ¶ added in v1.5.0
NewSummaryExt creates and returns new summary in s with the given name, window and quantiles.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
func (*Set) PushMetrics ¶ added in v1.27.0
PushMetrics pushes s metrics to pushURL.
opts may contain additional configuration options if non-nil.
It is recommended pushing metrics to /api/v1/import/prometheus endpoint according to https://docs.victoriametrics.com/#how-to-import-data-in-prometheus-exposition-format
func (*Set) RegisterMetricsWriter ¶ added in v1.31.0
RegisterMetricsWriter registers writeMetrics callback for including metrics in the output generated by s.WritePrometheus.
The writeMetrics callback must write metrics to w in Prometheus text exposition format without timestamps and trailing comments. The last line generated by writeMetrics must end with \n. See https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format
It is OK to reguster multiple writeMetrics callbacks - all of them will be called sequentially for gererating the output at s.WritePrometheus.
func (*Set) UnregisterAllMetrics ¶ added in v1.23.0
func (s *Set) UnregisterAllMetrics()
UnregisterAllMetrics de-registers all metrics registered in s.
It also de-registers writeMetrics callbacks passed to RegisterMetricsWriter.
func (*Set) UnregisterMetric ¶ added in v1.11.0
UnregisterMetric removes metric with the given name from s.
True is returned if the metric has been removed. False is returned if the given metric is missing in s.
func (*Set) WritePrometheus ¶ added in v1.5.0
WritePrometheus writes all the metrics from s to w in Prometheus format.
type Summary ¶
type Summary struct {
// contains filtered or unexported fields
}
Summary implements summary.
Example ¶
package main import ( "time" "github.com/VictoriaMetrics/metrics" ) func main() { // Define a summary in global scope. var s = metrics.NewSummary(`request_duration_seconds{path="/foo/bar"}`) // Update the summary with the duration of processRequest call. startTime := time.Now() processRequest() s.UpdateDuration(startTime) } func processRequest() string { return "foobar" }
Output:
Example (Vec) ¶
package main import ( "fmt" "github.com/VictoriaMetrics/metrics" ) func main() { for i := 0; i < 3; i++ { // Dynamically construct metric name and pass it to GetOrCreateSummary. name := fmt.Sprintf(`response_size_bytes{path=%q}`, "/foo/bar") response := processRequest() metrics.GetOrCreateSummary(name).Update(float64(len(response))) } } func processRequest() string { return "foobar" }
Output:
func GetOrCreateSummary ¶ added in v1.3.0
GetOrCreateSummary returns registered summary with the given name or creates new summary if the registry doesn't contain summary with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
Performance tip: prefer NewSummary instead of GetOrCreateSummary.
func GetOrCreateSummaryExt ¶ added in v1.3.0
GetOrCreateSummaryExt returns registered summary with the given name, window and quantiles or creates new summary if the registry doesn't contain summary with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
Performance tip: prefer NewSummaryExt instead of GetOrCreateSummaryExt.
func NewSummary ¶
NewSummary creates and returns new summary with the given name.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
func NewSummaryExt ¶
NewSummaryExt creates and returns new summary with the given name, window and quantiles.
name must be valid Prometheus-compatible metric with possible labels. For instance,
- foo
- foo{bar="baz"}
- foo{bar="baz",aaa="b"}
The returned summary is safe to use from concurrent goroutines.
func (*Summary) UpdateDuration ¶
UpdateDuration updates request duration based on the given startTime.