Document the possibility to create "empty" metrics in a metric vector.

This fixes https://github.com/prometheus/client_golang/issues/119.
This commit is contained in:
beorn7 2015-07-15 13:13:56 +02:00
parent 3b16b46a71
commit 7abba842b0
2 changed files with 31 additions and 2 deletions

View File

@ -392,6 +392,9 @@ func ExampleSummaryVec() {
temps.WithLabelValues("lithobates-catesbeianus").Observe(32 + math.Floor(100*math.Cos(float64(i)*0.11))/10) 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 // 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 // by (ab)using its Collect method and the Write method of its elements
// (which is usually only used by Prometheus internally - code like the // (which is usually only used by Prometheus internally - code like the
@ -414,6 +417,26 @@ func ExampleSummaryVec() {
// Output: // Output:
// [label: < // [label: <
// name: "species" // 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" // value: "lithobates-catesbeianus"
// > // >
// summary: < // summary: <

View File

@ -58,6 +58,11 @@ func (m *MetricVec) Collect(ch chan<- Metric) {
// GetMetricWithLabelValues returns the Metric for the given slice of label // GetMetricWithLabelValues returns the Metric for the given slice of label
// values (same order as the VariableLabels in Desc). If that combination of // 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. // 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 // Keeping the Metric for later use is possible (and should be considered if
// performance is critical), but keep in mind that Reset, DeleteLabelValues and // 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 // 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 // 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 // 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 // accessed for the first time, a new Metric is created. Implications of
// the Metric are the same as for GetMetricWithLabelValues. // 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 // An error is returned if the number and names of the Labels are inconsistent
// with those of the VariableLabels in Desc. // with those of the VariableLabels in Desc.