Merge pull request #262 from prometheus/beorn7/summary

Allow Summaries with empty objectives and deprecate DefObjectives

examples/random/main.go

@@ -44,6 +44,7 @@ var (
 		prometheus.SummaryOpts{
 			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

@@ -131,6 +131,7 @@ func BenchmarkSummaryWithLabelValues(b *testing.B) {
 		SummaryOpts{
 			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"},
 	)
@@ -145,6 +146,7 @@ func BenchmarkSummaryNoLabels(b *testing.B) {
 	m := NewSummary(SummaryOpts{
 		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

@@ -335,7 +335,8 @@ 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.
+		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.
@@ -373,7 +374,8 @@ 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.
+			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()
 
@@ -138,6 +177,7 @@ func TestSummaryConcurrency(t *testing.T) {
 		sum := NewSummary(SummaryOpts{
 			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)
@@ -225,6 +265,7 @@ func TestSummaryVecConcurrency(t *testing.T) {
 			SummaryOpts{
 				Name:       "test_summary",
 				Help:       "helpless",
+				Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
 			},
 			[]string{"label"},
 		)