Merge pull request #3 from prometheus/usability/sundry

Fix documentation after reading via server.

README.md

@@ -1,20 +1,5 @@
-# Major Notes
-The project's documentation is *not up-to-date due to rapidly-changing
-requirements* that have quieted down in the interim, but the overall API should
-be stable for several months even if things change under the hood.
-
-An update to reflect the current state is pending.  Key changes for current
-users:
-
-1. The code has been qualified in production environments.
-2. Label-oriented metric exposition and registration, including docstrings.
-3. Deprecation of gocheck in favor of native table-driven tests.
-4. The best way to get a handle on this is to look at the examples.
-
-Barring that, the antique documentation is below:
-
 # Overview
-This [Go](http://golang.org) package is an extraction of a piece of
+These [Go](http://golang.org) packages are an extraction of pieces of
 instrumentation code I whipped-up for a personal project that a friend of mine
 and I are working on.  We were in need for some rudimentary statistics to
 observe behaviors of the server's various components, so this was written.
@@ -33,48 +18,50 @@ to be made, but this task has been deferred for now.
 [![Build Status](https://secure.travis-ci.org/prometheus/client_golang.png?branch=master)](http://travis-ci.org/prometheus/client_golang)
 
 # Documentation
-Please read the [generated documentation](http://go.pkgdoc.org/launchpad.net/gocheck)
+Please read the [generated documentation](http://go.pkgdoc.org/github.com/prometheus/client_golang)
 for the project's documentation from source code.
 
 # Basic Overview
 ## Metrics
 A metric is a measurement mechanism.
 
 ### Gauge
-A Gauge is a metric that exposes merely an instantaneous value or some snapshot
-thereof.
+A _Gauge_ is a metric that exposes merely an instantaneous value or some
+snapshot thereof.
+
+### Counter
+A _Counter_ is a metric that exposes merely a sum or tally of things.
 
 ### Histogram
-A Histogram is a metric that captures events or samples into buckets.  It
+A _Histogram_ is a metric that captures events or samples into _Buckets_.  It
 exposes its values via percentile estimations.
 
 #### Buckets
-A Bucket is a generic container that collects samples and their values.  It
+A _Bucket_ is a generic container that collects samples and their values.  It
 prescribes no behavior on its own aside from merely accepting a value,
 leaving it up to the concrete implementation to what to do with the injected
 values.
 
 ##### Accumulating Bucket
-An Accumulating Bucket is a bucket that appends the new sample to a timestamped
-priority queue such that the eldest values are evicted according to a given
-policy.
+An _Accumulating Bucket_ is a _Bucket_ that appends the new sample to a queue
+such that the eldest values are evicted according to a given policy.
 
-##### Eviction Policies
-Once an Accumulating Bucket reaches capacity, its eviction policy is invoked.
+###### Eviction Policies
+Once an _Accumulating Bucket_ reaches capacity, its eviction policy is invoked.
 This reaps the oldest N objects subject to certain behavior.
 
-###### Remove Oldest
+####### Remove Oldest
 This merely removes the oldest N items without performing some aggregation
 replacement operation on them.
 
-###### Aggregate Oldest
+####### Aggregate Oldest
 This removes the oldest N items while performing some summary aggregation
 operation thereupon, which is then appended to the list in the former values'
 place.
 
 ##### Tallying Bucket
-A Tallying Bucket differs from an Accumulating Bucket in that it never stores
-any of the values emitted into it but rather exposes a simplied summary
+A _Tallying Bucket_ differs from an _Accumulating Bucket_ in that it never
+stores any of the values emitted into it but rather exposes a simplied summary
 representation thereof.  For instance, if a values therein is requested,
 it may situationally emit a minimum, maximum, an average, or any other
 reduction mechanism requested.
@@ -84,3 +71,6 @@ This package employs [gocheck](http://labix.org/gocheck) for testing.  Please
 ensure that all tests pass by running the following from the project root:
 
     $ go test ./...
+
+The use of gocheck is summarily being phased out; however, old tests that use it
+still exist.

constants.go

@@ -10,15 +10,29 @@ var (
 	// NilLabels is a nil set of labels merely for end-user convenience.
 	NilLabels map[string]string = nil
 
+	// The default http.Handler for exposing telemetric data over a web services
+	// interface.
+	DefaultHandler = DefaultRegistry.Handler()
+
+	// This is the default registry with which Metric objects are associated.  It
+	// is primarily a read-only object after server instantiation.
+	DefaultRegistry = NewRegistry()
+)
+
+const (
 	// A prefix to be used to namespace instrumentation flags from others.
 	FlagNamespace = "telemetry."
 
 	// The format of the exported data.  This will match this library's version,
 	// which subscribes to the Semantic Versioning scheme.
 	APIVersion = "0.0.1"
 
+	// When reporting telemetric data over the HTTP web services interface, a web
+	// services interface shall include this header along with APIVersion as its
+	// value.
 	ProtocolVersionHeader = "X-Prometheus-API-Version"
 
+	// The customary web services endpoint on which telemetric data is exposed.
 	ExpositionResource = "/metrics.json"
 
 	baseLabelsKey = "baseLabels"

contributor/documentation.go

@@ -0,0 +1,9 @@
+// Copyright (c) 2013, Matt T. Proud
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+// A repository of various contributed Prometheus client components that may
+// assist in your use of the library.
+package contributor

contributor/responsewriter_delegator.go

@@ -1,10 +1,8 @@
-/*
-Copyright (c) 2013, Matt T. Proud
-All rights reserved.
-
-Use of this source code is governed by a BSD-style license that can be found in
-the LICENSE file.
-*/
+// Copyright (c) 2013, Matt T. Proud
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
 
 package contributor
 

documentation.go

@@ -6,47 +6,6 @@
 
 // registry.go provides a container for centralized exposition of metrics to
 // their prospective consumers.
-
-//  registry.Register("human_readable_metric_name", metric)
-
-// Please try to observe the following rules when naming metrics:
-
-// - Use underbars "_" to separate words.
-
-// - Have the metric name start from generality and work toward specificity
-// toward the end.  For example, when working with multiple caching subsystems,
-// consider using the following structure "cache" + "user_credentials" →
-// "cache_user_credentials" and "cache" + "value_transformations" →
-// "cache_value_transformations".
-
-// - Have whatever is being measured follow the system and subsystem names cited
-// supra.  For instance, with "insertions", "deletions", "evictions",
-// "replacements" of the above cache, they should be named as
-// "cache_user_credentials_insertions" and "cache_user_credentials_deletions"
-// and "cache_user_credentials_deletions" and
-// "cache_user_credentials_evictions".
-
-// - If what is being measured has a standardized unit around it, consider
-// providing a unit for it.
-
-// - Consider adding an additional suffix that designates what the value
-// represents such as a "total" or "size"---e.g.,
-// "cache_user_credentials_size_kb" or
-// "cache_user_credentials_insertions_total".
-
-// - Give heed to how future-proof the names are.  Things may depend on these
-// names; and as your service evolves, the calculated values may take on
-// different meanings, which can be difficult to reflect if deployed code
-// depends on antique names.
-
-// Further considerations:
-
-// - The Registry's exposition mechanism is not backed by authorization and
-// authentication.  This is something that will need to be addressed for
-// production services that are directly exposed to the outside world.
-
-// - Engage in as little in-process processing of values as possible.  The job
-// of processing and aggregation of these values belongs in a separate
-// post-processing job.  The same goes for archiving.  I will need to evaluate
-// hooks into something like OpenTSBD.
+//
+//  registry.Register("human_readable_metric_name", "metric docstring", map[string]string{"baseLabel": "baseLabelValue"}, metric)
 package registry

documentation/documentation.go

@@ -0,0 +1,8 @@
+// Copyright (c) 2013, Matt T. Proud
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found
+// in the LICENSE file.
+
+// A repository of various Prometheus client documentation and advice.
+package documentation

documentation/styleguide.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2013, Matt T. Proud
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found
+// in the LICENSE file.
+
+// Please try to observe the following rules when naming metrics:
+//
+// - Use underbars "_" to separate words.
+//
+// - Have the metric name start from generality and work toward specificity
+// toward the end.  For example, when working with multiple caching subsystems,
+// consider using the following structure "cache" + "user_credentials" →
+// "cache_user_credentials" and "cache" + "value_transformations" →
+// "cache_value_transformations".
+//
+// - Have whatever is being measured follow the system and subsystem names cited
+// supra.  For instance, with "insertions", "deletions", "evictions",
+// "replacements" of the above cache, they should be named as
+// "cache_user_credentials_insertions" and "cache_user_credentials_deletions"
+// and "cache_user_credentials_deletions" and
+// "cache_user_credentials_evictions".
+//
+// - If what is being measured has a standardized unit around it, consider
+// providing a unit for it.
+//
+// - Consider adding an additional suffix that designates what the value
+// represents such as a "total" or "size"---e.g.,
+// "cache_user_credentials_size_kb" or
+// "cache_user_credentials_insertions_total".
+//
+// - Give heed to how future-proof the names are.  Things may depend on these
+// names; and as your service evolves, the calculated values may take on
+// different meanings, which can be difficult to reflect if deployed code
+// depends on antique names.
+//
+// Further considerations:
+//
+// - The Registry's exposition mechanism is not backed by authorization and
+// authentication.  This is something that will need to be addressed for
+// production services that are directly exposed to the outside world.
+//
+// - Engage in as little in-process processing of values as possible.  The job
+// of processing and aggregation of these values belongs in a separate
+// post-processing job.  The same goes for archiving.  I will need to evaluate
+// hooks into something like OpenTSBD.
+
+package documentation

examples/documentation.go

@@ -0,0 +1,8 @@
+// Copyright (c) 2012, Matt T. Proud
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found
+// in the LICENSE file.
+
+// Various Prometheus client examples.
+package examples

examples/random/main.go

@@ -4,9 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// main.go provides a simple example of how to use this instrumentation
-// framework in the context of having something that emits values into
-// its collectors.
+// A simple example of how to use this instrumentation framework in the context
+// of having something that emits values into its collectors.
 //
 // The emitted values correspond to uniform, normal, and exponential
 // distributions.

examples/simple/main.go

@@ -4,8 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// main.go provides a simple skeletal example of how this instrumentation
-// framework is registered and invoked.
+// A simple skeletal example of how this instrumentation framework is registered
+// and invoked.  Literally, this is the bare bones.
 package main
 
 import (

maths/documentation.go

@@ -5,18 +5,18 @@
 // license that can be found in the LICENSE file.
 
 // The maths package provides a number of mathematical-related helpers:
-
+//
 // distributions.go provides basic distribution-generating functions that are
 // used primarily in testing contexts.
-
+//
 // helpers_for_testing.go provides a testing assistents for this package and its
 // dependents.
-
+//
 // maths_test.go provides a test suite for all tests in the maths package
 // hierarchy.  It employs the gocheck framework for test scaffolding.
-
+//
 // statistics.go provides basic summary statistics functions for the purpose of
 // metrics aggregation.
-
+//
 // statistics_test.go provides a test complement for the statistics.go module.
 package maths