metrics: fix docstrings (#29279)

pull/29295/head
georgehao 8 months ago committed by GitHub
parent 45b88abbde
commit 0ceac8d00e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
  1. 4
      metrics/json.go
  2. 38
      metrics/registry.go
  3. 8
      metrics/timer.go

@ -26,6 +26,6 @@ func WriteJSONOnce(r Registry, w io.Writer) {
json.NewEncoder(w).Encode(r) json.NewEncoder(w).Encode(r)
} }
func (p *PrefixedRegistry) MarshalJSON() ([]byte, error) { func (r *PrefixedRegistry) MarshalJSON() ([]byte, error) {
return json.Marshal(p.GetAll()) return json.Marshal(r.GetAll())
} }

@ -8,8 +8,8 @@ import (
"sync" "sync"
) )
// DuplicateMetric is the error returned by Registry.Register when a metric // DuplicateMetric is the error returned by Registry. Register when a metric
// already exists. If you mean to Register that metric you must first // already exists. If you mean to Register that metric you must first
// Unregister the existing metric. // Unregister the existing metric.
type DuplicateMetric string type DuplicateMetric string
@ -20,11 +20,11 @@ func (err DuplicateMetric) Error() string {
// A Registry holds references to a set of metrics by name and can iterate // A Registry holds references to a set of metrics by name and can iterate
// over them, calling callback functions provided by the user. // over them, calling callback functions provided by the user.
// //
// This is an interface so as to encourage other structs to implement // This is an interface to encourage other structs to implement
// the Registry API as appropriate. // the Registry API as appropriate.
type Registry interface { type Registry interface {
// Call the given function for each registered metric. // Each call the given function for each registered metric.
Each(func(string, interface{})) Each(func(string, interface{}))
// Get the metric by the given name or nil if none is registered. // Get the metric by the given name or nil if none is registered.
@ -33,7 +33,7 @@ type Registry interface {
// GetAll metrics in the Registry. // GetAll metrics in the Registry.
GetAll() map[string]map[string]interface{} GetAll() map[string]map[string]interface{}
// Gets an existing metric or registers the given one. // GetOrRegister gets an existing metric or registers the given one.
// The interface can be the metric to register if not found in registry, // The interface can be the metric to register if not found in registry,
// or a function returning the metric for lazy instantiation. // or a function returning the metric for lazy instantiation.
GetOrRegister(string, interface{}) interface{} GetOrRegister(string, interface{}) interface{}
@ -41,7 +41,7 @@ type Registry interface {
// Register the given metric under the given name. // Register the given metric under the given name.
Register(string, interface{}) error Register(string, interface{}) error
// Run all registered healthchecks. // RunHealthchecks run all registered healthchecks.
RunHealthchecks() RunHealthchecks()
// Unregister the metric with the given name. // Unregister the metric with the given name.
@ -52,7 +52,7 @@ type orderedRegistry struct {
StandardRegistry StandardRegistry
} }
// Call the given function for each registered metric. // Each call the given function for each registered metric.
func (r *orderedRegistry) Each(f func(string, interface{})) { func (r *orderedRegistry) Each(f func(string, interface{})) {
var names []string var names []string
reg := r.registered() reg := r.registered()
@ -75,13 +75,13 @@ func NewOrderedRegistry() Registry {
return new(orderedRegistry) return new(orderedRegistry)
} }
// The standard implementation of a Registry uses sync.map // StandardRegistry the standard implementation of a Registry uses sync.map
// of names to metrics. // of names to metrics.
type StandardRegistry struct { type StandardRegistry struct {
metrics sync.Map metrics sync.Map
} }
// Call the given function for each registered metric. // Each call the given function for each registered metric.
func (r *StandardRegistry) Each(f func(string, interface{})) { func (r *StandardRegistry) Each(f func(string, interface{})) {
for name, i := range r.registered() { for name, i := range r.registered() {
f(name, i) f(name, i)
@ -94,7 +94,7 @@ func (r *StandardRegistry) Get(name string) interface{} {
return item return item
} }
// Gets an existing metric or creates and registers a new one. Threadsafe // GetOrRegister gets an existing metric or creates and registers a new one. Threadsafe
// alternative to calling Get and Register on failure. // alternative to calling Get and Register on failure.
// The interface can be the metric to register if not found in registry, // The interface can be the metric to register if not found in registry,
// or a function returning the metric for lazy instantiation. // or a function returning the metric for lazy instantiation.
@ -114,7 +114,7 @@ func (r *StandardRegistry) GetOrRegister(name string, i interface{}) interface{}
return item return item
} }
// Register the given metric under the given name. Returns a DuplicateMetric // Register the given metric under the given name. Returns a DuplicateMetric
// if a metric by the given name is already registered. // if a metric by the given name is already registered.
func (r *StandardRegistry) Register(name string, i interface{}) error { func (r *StandardRegistry) Register(name string, i interface{}) error {
// fast path // fast path
@ -133,7 +133,7 @@ func (r *StandardRegistry) Register(name string, i interface{}) error {
return nil return nil
} }
// Run all registered healthchecks. // RunHealthchecks run all registered healthchecks.
func (r *StandardRegistry) RunHealthchecks() { func (r *StandardRegistry) RunHealthchecks() {
r.metrics.Range(func(key, value any) bool { r.metrics.Range(func(key, value any) bool {
if h, ok := value.(Healthcheck); ok { if h, ok := value.(Healthcheck); ok {
@ -263,7 +263,7 @@ func NewPrefixedChildRegistry(parent Registry, prefix string) Registry {
} }
} }
// Call the given function for each registered metric. // Each call the given function for each registered metric.
func (r *PrefixedRegistry) Each(fn func(string, interface{})) { func (r *PrefixedRegistry) Each(fn func(string, interface{})) {
wrappedFn := func(prefix string) func(string, interface{}) { wrappedFn := func(prefix string) func(string, interface{}) {
return func(name string, iface interface{}) { return func(name string, iface interface{}) {
@ -295,7 +295,7 @@ func (r *PrefixedRegistry) Get(name string) interface{} {
return r.underlying.Get(realName) return r.underlying.Get(realName)
} }
// Gets an existing metric or registers the given one. // GetOrRegister gets an existing metric or registers the given one.
// The interface can be the metric to register if not found in registry, // The interface can be the metric to register if not found in registry,
// or a function returning the metric for lazy instantiation. // or a function returning the metric for lazy instantiation.
func (r *PrefixedRegistry) GetOrRegister(name string, metric interface{}) interface{} { func (r *PrefixedRegistry) GetOrRegister(name string, metric interface{}) interface{} {
@ -309,7 +309,7 @@ func (r *PrefixedRegistry) Register(name string, metric interface{}) error {
return r.underlying.Register(realName, metric) return r.underlying.Register(realName, metric)
} }
// Run all registered healthchecks. // RunHealthchecks run all registered healthchecks.
func (r *PrefixedRegistry) RunHealthchecks() { func (r *PrefixedRegistry) RunHealthchecks() {
r.underlying.RunHealthchecks() r.underlying.RunHealthchecks()
} }
@ -331,7 +331,7 @@ var (
AccountingRegistry = NewRegistry() // registry used in swarm AccountingRegistry = NewRegistry() // registry used in swarm
) )
// Call the given function for each registered metric. // Each call the given function for each registered metric.
func Each(f func(string, interface{})) { func Each(f func(string, interface{})) {
DefaultRegistry.Each(f) DefaultRegistry.Each(f)
} }
@ -341,7 +341,7 @@ func Get(name string) interface{} {
return DefaultRegistry.Get(name) return DefaultRegistry.Get(name)
} }
// Gets an existing metric or creates and registers a new one. Threadsafe // GetOrRegister gets an existing metric or creates and registers a new one. Threadsafe
// alternative to calling Get and Register on failure. // alternative to calling Get and Register on failure.
func GetOrRegister(name string, i interface{}) interface{} { func GetOrRegister(name string, i interface{}) interface{} {
return DefaultRegistry.GetOrRegister(name, i) return DefaultRegistry.GetOrRegister(name, i)
@ -353,7 +353,7 @@ func Register(name string, i interface{}) error {
return DefaultRegistry.Register(name, i) return DefaultRegistry.Register(name, i)
} }
// Register the given metric under the given name. Panics if a metric by the // MustRegister register the given metric under the given name. Panics if a metric by the
// given name is already registered. // given name is already registered.
func MustRegister(name string, i interface{}) { func MustRegister(name string, i interface{}) {
if err := Register(name, i); err != nil { if err := Register(name, i); err != nil {
@ -361,7 +361,7 @@ func MustRegister(name string, i interface{}) {
} }
} }
// Run all registered healthchecks. // RunHealthchecks run all registered healthchecks.
func RunHealthchecks() { func RunHealthchecks() {
DefaultRegistry.RunHealthchecks() DefaultRegistry.RunHealthchecks()
} }

@ -10,7 +10,7 @@ type TimerSnapshot interface {
MeterSnapshot MeterSnapshot
} }
// Timers capture the duration and rate of events. // Timer capture the duration and rate of events.
type Timer interface { type Timer interface {
Snapshot() TimerSnapshot Snapshot() TimerSnapshot
Stop() Stop()
@ -99,14 +99,14 @@ func (t *StandardTimer) Stop() {
t.meter.Stop() t.meter.Stop()
} }
// Record the duration of the execution of the given function. // Time record the duration of the execution of the given function.
func (t *StandardTimer) Time(f func()) { func (t *StandardTimer) Time(f func()) {
ts := time.Now() ts := time.Now()
f() f()
t.Update(time.Since(ts)) t.Update(time.Since(ts))
} }
// Record the duration of an event, in nanoseconds. // Update the duration of an event, in nanoseconds.
func (t *StandardTimer) Update(d time.Duration) { func (t *StandardTimer) Update(d time.Duration) {
t.mutex.Lock() t.mutex.Lock()
defer t.mutex.Unlock() defer t.mutex.Unlock()
@ -114,7 +114,7 @@ func (t *StandardTimer) Update(d time.Duration) {
t.meter.Mark(1) t.meter.Mark(1)
} }
// Record the duration of an event that started at a time and ends now. // UpdateSince update the duration of an event that started at a time and ends now.
// The record uses nanoseconds. // The record uses nanoseconds.
func (t *StandardTimer) UpdateSince(ts time.Time) { func (t *StandardTimer) UpdateSince(ts time.Time) {
t.Update(time.Since(ts)) t.Update(time.Since(ts))

Loading…
Cancel
Save