From b9a1b5ed1e0d6cf9b86d091d48601be9fd4658ea Mon Sep 17 00:00:00 2001
From: Peter Bourgon <peter@bourgon.org>
Date: Sat, 17 Dec 2016 16:20:23 +0100
Subject: [PATCH 1/2] metrics: improve README

---
 metrics/doc.go | 42 +++++++++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 9 deletions(-)

diff --git a/metrics/doc.go b/metrics/doc.go
index 0318ed8a4..1bc5db066 100644
--- a/metrics/doc.go
+++ b/metrics/doc.go
@@ -1,17 +1,35 @@
-// 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.
+// 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 probably makes sense to use that system's instrumentation
+// library directly.
 //
-// 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.
+// 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.
 //
 // 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. So, create metrics in your func main, using whichever
-// concrete implementation is appropriate for your organization.
+// 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.
 //
 //    latency := prometheus.NewSummaryFrom(stdprometheus.SummaryOpts{
 //        Namespace: "myteam",
@@ -40,8 +58,14 @@
 //    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

From 200cb17653ef4918c38c6f7f75389353324ae110 Mon Sep 17 00:00:00 2001
From: Peter Bourgon <peter@bourgon.org>
Date: Sun, 18 Dec 2016 14:43:24 +0100
Subject: [PATCH 2/2] metrics: minor improvements to package docs

---
 metrics/README.md | 2 ++
 metrics/doc.go    | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/metrics/README.md b/metrics/README.md
index 1cbb9ab11..fd3347eaa 100644
--- a/metrics/README.md
+++ b/metrics/README.md
@@ -93,3 +93,5 @@ func exportGoroutines(g metrics.Gauge) {
 	}
 }
 ```
+
+For more information, see [the package documentation](https://godoc.org/github.com/go-kit/kit/metrics).
diff --git a/metrics/doc.go b/metrics/doc.go
index 1bc5db066..a3b3a36f4 100644
--- a/metrics/doc.go
+++ b/metrics/doc.go
@@ -3,7 +3,7 @@
 // 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 probably makes sense to use that system's instrumentation
+// plans to change, it may make sense to use that system's instrumentation
 // library directly.
 //
 // This package provides three core metric abstractions (Counter, Gauge, and