From 7abba842b03fc1b4690e801697493b2f507f0172 Mon Sep 17 00:00:00 2001
From: beorn7 <beorn@soundcloud.com>
Date: Wed, 15 Jul 2015 13:13:56 +0200
Subject: [PATCH] Document the possibility to create "empty" metrics in a
 metric vector.

This fixes https://github.com/prometheus/client_golang/issues/119.
---
 prometheus/examples_test.go | 23 +++++++++++++++++++++++
 prometheus/vec.go           | 10 ++++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/prometheus/examples_test.go b/prometheus/examples_test.go
index a28a801..0344e46 100644
--- a/prometheus/examples_test.go
+++ b/prometheus/examples_test.go
@@ -392,6 +392,9 @@ func ExampleSummaryVec() {
 		temps.WithLabelValues("lithobates-catesbeianus").Observe(32 + math.Floor(100*math.Cos(float64(i)*0.11))/10)
 	}
 
+	// Create a Summary without any observations.
+	temps.WithLabelValues("leiopelma-hochstetteri")
+
 	// Just for demonstration, let's check the state of the summary vector
 	// by (ab)using its Collect method and the Write method of its elements
 	// (which is usually only used by Prometheus internally - code like the
@@ -414,6 +417,26 @@ func ExampleSummaryVec() {
 	// Output:
 	// [label: <
 	//   name: "species"
+	//   value: "leiopelma-hochstetteri"
+	// >
+	// summary: <
+	//   sample_count: 0
+	//   sample_sum: 0
+	//   quantile: <
+	//     quantile: 0.5
+	//     value: nan
+	//   >
+	//   quantile: <
+	//     quantile: 0.9
+	//     value: nan
+	//   >
+	//   quantile: <
+	//     quantile: 0.99
+	//     value: nan
+	//   >
+	// >
+	//  label: <
+	//   name: "species"
 	//   value: "lithobates-catesbeianus"
 	// >
 	// summary: <
diff --git a/prometheus/vec.go b/prometheus/vec.go
index aa49deb..a1f3bdf 100644
--- a/prometheus/vec.go
+++ b/prometheus/vec.go
@@ -58,6 +58,11 @@ func (m *MetricVec) Collect(ch chan<- Metric) {
 // GetMetricWithLabelValues returns the Metric for the given slice of label
 // values (same order as the VariableLabels in Desc). If that combination of
 // label values is accessed for the first time, a new Metric is created.
+//
+// It is possible to call this method without using the returned Metric to only
+// create the new Metric but leave it at its start value (e.g. a Summary or
+// Histogram without any observations). See also the SummaryVec example.
+//
 // Keeping the Metric for later use is possible (and should be considered if
 // performance is critical), but keep in mind that Reset, DeleteLabelValues and
 // Delete can be used to delete the Metric from the MetricVec. In that case, the
@@ -87,8 +92,9 @@ func (m *MetricVec) GetMetricWithLabelValues(lvs ...string) (Metric, error) {
 
 // GetMetricWith returns the Metric for the given Labels map (the label names
 // must match those of the VariableLabels in Desc). If that label map is
-// accessed for the first time, a new Metric is created. Implications of keeping
-// the Metric are the same as for GetMetricWithLabelValues.
+// accessed for the first time, a new Metric is created. Implications of
+// creating a Metric without using it and keeping the Metric for later use are
+// the same as for GetMetricWithLabelValues.
 //
 // An error is returned if the number and names of the Labels are inconsistent
 // with those of the VariableLabels in Desc.