metrics: updates per feedback

metrics/counter.go

@@ -2,7 +2,7 @@ package metrics
 
 import "sync/atomic"
 
-// Counters hold an int64 value that can be incremented and decremented.
+// Counter holds an int64 value that can be incremented and decremented.
 type Counter interface {
 	Clear()
 	Count() int64

metrics/debug.go

@@ -19,17 +19,18 @@ var (
 	gcStats debug.GCStats
 )
 
-// Capture new values for the Go garbage collector statistics exported in
-// debug.GCStats.  This is designed to be called as a goroutine.
+// CaptureDebugGCStats captures new values for the Go garbage collector statistics 
+// exported in debug.GCStats.  This is designed to be called as a goroutine.
 func CaptureDebugGCStats(r Registry, d time.Duration) {
 	for range time.Tick(d) {
 		CaptureDebugGCStatsOnce(r)
 	}
 }
 
-// Capture new values for the Go garbage collector statistics exported in
-// debug.GCStats.  This is designed to be called in a background goroutine.
-// Giving a registry which has not been given to RegisterDebugGCStats will
+// CaptureDebugGCStatsOnce captures new values for the Go garbage collector
+// statistics exported in debug.GCStats.  This is designed to be called in a 
+// background goroutine.Giving a registry which has not been given to 
+// RegisterDebugGCStats will
 // panic.
 //
 // Be careful (but much less so) with this because debug.ReadGCStats calls
@@ -50,8 +51,8 @@ func CaptureDebugGCStatsOnce(r Registry) {
 	debugMetrics.GCStats.PauseTotal.Update(int64(gcStats.PauseTotal))
 }
 
-// Register metrics for the Go garbage collector statistics exported in
-// debug.GCStats.  The metrics are named by their fully-qualified Go symbols,
+// RegisterDebugGCStats registers metrics for the Go garbage collector statistics
+// exported in debug.GCStats.  The metrics are named by their fully-qualified Go symbols,
 // i.e. debug.GCStats.PauseTotal.
 func RegisterDebugGCStats(r Registry) {
 	debugMetrics.GCStats.LastGC = NewGauge()

metrics/ewma.go

@@ -6,7 +6,7 @@ import (
 	"sync/atomic"
 )
 
-// EWMAs continuously calculate an exponentially-weighted moving average
+// EWMA continuously calculates an exponentially-weighted moving average
 // based on an outside source of clock ticks.
 type EWMA interface {
 	Rate() float64

metrics/exp/exp.go

@@ -1,5 +1,7 @@
-// Hook go-metrics into expvar
-// on any /debug/metrics request, load all vars from the registry into expvar, and execute regular expvar handler
+// Package exp hooks go-metrics into expvar.
+//
+// On any /debug/metrics request, loads all vars from the registry into expvar,
+// and executes regular expvar handler.
 package exp
 
 import (

metrics/gauge.go

@@ -2,7 +2,7 @@ package metrics
 
 import "sync/atomic"
 
-// Gauges hold an int64 value that can be set arbitrarily.
+// Gauge holds an int64 value that can be set arbitrarily.
 type Gauge interface {
 	Snapshot() Gauge
 	Update(int64)

metrics/gauge_float64.go

@@ -2,7 +2,7 @@ package metrics
 
 import "sync"
 
-// GaugeFloat64s hold a float64 value that can be set arbitrarily.
+// GaugeFloat64 holds a float64 value that can be set arbitrarily.
 type GaugeFloat64 interface {
 	Snapshot() GaugeFloat64
 	Update(float64)
@@ -38,7 +38,7 @@ func NewRegisteredGaugeFloat64(name string, r Registry) GaugeFloat64 {
 	return c
 }
 
-// NewFunctionalGauge constructs a new FunctionalGauge.
+// NewFunctionalGaugeFloat64 constructs a new FunctionalGauge.
 func NewFunctionalGaugeFloat64(f func() float64) GaugeFloat64 {
 	if !Enabled {
 		return NilGaugeFloat64{}
@@ -46,7 +46,7 @@ func NewFunctionalGaugeFloat64(f func() float64) GaugeFloat64 {
 	return &FunctionalGaugeFloat64{value: f}
 }
 
-// NewRegisteredFunctionalGauge constructs and registers a new StandardGauge.
+// NewRegisteredFunctionalGaugeFloat64 constructs and registers a new StandardGauge.
 func NewRegisteredFunctionalGaugeFloat64(name string, r Registry, f func() float64) GaugeFloat64 {
 	c := NewFunctionalGaugeFloat64(f)
 	if nil == r {
@@ -70,7 +70,7 @@ func (GaugeFloat64Snapshot) Update(float64) {
 // Value returns the value at the time the snapshot was taken.
 func (g GaugeFloat64Snapshot) Value() float64 { return float64(g) }
 
-// NilGauge is a no-op Gauge.
+// NilGaugeFloat64 is a no-op Gauge.
 type NilGaugeFloat64 struct{}
 
 // Snapshot is a no-op.

metrics/healthcheck.go

@@ -1,6 +1,6 @@
 package metrics
 
-// Healthchecks hold an error value describing an arbitrary up/down status.
+// Healthcheck holds an error value describing an arbitrary up/down status.
 type Healthcheck interface {
 	Check()
 	Error() error

metrics/histogram.go

@@ -1,6 +1,6 @@
 package metrics
 
-// Histograms calculate distribution statistics from a series of int64 values.
+// Histogram calculates distribution statistics from a series of int64 values.
 type Histogram interface {
 	Clear()
 	Count() int64

metrics/json.go

@@ -26,6 +26,8 @@ func WriteJSONOnce(r Registry, w io.Writer) {
 	json.NewEncoder(w).Encode(r)
 }
 
+// MarshalJSON returns a byte slice containing a JSON representation of all
+// the metrics in the Registry.
 func (p *PrefixedRegistry) MarshalJSON() ([]byte, error) {
 	return json.Marshal(p.GetAll())
 }

metrics/librato/client.go

@@ -11,6 +11,7 @@ import (
 const Operations = "operations"
 const OperationsShort = "ops"
 
+// LibratoClient holds an email and a token.
 type LibratoClient struct {
 	Email, Token string
 }
@@ -52,7 +53,7 @@ const (
 	Counters = "counters"
 	Gauges   = "gauges"
 
-	MetricsPostUrl = "https://metrics-api.librato.com/v1/metrics"
+	MetricsPostURL = "https://metrics-api.librato.com/v1/metrics"
 )
 
 type Measurement map[string]interface{}
@@ -80,7 +81,7 @@ func (c *LibratoClient) PostMetrics(batch Batch) (err error) {
 		return
 	}
 
-	if req, err = http.NewRequest("POST", MetricsPostUrl, bytes.NewBuffer(js)); err != nil {
+	if req, err = http.NewRequest("POST", MetricsPostURL, bytes.NewBuffer(js)); err != nil {
 		return
 	}
 

metrics/librato/librato.go

@@ -43,7 +43,7 @@ func Librato(r metrics.Registry, d time.Duration, e string, t string, s string,
 func (rep *Reporter) Run() {
 	log.Printf("WARNING: This client has been DEPRECATED! It has been moved to https://github.com/mihasya/go-metrics-librato and will be removed from rcrowley/go-metrics on August 5th 2015")
 	ticker := time.Tick(rep.Interval)
-	metricsApi := &LibratoClient{rep.Email, rep.Token}
+	metricsAPI := &LibratoClient{rep.Email, rep.Token}
 	for now := range ticker {
 		var metrics Batch
 		var err error
@@ -51,7 +51,7 @@ func (rep *Reporter) Run() {
 			log.Printf("ERROR constructing librato request body %s", err)
 			continue
 		}
-		if err := metricsApi.PostMetrics(metrics); err != nil {
+		if err := metricsAPI.PostMetrics(metrics); err != nil {
 			log.Printf("ERROR sending metrics to librato %s", err)
 			continue
 		}

metrics/log.go

@@ -4,15 +4,18 @@ import (
 	"time"
 )
 
+// Logger will print any number of passed arguments of type interface.
 type Logger interface {
 	Printf(format string, v ...interface{})
 }
 
+// Log outputs each metric in the given registry periodically using the given
+// logger and current time in nanos.
 func Log(r Registry, freq time.Duration, l Logger) {
 	LogScaled(r, freq, time.Nanosecond, l)
 }
 
-// Output each metric in the given registry periodically using the given
+// LogScaled outputs each metric in the given registry periodically using the given
 // logger. Print timings in `scale` units (eg time.Millisecond) rather than nanos.
 func LogScaled(r Registry, freq time.Duration, scale time.Duration, l Logger) {
 	du := float64(scale)

metrics/meter.go

@@ -5,7 +5,7 @@ import (
 	"time"
 )
 
-// Meters count events to produce exponentially-weighted moving average rates
+// Meter counts events to produce exponentially-weighted moving average rates
 // at one-, five-, and fifteen-minutes and a mean rate.
 type Meter interface {
 	Count() int64
@@ -46,7 +46,7 @@ func NewMeter() Meter {
 	return m
 }
 
-// NewMeter constructs and registers a new StandardMeter and launches a
+// NewRegisteredMeter constructs and registers a new StandardMeter and launches a
 // goroutine.
 // Be sure to unregister the meter from the registry once it is of no use to
 // allow for garbage collection.

metrics/metrics.go

@@ -2,7 +2,7 @@
 //
 // <https://github.com/rcrowley/go-metrics>
 //
-// Coda Hale's original work: <https://github.com/codahale/metrics>
+// Package metrics is a go port of Coda Hale's original work: <https://github.com/codahale/metrics>
 package metrics
 
 import (
@@ -19,7 +19,7 @@ import (
 //
 // This global kill-switch helps quantify the observer effect and makes
 // for less cluttered pprof profiles.
-var Enabled bool = false
+var Enabled = false
 
 // MetricsEnabledFlag is the CLI flag name to use to enable metrics collections.
 const MetricsEnabledFlag = "metrics"

metrics/opentsdb.go

@@ -10,7 +10,7 @@ import (
 	"time"
 )
 
-var shortHostName string = ""
+var shortHostName string
 
 // OpenTSDBConfig provides a container with configuration parameters for
 // the OpenTSDB exporter

metrics/registry.go

@@ -50,33 +50,32 @@ type Registry interface {
 	UnregisterAll()
 }
 
-// The standard implementation of a Registry is a mutex-protected map
-// of names to metrics.
+// StandardRegistry is a mutex protected implementation of a Registry.
 type StandardRegistry struct {
 	metrics map[string]interface{}
 	mutex   sync.Mutex
 }
 
-// Create a new registry.
+// NewRegistry creates a new registry.
 func NewRegistry() Registry {
 	return &StandardRegistry{metrics: make(map[string]interface{})}
 }
 
-// Call the given function for each registered metric.
+// Each calls the given function for each registered metric.
 func (r *StandardRegistry) Each(f func(string, interface{})) {
 	for name, i := range r.registered() {
 		f(name, i)
 	}
 }
 
-// Get the metric by the given name or nil if none is registered.
+// Get gets the metric by the given name or nil if none is registered.
 func (r *StandardRegistry) Get(name string) interface{} {
 	r.mutex.Lock()
 	defer r.mutex.Unlock()
 	return r.metrics[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.
 // The interface can be the metric to register if not found in registry,
 // or a function returning the metric for lazy instantiation.
@@ -101,7 +100,7 @@ func (r *StandardRegistry) Register(name string, i interface{}) error {
 	return r.register(name, i)
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks runs all registered healthchecks.
 func (r *StandardRegistry) RunHealthchecks() {
 	r.mutex.Lock()
 	defer r.mutex.Unlock()
@@ -181,7 +180,7 @@ func (r *StandardRegistry) Unregister(name string) {
 	delete(r.metrics, name)
 }
 
-// Unregister all metrics.  (Mostly for testing.)
+// UnregisterAll unregisters all metrics. Mostly for testing.
 func (r *StandardRegistry) UnregisterAll() {
 	r.mutex.Lock()
 	defer r.mutex.Unlock()
@@ -244,7 +243,7 @@ func NewPrefixedChildRegistry(parent Registry, prefix string) Registry {
 	}
 }
 
-// Call the given function for each registered metric.
+// Each calls the given function for each registered metric.
 func (r *PrefixedRegistry) Each(fn func(string, interface{})) {
 	wrappedFn := func(prefix string) func(string, interface{}) {
 		return func(name string, iface interface{}) {
@@ -276,7 +275,7 @@ func (r *PrefixedRegistry) Get(name string) interface{} {
 	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,
 // or a function returning the metric for lazy instantiation.
 func (r *PrefixedRegistry) GetOrRegister(name string, metric interface{}) interface{} {
@@ -290,7 +289,7 @@ func (r *PrefixedRegistry) Register(name string, metric interface{}) error {
 	return r.underlying.Register(realName, metric)
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks runs all registered healthchecks.
 func (r *PrefixedRegistry) RunHealthchecks() {
 	r.underlying.RunHealthchecks()
 }
@@ -306,14 +305,14 @@ func (r *PrefixedRegistry) Unregister(name string) {
 	r.underlying.Unregister(realName)
 }
 
-// Unregister all metrics.  (Mostly for testing.)
+// UnregisterAll unregisters all metrics. Mostly for testing.
 func (r *PrefixedRegistry) UnregisterAll() {
 	r.underlying.UnregisterAll()
 }
 
-var DefaultRegistry Registry = NewRegistry()
+var DefaultRegistry = NewRegistry()
 
-// Call the given function for each registered metric.
+// Each calls the given function for each registered metric.
 func Each(f func(string, interface{})) {
 	DefaultRegistry.Each(f)
 }
@@ -323,7 +322,7 @@ func Get(name string) interface{} {
 	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.
 func GetOrRegister(name string, i interface{}) interface{} {
 	return DefaultRegistry.GetOrRegister(name, i)
@@ -335,7 +334,7 @@ func Register(name string, i interface{}) error {
 	return DefaultRegistry.Register(name, i)
 }
 
-// Register the given metric under the given name.  Panics if a metric by the
+// MustRegister registers the given metric under the given name.  Panics if a metric by the
 // given name is already registered.
 func MustRegister(name string, i interface{}) {
 	if err := Register(name, i); err != nil {
@@ -343,7 +342,7 @@ func MustRegister(name string, i interface{}) {
 	}
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks runs all registered healthchecks.
 func RunHealthchecks() {
 	DefaultRegistry.RunHealthchecks()
 }

metrics/resetting_timer.go

@@ -7,7 +7,8 @@ import (
 	"time"
 )
 
-// Initial slice capacity for the values stored in a ResettingTimer
+// InitialResettingTimerSliceCap is the initial slice capacity for the values
+// stored in a ResettingTimer.
 const InitialResettingTimerSliceCap = 10
 
 // ResettingTimer is used for storing aggregated values for timers, which are reset on every flush interval.
@@ -113,21 +114,21 @@ func (t *StandardResettingTimer) Mean() float64 {
 	panic("Mean called on a StandardResettingTimer")
 }
 
-// Record the duration of the execution of the given function.
+// Time records the duration of the execution of the given function.
 func (t *StandardResettingTimer) Time(f func()) {
 	ts := time.Now()
 	f()
 	t.Update(time.Since(ts))
 }
 
-// Record the duration of an event.
+// Update records the duration of an event.
 func (t *StandardResettingTimer) Update(d time.Duration) {
 	t.mutex.Lock()
 	defer t.mutex.Unlock()
 	t.values = append(t.values, int64(d))
 }
 
-// Record the duration of an event that started at a time and ends now.
+// UpdateSince records the duration of an event that started at a time and ends now.
 func (t *StandardResettingTimer) UpdateSince(ts time.Time) {
 	t.mutex.Lock()
 	defer t.mutex.Unlock()
@@ -211,7 +212,7 @@ func (t *ResettingTimerSnapshot) calc(percentiles []float64) {
 				// math.Floor(x + 0.5)
 				indexOfPerc := int(math.Floor(((abs / 100.0) * float64(count)) + 0.5))
 				if pct >= 0 {
-					indexOfPerc -= 1 // index offset=0
+					indexOfPerc-- // index offset=0
 				}
 				thresholdBoundary = t.values[indexOfPerc]
 			}

metrics/runtime.go

@@ -52,18 +52,18 @@ var (
 	threadCreateProfile = pprof.Lookup("threadcreate")
 )
 
-// Capture new values for the Go runtime statistics exported in
-// runtime.MemStats.  This is designed to be called as a goroutine.
+// CaptureRuntimeMemStats captures new values for the Go runtime statistics exported 
+// in runtime.MemStats.  This is designed to be called as a goroutine.
 func CaptureRuntimeMemStats(r Registry, d time.Duration) {
 	for range time.Tick(d) {
 		CaptureRuntimeMemStatsOnce(r)
 	}
 }
 
-// Capture new values for the Go runtime statistics exported in
-// runtime.MemStats.  This is designed to be called in a background
-// goroutine.  Giving a registry which has not been given to
-// RegisterRuntimeMemStats will panic.
+// CaptureRuntimeMemStatsOnce captures new values for the Go runtime statistics 
+// exported in runtime.MemStats.  This is designed to be called in a background
+// goroutine.  Giving a registry which has not been given to RegisterRuntimeMemStats
+// will panic.
 //
 // Be very careful with this because runtime.ReadMemStats calls the C
 // functions runtime·semacquire(&runtime·worldsema) and runtime·stoptheworld()
@@ -142,7 +142,7 @@ func CaptureRuntimeMemStatsOnce(r Registry) {
 	runtimeMetrics.NumThread.Update(int64(threadCreateProfile.Count()))
 }
 
-// Register runtimeMetrics for the Go runtime statistics exported in runtime and
+// RegisterRuntimeMemStats registers runtimeMetrics for the Go runtime statistics exported in runtime and
 // specifically runtime.MemStats.  The runtimeMetrics are named by their
 // fully-qualified Go symbols, i.e. runtime.MemStats.Alloc.
 func RegisterRuntimeMemStats(r Registry) {

metrics/sample.go

@@ -10,7 +10,7 @@ import (
 
 const rescaleThreshold = time.Hour
 
-// Samples maintain a statistically-significant selection of values from
+// Sample maintains a statistically-significant selection of values from
 // a stream.
 type Sample interface {
 	Clear()
@@ -214,7 +214,7 @@ func (NilSample) Percentiles(ps []float64) []float64 {
 // Size is a no-op.
 func (NilSample) Size() int { return 0 }
 
-// Sample is a no-op.
+// Snapshot is a no-op.
 func (NilSample) Snapshot() Sample { return NilSample{} }
 
 // StdDev is a no-op.
@@ -268,7 +268,7 @@ func SampleMin(values []int64) int64 {
 	return min
 }
 
-// SamplePercentiles returns an arbitrary percentile of the slice of int64.
+// SamplePercentile returns an arbitrary percentile of the slice of int64.
 func SamplePercentile(values int64Slice, p float64) float64 {
 	return SamplePercentiles(values, []float64{p})[0]
 }
@@ -302,6 +302,7 @@ type SampleSnapshot struct {
 	values []int64
 }
 
+// NewSampleSnapshot creates a new sample snapshot.
 func NewSampleSnapshot(count int64, values []int64) *SampleSnapshot {
 	return &SampleSnapshot{
 		count:  count,
@@ -394,7 +395,7 @@ func SampleVariance(values []int64) float64 {
 	return sum / float64(len(values))
 }
 
-// A uniform sample using Vitter's Algorithm R.
+// UniformSample represents a uniform sample using Vitter's Algorithm R.
 //
 // <http://www.cs.umd.edu/~samir/498/vitter.pdf>
 type UniformSample struct {

metrics/syslog.go

@@ -8,7 +8,7 @@ import (
 	"time"
 )
 
-// Output each metric in the given registry to syslog periodically using
+// Syslog outputs each metric in the given registry to syslog periodically using
 // the given syslogger.
 func Syslog(r Registry, d time.Duration, w *syslog.Writer) {
 	for range time.Tick(d) {

metrics/timer.go

@@ -5,7 +5,7 @@ import (
 	"time"
 )
 
-// Timers capture the duration and rate of events.
+// Timer captures the duration and rate of events.
 type Timer interface {
 	Count() int64
 	Max() int64
@@ -221,14 +221,14 @@ func (t *StandardTimer) Sum() int64 {
 	return t.histogram.Sum()
 }
 
-// Record the duration of the execution of the given function.
+// Time records the duration of the execution of the given function.
 func (t *StandardTimer) Time(f func()) {
 	ts := time.Now()
 	f()
 	t.Update(time.Since(ts))
 }
 
-// Record the duration of an event.
+// Update records the duration of an event.
 func (t *StandardTimer) Update(d time.Duration) {
 	t.mutex.Lock()
 	defer t.mutex.Unlock()
@@ -236,7 +236,7 @@ func (t *StandardTimer) Update(d time.Duration) {
 	t.meter.Mark(1)
 }
 
-// Record the duration of an event that started at a time and ends now.
+// UpdateSince records the duration of an event that started at a time and ends now.
 func (t *StandardTimer) UpdateSince(ts time.Time) {
 	t.mutex.Lock()
 	defer t.mutex.Unlock()