Documentation ¶
Index ¶
- Constants
- Variables
- func CollectAndCompare(t *testing.T, vec MetricVec, name string, mtype string, ...)
- func ExponentialBucketRange(min, max float64, count int) []float64
- func ExponentialBuckets(start, factor float64, count int) []float64
- func HandlerFor(metrics *Metrics) http.Handler
- func LinearBuckets(start, width float64, count int) []float64
- func Register(reg prometheus.Registerer, metric prometheus.Collector) error
- func SlicePairsToMap(pairs []string) map[string]string
- type ApexError
- type ApexInternalErrorMetrics
- func (a *ApexInternalErrorMetrics) AlreadyRegistered(name string, t string)
- func (a *ApexInternalErrorMetrics) InvalidMetricName(name string, t string)
- func (a *ApexInternalErrorMetrics) PanicRecovery(name string, t string)
- func (a *ApexInternalErrorMetrics) RegistrationFailed(name string, t string)
- type CounterVec
- type GaugeVec
- func (g *GaugeVec) Add(v float64, lv ...string)
- func (g *GaugeVec) Dec(lv ...string)
- func (g *GaugeVec) Inc(lv ...string)
- func (g *GaugeVec) Name() string
- func (g *GaugeVec) Set(v float64, lv ...string)
- func (g *GaugeVec) Sub(v float64, lv ...string)
- func (g *GaugeVec) Type() MetricType
- func (g *GaugeVec) Vec() prometheus.Collector
- type HistogramOpts
- type HistogramVec
- type Logger
- type MetricType
- type MetricVec
- type Metrics
- func (m *Metrics) CounterAdd(name string, v float64, lv ...string)
- func (m *Metrics) CounterInc(name string, lv ...string)
- func (m *Metrics) GaugeAdd(name string, v float64, lv ...string)
- func (m *Metrics) GaugeDec(name string, lv ...string)
- func (m *Metrics) GaugeInc(name string, lv ...string)
- func (m *Metrics) GaugeSet(name string, v float64, lv ...string)
- func (m *Metrics) GaugeSub(name string, v float64, lv ...string)
- func (m *Metrics) HistogramObserve(name string, v float64, lv ...string)
- func (m *Metrics) HistogramTimer(name string, lv ...string) *Timer
- func (m *Metrics) Start(opts ServerOpts) error
- func (m *Metrics) Stop()
- func (m *Metrics) SummaryObserve(name string, v float64, lv ...string)
- func (m *Metrics) SummaryTimer(name string, lv ...string) *Timer
- func (m *Metrics) WithLabels(labels ...string) *Metrics
- func (m *Metrics) WithPrefix(prefix ...string) *Metrics
- type MetricsOpts
- type Server
- type ServerOpts
- type Store
- type SummaryOpts
- type SummaryVec
- type TLSOpts
- type Timer
Constants ¶
const ( DefaultTimeout = 5 * time.Second DefaultMaxAge time.Duration = 10 * time.Minute DefaultAgeBuckets uint32 = 5 )
const ( // ErrInvalidMetricName is returned when a metric name contains other // characters other than [a-zA-Z_-]. ErrInvalidMetricName = ApexError("Invalid metric name") // ErrRegistrationFailed is returned if prometheus is unable to register // the collector. ErrRegistrationFailed = ApexError("Unable to register collector") // ErrAlreadyRegistered is returned if prometheus has already registered // a collector. ErrAlreadyRegistered = ApexError("metric is already registered") )
const ( // CounterType represents an apex wrapper around the prometheus CounterVec // type. CounterType MetricType = "counter" // GaugeType represents an apex wrapper around the prometheus GaugeVec // type. GaugeType MetricType = "gauge" // SummaryType represents an apex wrapper around the prometheus SummaryVec // type. SummaryType MetricType = "summary" // HistogramType represents an apex wrapper around the prometheus HistogramVec // type. HistogramType MetricType = "histogram" // Defines the metrics help string. This is currently not settable. DefaultHelpString string = "created automagically by apex" )
Variables ¶
var ( // DefBuckets are the default Histogram buckets. DefBuckets = prometheus.DefBuckets //nolint:gochecknoglobals )
var (
DefaultObjectives = map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001} //nolint:gochecknoglobals
)
Functions ¶
func CollectAndCompare ¶ added in v0.2.0
func CollectAndCompare( t *testing.T, vec MetricVec, name string, mtype string, labels map[string]string, value float64, )
CollectAndCompare is a helper function for testing. It creates prometheus strings and compares them with the collector using the CollectAndCompare test utility.
func ExponentialBucketRange ¶
ExponentialBucketsRange creates 'count' buckets, where the lowest bucket is 'min' and the highest bucket is 'max'. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts. (from prometheus docs)
The function panics if 'count' is 0 or negative, if 'min' is 0 or negative.
func ExponentialBuckets ¶
ExponentialBuckets creates 'count' buckets, where the lowest bucket has an upper bound of 'start' and each following bucket's upper bound is 'factor' times the previous bucket's upper bound. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts. (from prometheus docs)
The function panics if 'count' is 0 or negative, if 'start' is 0 or negative, or if 'factor' is less than or equal 1.
func HandlerFor ¶ added in v0.3.0
HandlerFor returns the handler for the metrics registry.
func LinearBuckets ¶
LinearBuckets creates 'count' buckets, each 'width' wide, where the lowest bucket has an upper bound of 'start'. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts. (from prometheus docs)
The function panics if 'count' is zero or negative.
func Register ¶
func Register(reg prometheus.Registerer, metric prometheus.Collector) error
Register registers a collector with prometheus.
func SlicePairsToMap ¶ added in v0.2.0
SlicePairsToMap copies key value pairs to a map.
Types ¶
type ApexInternalErrorMetrics ¶
type ApexInternalErrorMetrics struct {
// contains filtered or unexported fields
}
ApexInternalErrorMetrics provides internal counters for recovered errors from the prometheus collector when PanicOnError is false.
func NewApexInternalErrorMetrics ¶
func NewApexInternalErrorMetrics(prefixes []string, sep rune) *ApexInternalErrorMetrics
NewApexInternalErrorMetrics defines and registers the internal collectors and returns a new ApexInternalErrorMetrics struct.
func (*ApexInternalErrorMetrics) AlreadyRegistered ¶
func (a *ApexInternalErrorMetrics) AlreadyRegistered(name string, t string)
AlreadyRegistered provides a helper function for incrementing the errAlreadyRegistered collector.
func (*ApexInternalErrorMetrics) InvalidMetricName ¶
func (a *ApexInternalErrorMetrics) InvalidMetricName(name string, t string)
InvalidMeticName provides a helper function for incrementing the errInvalidMetricName collector.
func (*ApexInternalErrorMetrics) PanicRecovery ¶
func (a *ApexInternalErrorMetrics) PanicRecovery(name string, t string)
PanicRecovery provides a helper function for incrementing the errPanicRecovery collector.
func (*ApexInternalErrorMetrics) RegistrationFailed ¶
func (a *ApexInternalErrorMetrics) RegistrationFailed(name string, t string)
RegistrationFailed provides a helper function for incrementing the errRegistrationFailed collector.
type CounterVec ¶ added in v0.2.0
type CounterVec struct {
// contains filtered or unexported fields
}
CounterVec is a wrapper around the prometheus CounterVec.
It bundles a set of Counters that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. number of HTTP requests, partitioned by response code and method).
func NewCounterVec ¶ added in v0.2.0
func NewCounterVec(registerer prometheus.Registerer, name string, labels ...string) (*CounterVec, error)
NewCounterVec creates, registers, and returns a new CounterVec.
func (*CounterVec) Add ¶ added in v0.2.0
func (c *CounterVec) Add(v float64, lv ...string)
Add increases the counter by the given float value with the label values in the order that the labels were defined in NewCounterVec.
func (*CounterVec) Inc ¶ added in v0.2.0
func (c *CounterVec) Inc(lv ...string)
Inc increments the counter by 1 with the label values in the order that the labels were defined in NewCounterVec.
func (*CounterVec) Name ¶ added in v0.2.0
func (c *CounterVec) Name() string
Name returns the name of the CounterVec.
func (*CounterVec) Type ¶ added in v0.2.0
func (c *CounterVec) Type() MetricType
Type returns the metric type.
func (*CounterVec) Vec ¶ added in v0.2.0
func (c *CounterVec) Vec() prometheus.Collector
Vec returns the prometheus CounterVec.
type GaugeVec ¶ added in v0.2.0
type GaugeVec struct {
// contains filtered or unexported fields
}
GaugeVec is a wrapper around the prometheus GaugeVec.
It bundles a set of Gauges that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. number of operations queued, partitioned by user and operation type). Create instances with NewGaugeVec.
A gauge represents a numerical value that can be arbitrarily increased or decreased. Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down. Gauges are often used to represent things like disk and memory usage and concurrent requests.
func NewGaugeVec ¶ added in v0.2.0
func NewGaugeVec(registerer prometheus.Registerer, name string, labels ...string) (*GaugeVec, error)
NewGaugeVec creates, registers, and returns a new GaugeVec.
func (*GaugeVec) Add ¶ added in v0.2.0
Add increases the counter by the given float value with the label values in the order that the labels were defined in NewGaugeVec.
func (*GaugeVec) Dec ¶ added in v0.2.0
Dec decrements the Gauge by 1 using the label values in the order that the labels were defined in NewGaugeVec.
func (*GaugeVec) Inc ¶ added in v0.2.0
Inc increments the Gauge by 1 using the label values in the order that the labels were defined in NewGaugeVec.
func (*GaugeVec) Set ¶ added in v0.2.0
Set sets the Gauge to an arbitrary value using the label values in the order that the labels were defined in NewGaugeVec.
func (*GaugeVec) Sub ¶ added in v0.2.0
Add subtracts the counter by the given float value with the label values in the order that the labels were defined in NewGaugeVec.
func (*GaugeVec) Type ¶ added in v0.2.0
func (g *GaugeVec) Type() MetricType
Type returns the metric type.
func (*GaugeVec) Vec ¶ added in v0.2.0
func (g *GaugeVec) Vec() prometheus.Collector
Vec returns the prometheus GaugeVec.
type HistogramOpts ¶
type HistogramOpts struct { // Buckets defines the observation buckets for the histogram. Each float // value is the upper inclusive bound of the bucket with +Inf added implicitly. // the default is Buckets []float64 }
HistogramOpts defines options that are available to the HistogramVec collectors.
type HistogramVec ¶ added in v0.2.0
type HistogramVec struct {
// contains filtered or unexported fields
}
HistogramVec is a wrapper around the prometheus HistogramVec.
It bundles a set of histograms used if you want to count the same thing partitioned by various dimensions.
func NewHistogramVec ¶ added in v0.2.0
func NewHistogramVec(registerer prometheus.Registerer, name string, buckets []float64, labels ...string) (*HistogramVec, error)
NewHistogramVec creates, registers, and returns a new HistogramVec.
func (*HistogramVec) Name ¶ added in v0.2.0
func (g *HistogramVec) Name() string
Name returns the name of the HistogramVec.
func (*HistogramVec) Observe ¶ added in v0.2.0
func (h *HistogramVec) Observe(v float64, lv ...string)
func (*HistogramVec) Timer ¶ added in v0.2.0
func (h *HistogramVec) Timer(lv ...string) *Timer
func (*HistogramVec) Type ¶ added in v0.2.0
func (g *HistogramVec) Type() MetricType
Type returns the metric type.
func (*HistogramVec) Vec ¶ added in v0.2.0
func (g *HistogramVec) Vec() prometheus.Collector
Vec returns the prometheus HistogramVec.
type MetricType ¶ added in v0.2.0
type MetricType string
type MetricVec ¶ added in v0.2.0
type MetricVec interface { Name() string Type() MetricType Vec() prometheus.Collector }
MetricVec defines the interface for apex metrics collector wrappers.
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics provides a wrapper around the prometheus client to automatically register and collect metrics.
func New ¶
func New(opts MetricsOpts) *Metrics
New creates a new Apex metrics store using the options that have been provided.
func (*Metrics) CounterAdd ¶
CounterAdd increments a counter by the provided value.
func (*Metrics) CounterInc ¶
CounterInc increments a counter by 1.
func (*Metrics) HistogramObserve ¶
HistogramObserve adds a single observation to the histogram.
func (*Metrics) HistogramTimer ¶
HistogramTimer returns a Timer helper to measure duration. ObserveDuration is used to measure the time. Example:
timer := m.HistogramTimer("response") defer timer.ObserveDuration()
func (*Metrics) Start ¶
func (m *Metrics) Start(opts ServerOpts) error
Start creates and starts a new HTTP server. It blocks until Stop is called.
func (*Metrics) Stop ¶ added in v0.3.0
func (m *Metrics) Stop()
Stop shuts down the HTTP server gracefully.
func (*Metrics) SummaryObserve ¶
SummaryObserve adds a single observation to the summary.
func (*Metrics) SummaryTimer ¶
SummaryTimer returns a Timer helper to measure duration. ObserveDuration is used to measure the time. Example:
timer := m.SummaryTimer("response") defer timer.ObserveDuration()
func (*Metrics) WithLabels ¶ added in v0.2.0
WithLabels creates a new metric with the provided labels. Example:
metrics = metrics.WithValues("label1", "label2") metrics.GaugeAdd("gauge_with_values", 2.0, "value1", "value2")
func (*Metrics) WithPrefix ¶ added in v0.2.0
WithPrefix appends additional values to the metric name to prefix any new metric names that are added. By default metrics are created without prefixes unless added in MetricOpts. For example:
m := apex.New(apex.MetricsOpts{}) // prefix: "" m.WithPrefix("apex", "example") // prefix: "apex_example" m.CounterInc("a_total") // metric: "apex_example_a_total" n := m.WithPrefix("component") // prefix: "apex_example_component" n.CounterInc("b_total") // metric: "apex_example_component_b_total" m.CounterInc("c_total") // metric: "apex_example_c_total"
type MetricsOpts ¶
type MetricsOpts struct { // ConstantLabels is an array of label/value pairs that will be constant // across all metrics. ConstantLabels []string // HistogramBuckets are buckets used for histogram observation counts. HistogramBuckets []float64 // SummaryOpts defines the options available to summary collectors. SummaryOpts *SummaryOpts // Registry is the prometheus registry that will be used to register // collectors. Registry *prometheus.Registry // Separator is the separator that will be used to join the metric name // components. Separator rune // PanicOnError maintains the default behavior of prometheus to panic on // errors. If this value is set to false, the library attempts to recover // from any panics and emits an internally managed metric // apex_errors_panic_recovery to inform the operator that visibility is // degraded. If set to true the original behavior is maintained and all // errors are treated as panics. PanicOnError bool // Prefix is an array of prefixes that will be appended to the metric name. Prefix []string // Logger takes a value that matches the Logger interface and is used for // log output of errors and other debug information. Logger Logger }
MetricsOpts defines options that are available for the metrics wrapper.
type Server ¶ added in v0.3.0
type Server struct {
// contains filtered or unexported fields
}
func (*Server) Start ¶ added in v0.3.0
func (s *Server) Start(reg *prometheus.Registry) error
Start creates a new http server which listens on the TCP address addr and port.
func (*Server) Stop ¶ added in v0.3.0
func (s *Server) Stop()
Stop closes the stop channel which initiates the shutdown of the HTTP server.
func (*Server) WithLogger ¶ added in v0.3.0
WithLogger defines the logger that will be used with the server.
type ServerOpts ¶ added in v0.3.0
type ServerOpts struct { // BindAddr is the address the promethus collector will listen on for // connections. BindAddr string // BaseContext // Path is the path used by the HTTP server. Path string // Port is the path used by the HTTP server. Port int // TLS TLS *TLSOpts // TerminationGracePeriod is the amount of time that the server will wait // before stopping the HTTP server. This grace period allows any prometheus // scrapers time to scrape. TerminationGracePeriod time.Duration }
type Store ¶ added in v0.2.0
type Store struct { // TODO: part of the issue with the race condition was that we were // setting the metric store value to nil and not revisiting. This will // pretty much address the double register race that caused the nil, but // I need to come back through this and make the check/get more resilient // so I can shrink the footprint of the lock. sync.Mutex // contains filtered or unexported fields }
Store manages all of the prometheus collectors.
type SummaryOpts ¶
type SummaryOpts struct { // Objectives defines the quantile rank estimates with their respective // absolute error. Objectives map[float64]float64 // MaxAge defines the duration for which an observation stays relevant // for the summary. MaxAge time.Duration // AgeBuckets is the number of buckets used to exclude observations that // are older than MaxAge from the summary. AgeBuckets uint32 }
type SummaryVec ¶ added in v0.2.0
type SummaryVec struct {
// contains filtered or unexported fields
}
SummaryVec is a wrapper around the prometheus SummaryVec.
It bundles a set of summaries used if you want to count the same thing partitioned by various dimensions.
func NewSummaryVec ¶ added in v0.2.0
func NewSummaryVec(registerer prometheus.Registerer, name string, opts SummaryOpts, labels ...string) (*SummaryVec, error)
func (*SummaryVec) Name ¶ added in v0.2.0
func (s *SummaryVec) Name() string
Name returns the name of the SummaryVec.
func (*SummaryVec) Observe ¶ added in v0.2.0
func (s *SummaryVec) Observe(v float64, lv ...string)
Observe adds a single observation to the summary.
func (*SummaryVec) Timer ¶ added in v0.2.0
func (s *SummaryVec) Timer(lv ...string) *Timer
Timer returns a new summary timer.
func (*SummaryVec) Type ¶ added in v0.2.0
func (s *SummaryVec) Type() MetricType
Type returns the metric type.
func (*SummaryVec) Vec ¶ added in v0.2.0
func (s *SummaryVec) Vec() prometheus.Collector
Vec returns the prometheus SummaryVec.
type TLSOpts ¶ added in v0.3.0
type TLSOpts struct { // CertFile is the path to the file containing the SSL certificate or // certificate bundle. CertFile string // Keyfile is the path containing the certificate key. KeyFile string // InsecureSkipVerify controls whether a client verifies the server's // certificate chain and host name. InsecureSkipVerify bool // MinVersion contains the minimum TLS version that is acceptable. By // default TLS 1.3 is used. MinVersion uint16 }
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
Timer is a helper type to time functions.
func NewTimer ¶
func NewTimer(collector prometheus.Collector, lv ...string) *Timer
NewTimer creates a new Timer.
func (*Timer) ObserveDuration ¶
func (t *Timer) ObserveDuration()
ObserveDuration records the duration that has passed between the time that the Timer was created.