Merge pull request #278 from prometheus/grobie/update-graphite-exposition

Document graphite bridge

prometheus/doc.go

@@ -17,7 +17,7 @@
 // Pushgateway (package push).
 //
 // All exported functions and methods are safe to be used concurrently unless
-//specified otherwise.
+// specified otherwise.
 //
 // A Basic Example
 //
@@ -95,8 +95,8 @@
 // SummaryVec, HistogramVec, and UntypedVec are not.
 //
 // To create instances of Metrics and their vector versions, you need a suitable
-// …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts,
+// …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, HistogramOpts, or
-// HistogramOpts, or UntypedOpts.
+// UntypedOpts.
 //
 // Custom Collectors and constant Metrics
 //
@@ -114,8 +114,8 @@
 // Metric instances “on the fly” using NewConstMetric, NewConstHistogram, and
 // NewConstSummary (and their respective Must… versions). That will happen in
 // the Collect method. The Describe method has to return separate Desc
-// instances, representative of the “throw-away” metrics to be created
+// instances, representative of the “throw-away” metrics to be created later.
-// later. NewDesc comes in handy to create those Desc instances.
+// NewDesc comes in handy to create those Desc instances.
 //
 // The Collector example illustrates the use case. You can also look at the
 // source code of the processCollector (mirroring process metrics), the
@@ -129,32 +129,32 @@
 // Advanced Uses of the Registry
 //
 // While MustRegister is the by far most common way of registering a Collector,
-// sometimes you might want to handle the errors the registration might
+// sometimes you might want to handle the errors the registration might cause.
-// cause. As suggested by the name, MustRegister panics if an error occurs. With
+// As suggested by the name, MustRegister panics if an error occurs. With the
-// the Register function, the error is returned and can be handled.
+// Register function, the error is returned and can be handled.
 //
 // An error is returned if the registered Collector is incompatible or
 // inconsistent with already registered metrics. The registry aims for
-// consistency of the collected metrics according to the Prometheus data
+// consistency of the collected metrics according to the Prometheus data model.
-// model. Inconsistencies are ideally detected at registration time, not at
+// Inconsistencies are ideally detected at registration time, not at collect
-// collect time. The former will usually be detected at start-up time of a
+// time. The former will usually be detected at start-up time of a program,
-// program, while the latter will only happen at scrape time, possibly not even
+// while the latter will only happen at scrape time, possibly not even on the
-// on the first scrape if the inconsistency only becomes relevant later. That is
+// first scrape if the inconsistency only becomes relevant later. That is the
-// the main reason why a Collector and a Metric have to describe themselves to
+// main reason why a Collector and a Metric have to describe themselves to the
-// the registry.
+// registry.
 //
 // So far, everything we did operated on the so-called default registry, as it
 // can be found in the global DefaultRegistry variable. With NewRegistry, you
 // can create a custom registry, or you can even implement the Registerer or
-// Gatherer interfaces yourself. The methods Register and Unregister work in
+// Gatherer interfaces yourself. The methods Register and Unregister work in the
-// the same way on a custom registry as the global functions Register and
+// same way on a custom registry as the global functions Register and Unregister
-// Unregister on the default registry.
+// on the default registry.
 //
-// There are a number of uses for custom registries: You can use registries
+// There are a number of uses for custom registries: You can use registries with
-// with special properties, see NewPedanticRegistry. You can avoid global state,
+// special properties, see NewPedanticRegistry. You can avoid global state, as
-// as it is imposed by the DefaultRegistry. You can use multiple registries at
+// it is imposed by the DefaultRegistry. You can use multiple registries at the
-// the same time to expose different metrics in different ways. You can use
+// same time to expose different metrics in different ways. You can use separate
-// separate registries for testing purposes.
+// registries for testing purposes.
 //
 // Also note that the DefaultRegistry comes registered with a Collector for Go
 // runtime metrics (via NewGoCollector) and a Collector for process metrics (via
@@ -166,16 +166,20 @@
 // The Registry implements the Gatherer interface. The caller of the Gather
 // method can then expose the gathered metrics in some way. Usually, the metrics
 // are served via HTTP on the /metrics endpoint. That's happening in the example
-// above. The tools to expose metrics via HTTP are in the promhttp
+// above. The tools to expose metrics via HTTP are in the promhttp sub-package.
-// sub-package. (The top-level functions in the prometheus package are
+// (The top-level functions in the prometheus package are deprecated.)
-// deprecated.)
 //
 // Pushing to the Pushgateway
 //
 // Function for pushing to the Pushgateway can be found in the push sub-package.
 //
+// Graphite Bridge
+//
+// Functions and examples to push metrics from a Gatherer to Graphite can be
+// found in the graphite sub-package.
+//
 // Other Means of Exposition
 //
-// More ways of exposing metrics can easily be added. Sending metrics to
+// More ways of exposing metrics can easily be added by following the approaches
-// Graphite would be an example that will soon be implemented.
+// of the existing implementations.
 package prometheus