glide up

vendor/github.com/go-kit/kit/metrics/doc.go

@@ -1,48 +1,17 @@
-// Package metrics provides a framework for application instrumentation. It's
-// primarily designed to help you get started with good and robust
-// instrumentation, and to help you migrate from a less-capable system like
-// Graphite to a more-capable system like Prometheus. If your organization has
-// already standardized on an instrumentation system like Prometheus, and has no
-// plans to change, it may make sense to use that system's instrumentation
-// library directly.
+// Package metrics provides a framework for application instrumentation. All
+// metrics are safe for concurrent use. Considerable design influence has been
+// taken from https://github.com/codahale/metrics and https://prometheus.io.
 //
-// This package provides three core metric abstractions (Counter, Gauge, and
-// Histogram) and implementations for almost all common instrumentation
-// backends. Each metric has an observation method (Add, Set, or Observe,
-// respectively) used to record values, and a With method to "scope" the
-// observation by various parameters. For example, you might have a Histogram to
-// record request durations, parameterized by the method that's being called.
-//
-//    var requestDuration metrics.Histogram
-//    // ...
-//    requestDuration.With("method", "MyMethod").Observe(time.Since(begin))
-//
-// This allows a single high-level metrics object (requestDuration) to work with
-// many code paths somewhat dynamically. The concept of With is fully supported
-// in some backends like Prometheus, and not supported in other backends like
-// Graphite. So, With may be a no-op, depending on the concrete implementation
-// you choose. Please check the implementation to know for sure. For
-// implementations that don't provide With, it's necessary to fully parameterize
-// each metric in the metric name, e.g.
-//
-//    // Statsd
-//    c := statsd.NewCounter("request_duration_MyMethod_200")
-//    c.Add(1)
-//
-//    // Prometheus
-//    c := prometheus.NewCounter(stdprometheus.CounterOpts{
-//        Name: "request_duration",
-//        ...
-//    }, []string{"method", "status_code"})
-//    c.With("method", "MyMethod", "status_code", strconv.Itoa(code)).Add(1)
+// This package contains the common interfaces. Your code should take these
+// interfaces as parameters. Implementations are provided for different
+// instrumentation systems in the various subdirectories.
 //
 // Usage
 //
-// Metrics are dependencies, and should be passed to the components that need
+// Metrics are dependencies and should be passed to the components that need
 // them in the same way you'd construct and pass a database handle, or reference
-// to another component. Metrics should *not* be created in the global scope.
-// Instead, instantiate metrics in your func main, using whichever concrete
-// implementation is appropriate for your organization.
+// to another component. So, create metrics in your func main, using whichever
+// concrete implementation is appropriate for your organization.
 //
 //    latency := prometheus.NewSummaryFrom(stdprometheus.SummaryOpts{
 //        Namespace: "myteam",
@@ -71,14 +40,8 @@
 //    api := NewAPI(store, logger, latency)
 //    http.ListenAndServe("/", api)
 //
-// Note that metrics are "write-only" interfaces.
-//
 // Implementation details
 //
-// All metrics are safe for concurrent use. Considerable design influence has
-// been taken from https://github.com/codahale/metrics and
-// https://prometheus.io.
-//
 // Each telemetry system has different semantics for label values, push vs.
 // pull, support for histograms, etc. These properties influence the design of
 // their respective packages. This table attempts to summarize the key points of
@@ -91,6 +54,7 @@
 //    expvar      1    atomic                 atomic                 synthetic, batch, in-place expose
 //    influx      n    custom                 custom                 custom
 //    prometheus  n    native                 native                 native
+//    circonus    1    native                 native                 native
 //    pcp         1    native                 native                 native
 //
 package metrics