Allow Summaries with empty objectives and deprecate DefObjectives

This also updates all tests and examples to use explicitly set
objectives.

In v0.10, DefObjectives will be completely removed, and the default
Summary will have no objectives then.

Fixes #118

examples/random/main.go

@@ -42,8 +42,9 @@ var (
 	// differentiated via a "service" label.
 	rpcDurations = prometheus.NewSummaryVec(
 		prometheus.SummaryOpts{
-			Name: "rpc_durations_seconds",
-			Help: "RPC latency distributions.",
+			Name:       "rpc_durations_seconds",
+			Help:       "RPC latency distributions.",
+			Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		},
 		[]string{"service"},
 	)

prometheus/benchmark_test.go

@@ -129,8 +129,9 @@ func BenchmarkGaugeNoLabels(b *testing.B) {
 func BenchmarkSummaryWithLabelValues(b *testing.B) {
 	m := NewSummaryVec(
 		SummaryOpts{
-			Name: "benchmark_summary",
-			Help: "A summary to benchmark it.",
+			Name:       "benchmark_summary",
+			Help:       "A summary to benchmark it.",
+			Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		},
 		[]string{"one", "two", "three"},
 	)
@@ -143,8 +144,9 @@ func BenchmarkSummaryWithLabelValues(b *testing.B) {
 
 func BenchmarkSummaryNoLabels(b *testing.B) {
 	m := NewSummary(SummaryOpts{
-		Name: "benchmark_summary",
-		Help: "A summary to benchmark it.",
+		Name:       "benchmark_summary",
+		Help:       "A summary to benchmark it.",
+		Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 	},
 	)
 	b.ReportAllocs()

prometheus/examples_test.go

@@ -334,8 +334,9 @@ func ExampleRegister() {
 
 func ExampleSummary() {
 	temps := prometheus.NewSummary(prometheus.SummaryOpts{
-		Name: "pond_temperature_celsius",
-		Help: "The temperature of the frog pond.", // Sorry, we can't measure how badly it smells.
+		Name:       "pond_temperature_celsius",
+		Help:       "The temperature of the frog pond.",
+		Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 	})
 
 	// Simulate some observations.
@@ -372,8 +373,9 @@ func ExampleSummary() {
 func ExampleSummaryVec() {
 	temps := prometheus.NewSummaryVec(
 		prometheus.SummaryOpts{
-			Name: "pond_temperature_celsius",
-			Help: "The temperature of the frog pond.", // Sorry, we can't measure how badly it smells.
+			Name:       "pond_temperature_celsius",
+			Help:       "The temperature of the frog pond.",
+			Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		},
 		[]string{"species"},
 	)

prometheus/graphite/bridge_test.go

@@ -52,6 +52,7 @@ func TestWriteSummary(t *testing.T) {
 			Name:        "name",
 			Help:        "docstring",
 			ConstLabels: prometheus.Labels{"constname": "constvalue"},
+			Objectives:  map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		},
 		[]string{"labelname"},
 	)

prometheus/http.go

@@ -190,6 +190,7 @@ func InstrumentHandlerFunc(handlerName string, handlerFunc func(http.ResponseWri
 		SummaryOpts{
 			Subsystem:   "http",
 			ConstLabels: Labels{"handler": handlerName},
+			Objectives:  map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		},
 		handlerFunc,
 	)

prometheus/http_test.go

@@ -44,6 +44,7 @@ func TestInstrumentHandler(t *testing.T) {
 	opts := SummaryOpts{
 		Subsystem:   "http",
 		ConstLabels: Labels{"handler": "test-handler"},
+		Objectives:  map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 	}
 
 	reqCnt := NewCounterVec(

prometheus/summary.go

@@ -54,6 +54,9 @@ type Summary interface {
 }
 
 // DefObjectives are the default Summary quantile values.
+//
+// Deprecated: DefObjectives will not be used as the default objectives in
+// v0.10 of the library. The default Summary will have no quantiles then.
 var (
 	DefObjectives = map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001}
 
@@ -113,9 +116,15 @@ type SummaryOpts struct {
 	ConstLabels Labels
 
 	// Objectives defines the quantile rank estimates with their respective
-	// absolute error. If Objectives[q] = e, then the value reported
-	// for q will be the φ-quantile value for some φ between q-e and q+e.
-	// The default value is DefObjectives.
+	// absolute error. If Objectives[q] = e, then the value reported for q
+	// will be the φ-quantile value for some φ between q-e and q+e.  The
+	// default value is DefObjectives. It is used if Objectives is left at
+	// its zero value (i.e. nil). To create a Summary without Objectives,
+	// set it to an empty map (i.e. map[float64]float64{}).
+	//
+	// Deprecated: Note that the current value of DefObjectives is
+	// deprecated. It will be replaced by an empty map in v0.10 of the
+	// library. Please explicitly set Objectives to the desired value.
 	Objectives map[float64]float64
 
 	// MaxAge defines the duration for which an observation stays relevant
@@ -183,7 +192,7 @@ func newSummary(desc *Desc, opts SummaryOpts, labelValues ...string) Summary {
 		}
 	}
 
-	if len(opts.Objectives) == 0 {
+	if opts.Objectives == nil {
 		opts.Objectives = DefObjectives
 	}
 

prometheus/summary_test.go

@@ -25,6 +25,45 @@ import (
 	dto "github.com/prometheus/client_model/go"
 )
 
+func TestSummaryWithDefaultObjectives(t *testing.T) {
+	reg := NewRegistry()
+	summaryWithDefaultObjectives := NewSummary(SummaryOpts{
+		Name: "default_objectives",
+		Help: "Test help.",
+	})
+	if err := reg.Register(summaryWithDefaultObjectives); err != nil {
+		t.Error(err)
+	}
+
+	m := &dto.Metric{}
+	if err := summaryWithDefaultObjectives.Write(m); err != nil {
+		t.Error(err)
+	}
+	if len(m.GetSummary().Quantile) != len(DefObjectives) {
+		t.Error("expected default objectives in summary")
+	}
+}
+
+func TestSummaryWithoutObjectives(t *testing.T) {
+	reg := NewRegistry()
+	summaryWithEmptyObjectives := NewSummary(SummaryOpts{
+		Name:       "empty_objectives",
+		Help:       "Test help.",
+		Objectives: map[float64]float64{},
+	})
+	if err := reg.Register(summaryWithEmptyObjectives); err != nil {
+		t.Error(err)
+	}
+
+	m := &dto.Metric{}
+	if err := summaryWithEmptyObjectives.Write(m); err != nil {
+		t.Error(err)
+	}
+	if len(m.GetSummary().Quantile) != 0 {
+		t.Error("expected no objectives in summary")
+	}
+}
+
 func benchmarkSummaryObserve(w int, b *testing.B) {
 	b.StopTimer()
 
@@ -136,8 +175,9 @@ func TestSummaryConcurrency(t *testing.T) {
 		end.Add(concLevel)
 
 		sum := NewSummary(SummaryOpts{
-			Name: "test_summary",
-			Help: "helpless",
+			Name:       "test_summary",
+			Help:       "helpless",
+			Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 		})
 
 		allVars := make([]float64, total)
@@ -223,8 +263,9 @@ func TestSummaryVecConcurrency(t *testing.T) {
 
 		sum := NewSummaryVec(
 			SummaryOpts{
-				Name: "test_summary",
-				Help: "helpless",
+				Name:       "test_summary",
+				Help:       "helpless",
+				Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 			},
 			[]string{"label"},
 		)