2015-02-02 17:14:36 +03:00
|
|
|
// Copyright 2014 The Prometheus Authors
|
2014-05-07 22:08:33 +04:00
|
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
|
// you may not use this file except in compliance with the License.
|
|
|
|
|
// You may obtain a copy of the License at
|
|
|
|
|
//
|
|
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
//
|
|
|
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
// See the License for the specific language governing permissions and
|
|
|
|
|
// limitations under the License.
|
|
|
|
|
|
2015-02-02 17:14:36 +03:00
|
|
|
// Copyright (c) 2013, The Prometheus Authors
|
2013-01-19 17:48:30 +04:00
|
|
|
// All rights reserved.
|
|
|
|
|
//
|
2013-02-12 05:36:06 +04:00
|
|
|
// Use of this source code is governed by a BSD-style license that can be found
|
|
|
|
|
// in the LICENSE file.
|
2013-01-19 17:48:30 +04:00
|
|
|
|
2016-08-03 15:57:02 +03:00
|
|
|
package prometheus_test
|
2013-01-19 17:48:30 +04:00
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"bytes"
|
2022-02-23 14:22:52 +03:00
|
|
|
"errors"
|
2018-12-06 13:22:18 +03:00
|
|
|
"fmt"
|
2018-10-10 17:59:24 +03:00
|
|
|
"math/rand"
|
2013-01-19 17:48:30 +04:00
|
|
|
"net/http"
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
"net/http/httptest"
|
2018-11-01 09:34:50 +03:00
|
|
|
"os"
|
2018-10-10 17:59:24 +03:00
|
|
|
"sync"
|
2013-01-19 17:48:30 +04:00
|
|
|
"testing"
|
2018-10-10 17:59:24 +03:00
|
|
|
"time"
|
2013-06-27 20:46:16 +04:00
|
|
|
|
2016-08-03 15:57:02 +03:00
|
|
|
"github.com/prometheus/client_golang/prometheus"
|
|
|
|
|
"github.com/prometheus/client_golang/prometheus/promhttp"
|
2022-12-22 18:14:00 +03:00
|
|
|
|
|
|
|
|
dto "github.com/prometheus/client_model/go"
|
|
|
|
|
"github.com/prometheus/common/expfmt"
|
|
|
|
|
"google.golang.org/protobuf/proto"
|
2013-01-19 17:48:30 +04:00
|
|
|
)
|
|
|
|
|
|
2018-07-09 02:03:22 +03:00
|
|
|
// uncheckedCollector wraps a Collector but its Describe method yields no Desc.
|
|
|
|
|
type uncheckedCollector struct {
|
|
|
|
|
c prometheus.Collector
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (u uncheckedCollector) Describe(_ chan<- *prometheus.Desc) {}
|
|
|
|
|
func (u uncheckedCollector) Collect(c chan<- prometheus.Metric) {
|
|
|
|
|
u.c.Collect(c)
|
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
func testHandler(t testing.TB) {
|
2018-07-09 02:03:22 +03:00
|
|
|
// TODO(beorn7): This test is a bit too "end-to-end". It tests quite a
|
|
|
|
|
// few moving parts that are not strongly coupled. They could/should be
|
2019-05-17 00:35:36 +03:00
|
|
|
// tested separately. However, the changes planned for v2 will
|
2018-07-09 02:03:22 +03:00
|
|
|
// require a major rework of this test anyway, at which time I will
|
|
|
|
|
// structure it in a better way.
|
2014-04-02 15:31:22 +04:00
|
|
|
|
2016-08-03 15:57:02 +03:00
|
|
|
metricVec := prometheus.NewCounterVec(
|
|
|
|
|
prometheus.CounterOpts{
|
2014-05-07 22:08:33 +04:00
|
|
|
Name: "name",
|
|
|
|
|
Help: "docstring",
|
2016-08-03 15:57:02 +03:00
|
|
|
ConstLabels: prometheus.Labels{"constname": "constvalue"},
|
2014-05-07 22:08:33 +04:00
|
|
|
},
|
|
|
|
|
[]string{"labelname"},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
metricVec.WithLabelValues("val1").Inc()
|
|
|
|
|
metricVec.WithLabelValues("val2").Inc()
|
2014-04-02 15:31:22 +04:00
|
|
|
|
2015-03-15 17:47:56 +03:00
|
|
|
externalMetricFamily := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("externalname"),
|
|
|
|
|
Help: proto.String("externaldocstring"),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Label: []*dto.LabelPair{
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("externalconstname"),
|
|
|
|
|
Value: proto.String("externalconstvalue"),
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2015-06-08 23:12:07 +03:00
|
|
|
{
|
|
|
|
|
Name: proto.String("externallabelname"),
|
|
|
|
|
Value: proto.String("externalval1"),
|
|
|
|
|
},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(1),
|
|
|
|
|
},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
externalBuf := &bytes.Buffer{}
|
|
|
|
|
enc := expfmt.NewEncoder(externalBuf, expfmt.FmtProtoDelim)
|
|
|
|
|
if err := enc.Encode(externalMetricFamily); err != nil {
|
2014-04-02 15:31:22 +04:00
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
externalMetricFamilyAsBytes := externalBuf.Bytes()
|
2014-04-23 15:40:37 +04:00
|
|
|
externalMetricFamilyAsText := []byte(`# HELP externalname externaldocstring
|
|
|
|
|
# TYPE externalname counter
|
2019-01-28 01:18:44 +03:00
|
|
|
externalname{externalconstname="externalconstvalue",externallabelname="externalval1"} 1
|
2014-04-23 15:40:37 +04:00
|
|
|
`)
|
|
|
|
|
externalMetricFamilyAsProtoText := []byte(`name: "externalname"
|
|
|
|
|
help: "externaldocstring"
|
|
|
|
|
type: COUNTER
|
|
|
|
|
metric: <
|
|
|
|
|
label: <
|
2014-05-07 22:08:33 +04:00
|
|
|
name: "externalconstname"
|
|
|
|
|
value: "externalconstvalue"
|
2014-04-23 15:40:37 +04:00
|
|
|
>
|
2015-06-08 23:12:07 +03:00
|
|
|
label: <
|
|
|
|
|
name: "externallabelname"
|
|
|
|
|
value: "externalval1"
|
|
|
|
|
>
|
2014-04-23 15:40:37 +04:00
|
|
|
counter: <
|
|
|
|
|
value: 1
|
|
|
|
|
>
|
|
|
|
|
>
|
|
|
|
|
|
|
|
|
|
`)
|
2022-08-03 07:30:51 +03:00
|
|
|
externalMetricFamilyAsProtoCompactText := []byte(`name:"externalname" help:"externaldocstring" type:COUNTER metric:<label:<name:"externalconstname" value:"externalconstvalue" > label:<name:"externallabelname" value:"externalval1" > counter:<value:1 > >`)
|
|
|
|
|
externalMetricFamilyAsProtoCompactText = append(externalMetricFamilyAsProtoCompactText, []byte(" \n")...)
|
2014-04-02 15:31:22 +04:00
|
|
|
|
|
|
|
|
expectedMetricFamily := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("name"),
|
|
|
|
|
Help: proto.String("docstring"),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-04-02 15:31:22 +04:00
|
|
|
Label: []*dto.LabelPair{
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-05-07 22:08:33 +04:00
|
|
|
Name: proto.String("constname"),
|
|
|
|
|
Value: proto.String("constvalue"),
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-05-07 22:08:33 +04:00
|
|
|
Name: proto.String("labelname"),
|
|
|
|
|
Value: proto.String("val1"),
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(1),
|
|
|
|
|
},
|
|
|
|
|
},
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-04-02 15:31:22 +04:00
|
|
|
Label: []*dto.LabelPair{
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-05-07 22:08:33 +04:00
|
|
|
Name: proto.String("constname"),
|
|
|
|
|
Value: proto.String("constvalue"),
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-14 20:45:16 +04:00
|
|
|
{
|
2014-05-07 22:08:33 +04:00
|
|
|
Name: proto.String("labelname"),
|
|
|
|
|
Value: proto.String("val2"),
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(1),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
buf := &bytes.Buffer{}
|
|
|
|
|
enc = expfmt.NewEncoder(buf, expfmt.FmtProtoDelim)
|
|
|
|
|
if err := enc.Encode(expectedMetricFamily); err != nil {
|
2014-04-02 15:31:22 +04:00
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
expectedMetricFamilyAsBytes := buf.Bytes()
|
2014-04-23 15:40:37 +04:00
|
|
|
expectedMetricFamilyAsText := []byte(`# HELP name docstring
|
|
|
|
|
# TYPE name counter
|
2019-01-28 01:18:44 +03:00
|
|
|
name{constname="constvalue",labelname="val1"} 1
|
|
|
|
|
name{constname="constvalue",labelname="val2"} 1
|
2014-04-23 15:40:37 +04:00
|
|
|
`)
|
|
|
|
|
expectedMetricFamilyAsProtoText := []byte(`name: "name"
|
|
|
|
|
help: "docstring"
|
|
|
|
|
type: COUNTER
|
|
|
|
|
metric: <
|
|
|
|
|
label: <
|
2014-05-07 22:08:33 +04:00
|
|
|
name: "constname"
|
|
|
|
|
value: "constvalue"
|
2014-04-23 15:40:37 +04:00
|
|
|
>
|
|
|
|
|
label: <
|
2014-05-07 22:08:33 +04:00
|
|
|
name: "labelname"
|
|
|
|
|
value: "val1"
|
2014-04-23 15:40:37 +04:00
|
|
|
>
|
|
|
|
|
counter: <
|
|
|
|
|
value: 1
|
|
|
|
|
>
|
|
|
|
|
>
|
|
|
|
|
metric: <
|
|
|
|
|
label: <
|
2014-05-07 22:08:33 +04:00
|
|
|
name: "constname"
|
|
|
|
|
value: "constvalue"
|
2014-04-23 15:40:37 +04:00
|
|
|
>
|
|
|
|
|
label: <
|
2014-05-07 22:08:33 +04:00
|
|
|
name: "labelname"
|
|
|
|
|
value: "val2"
|
2014-04-23 15:40:37 +04:00
|
|
|
>
|
|
|
|
|
counter: <
|
|
|
|
|
value: 1
|
|
|
|
|
>
|
|
|
|
|
>
|
|
|
|
|
|
|
|
|
|
`)
|
2022-08-03 07:30:51 +03:00
|
|
|
expectedMetricFamilyAsProtoCompactText := []byte(`name:"name" help:"docstring" type:COUNTER metric:<label:<name:"constname" value:"constvalue" > label:<name:"labelname" value:"val1" > counter:<value:1 > > metric:<label:<name:"constname" value:"constvalue" > label:<name:"labelname" value:"val2" > counter:<value:1 > >`)
|
|
|
|
|
expectedMetricFamilyAsProtoCompactText = append(expectedMetricFamilyAsProtoCompactText, []byte(" \n")...)
|
2014-04-02 15:31:22 +04:00
|
|
|
|
2015-03-15 17:47:56 +03:00
|
|
|
externalMetricFamilyWithSameName := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("name"),
|
2016-08-05 15:57:49 +03:00
|
|
|
Help: proto.String("docstring"),
|
2015-03-15 17:47:56 +03:00
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Label: []*dto.LabelPair{
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("constname"),
|
|
|
|
|
Value: proto.String("constvalue"),
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("labelname"),
|
|
|
|
|
Value: proto.String("different_val"),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(42),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
|
2022-08-03 07:30:51 +03:00
|
|
|
expectedMetricFamilyMergedWithExternalAsProtoCompactText := []byte(`name:"name" help:"docstring" type:COUNTER metric:<label:<name:"constname" value:"constvalue" > label:<name:"labelname" value:"different_val" > counter:<value:42 > > metric:<label:<name:"constname" value:"constvalue" > label:<name:"labelname" value:"val1" > counter:<value:1 > > metric:<label:<name:"constname" value:"constvalue" > label:<name:"labelname" value:"val2" > counter:<value:1 > >`)
|
|
|
|
|
expectedMetricFamilyMergedWithExternalAsProtoCompactText = append(expectedMetricFamilyMergedWithExternalAsProtoCompactText, []byte(" \n")...)
|
2015-03-15 17:47:56 +03:00
|
|
|
|
2017-08-20 01:07:21 +03:00
|
|
|
externalMetricFamilyWithInvalidLabelValue := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("name"),
|
|
|
|
|
Help: proto.String("docstring"),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Label: []*dto.LabelPair{
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("constname"),
|
|
|
|
|
Value: proto.String("\xFF"),
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("labelname"),
|
|
|
|
|
Value: proto.String("different_val"),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(42),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
|
2018-10-20 02:28:16 +03:00
|
|
|
expectedMetricFamilyInvalidLabelValueAsText := []byte(`An error has occurred while serving metrics:
|
2017-08-20 01:07:21 +03:00
|
|
|
|
2018-07-13 15:14:39 +03:00
|
|
|
collected metric "name" { label:<name:"constname" value:"\377" > label:<name:"labelname" value:"different_val" > counter:<value:42 > } has a label named "constname" whose value is not utf8: "\xff"
|
2018-07-13 17:29:17 +03:00
|
|
|
`)
|
|
|
|
|
|
|
|
|
|
summary := prometheus.NewSummary(prometheus.SummaryOpts{
|
2019-06-11 15:37:57 +03:00
|
|
|
Name: "complex",
|
|
|
|
|
Help: "A metric to check collisions with _sum and _count.",
|
|
|
|
|
Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
|
2018-07-13 17:29:17 +03:00
|
|
|
})
|
|
|
|
|
summaryAsText := []byte(`# HELP complex A metric to check collisions with _sum and _count.
|
|
|
|
|
# TYPE complex summary
|
|
|
|
|
complex{quantile="0.5"} NaN
|
|
|
|
|
complex{quantile="0.9"} NaN
|
|
|
|
|
complex{quantile="0.99"} NaN
|
2019-01-28 01:18:44 +03:00
|
|
|
complex_sum 0
|
|
|
|
|
complex_count 0
|
2018-07-13 17:29:17 +03:00
|
|
|
`)
|
|
|
|
|
histogram := prometheus.NewHistogram(prometheus.HistogramOpts{
|
|
|
|
|
Name: "complex",
|
|
|
|
|
Help: "A metric to check collisions with _sun, _count, and _bucket.",
|
|
|
|
|
})
|
|
|
|
|
externalMetricFamilyWithBucketSuffix := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("complex_bucket"),
|
|
|
|
|
Help: proto.String("externaldocstring"),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(1),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
externalMetricFamilyWithBucketSuffixAsText := []byte(`# HELP complex_bucket externaldocstring
|
|
|
|
|
# TYPE complex_bucket counter
|
2019-01-28 01:18:44 +03:00
|
|
|
complex_bucket 1
|
2018-07-13 17:29:17 +03:00
|
|
|
`)
|
|
|
|
|
externalMetricFamilyWithCountSuffix := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("complex_count"),
|
|
|
|
|
Help: proto.String("externaldocstring"),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(1),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
2018-10-20 02:28:16 +03:00
|
|
|
bucketCollisionMsg := []byte(`An error has occurred while serving metrics:
|
2018-07-13 17:29:17 +03:00
|
|
|
|
|
|
|
|
collected metric named "complex_bucket" collides with previously collected histogram named "complex"
|
|
|
|
|
`)
|
2018-10-20 02:28:16 +03:00
|
|
|
summaryCountCollisionMsg := []byte(`An error has occurred while serving metrics:
|
2018-07-13 17:29:17 +03:00
|
|
|
|
|
|
|
|
collected metric named "complex_count" collides with previously collected summary named "complex"
|
|
|
|
|
`)
|
2018-10-20 02:28:16 +03:00
|
|
|
histogramCountCollisionMsg := []byte(`An error has occurred while serving metrics:
|
2018-07-13 17:29:17 +03:00
|
|
|
|
|
|
|
|
collected metric named "complex_count" collides with previously collected histogram named "complex"
|
2017-08-20 01:07:21 +03:00
|
|
|
`)
|
2018-09-30 11:38:57 +03:00
|
|
|
externalMetricFamilyWithDuplicateLabel := &dto.MetricFamily{
|
|
|
|
|
Name: proto.String("broken_metric"),
|
|
|
|
|
Help: proto.String("The registry should detect the duplicate label."),
|
|
|
|
|
Type: dto.MetricType_COUNTER.Enum(),
|
|
|
|
|
Metric: []*dto.Metric{
|
|
|
|
|
{
|
|
|
|
|
Label: []*dto.LabelPair{
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("foo"),
|
|
|
|
|
Value: proto.String("bar"),
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
Name: proto.String("foo"),
|
|
|
|
|
Value: proto.String("baz"),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
Counter: &dto.Counter{
|
|
|
|
|
Value: proto.Float64(2.7),
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
}
|
2018-10-20 02:28:16 +03:00
|
|
|
duplicateLabelMsg := []byte(`An error has occurred while serving metrics:
|
2018-09-30 16:37:40 +03:00
|
|
|
|
|
|
|
|
collected metric "broken_metric" { label:<name:"foo" value:"bar" > label:<name:"foo" value:"baz" > counter:<value:2.7 > } has two or more labels with the same name: foo
|
|
|
|
|
`)
|
2017-08-20 01:07:21 +03:00
|
|
|
|
2014-04-02 15:31:22 +04:00
|
|
|
type output struct {
|
|
|
|
|
headers map[string]string
|
|
|
|
|
body []byte
|
|
|
|
|
}
|
|
|
|
|
|
2022-06-17 10:04:06 +03:00
|
|
|
scenarios := []struct {
|
2015-03-15 17:47:56 +03:00
|
|
|
headers map[string]string
|
|
|
|
|
out output
|
2016-08-03 15:57:02 +03:00
|
|
|
collector prometheus.Collector
|
2015-03-15 17:47:56 +03:00
|
|
|
externalMF []*dto.MetricFamily
|
2014-04-02 15:31:22 +04:00
|
|
|
}{
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 0
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "foo/bar;q=0.2, dings/bums;q=0.8",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-05-07 22:08:33 +04:00
|
|
|
body: []byte{},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 1
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "foo/bar;q=0.2, application/quark;q=0.8",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-05-07 22:08:33 +04:00
|
|
|
body: []byte{},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 2
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "foo/bar;q=0.2, application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=bla;q=0.8",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-05-07 22:08:33 +04:00
|
|
|
body: []byte{},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 3
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
2014-04-23 15:40:37 +04:00
|
|
|
"Accept": "text/plain;q=0.2, application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.8",
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
body: []byte{},
|
|
|
|
|
},
|
|
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 4
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/json",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-05-07 22:08:33 +04:00
|
|
|
body: expectedMetricFamilyAsText,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 5
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
body: expectedMetricFamilyAsBytes,
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 6
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/json",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-05-07 22:08:33 +04:00
|
|
|
body: externalMetricFamilyAsText,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 7
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
body: externalMetricFamilyAsBytes,
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 8
|
2014-04-02 15:31:22 +04:00
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited`,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsBytes,
|
2014-05-07 22:08:33 +04:00
|
|
|
expectedMetricFamilyAsBytes,
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-02 15:31:22 +04:00
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
{ // 9
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: []byte{},
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{ // 10
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=bla;q=0.2, text/plain;q=0.5",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: expectedMetricFamilyAsText,
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
{ // 11
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=bla;q=0.2, text/plain;q=0.5;version=0.0.4",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-03-19 16:04:12 +03:00
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsText,
|
2014-05-07 22:08:33 +04:00
|
|
|
expectedMetricFamilyAsText,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
{ // 12
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.2, text/plain;q=0.5;version=0.0.2",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsBytes,
|
2014-05-07 22:08:33 +04:00
|
|
|
expectedMetricFamilyAsBytes,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
{ // 13
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=text;q=0.5, application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.4",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=text`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsProtoText,
|
2014-05-07 22:08:33 +04:00
|
|
|
expectedMetricFamilyAsProtoText,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
{ // 14
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=compact-text",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2014-07-15 17:34:52 +04:00
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=compact-text`,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsProtoCompactText,
|
2014-05-07 22:08:33 +04:00
|
|
|
expectedMetricFamilyAsProtoCompactText,
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
2015-03-15 17:47:56 +03:00
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{externalMetricFamily},
|
|
|
|
|
},
|
|
|
|
|
{ // 15
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=compact-text",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=compact-text`,
|
|
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
externalMetricFamilyAsProtoCompactText,
|
|
|
|
|
expectedMetricFamilyMergedWithExternalAsProtoCompactText,
|
|
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
|
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamily,
|
|
|
|
|
externalMetricFamilyWithSameName,
|
|
|
|
|
},
|
2014-04-23 15:40:37 +04:00
|
|
|
},
|
2017-08-20 01:07:21 +03:00
|
|
|
{ // 16
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=compact-text",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: expectedMetricFamilyInvalidLabelValueAsText,
|
|
|
|
|
},
|
|
|
|
|
collector: metricVec,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamily,
|
|
|
|
|
externalMetricFamilyWithInvalidLabelValue,
|
|
|
|
|
},
|
|
|
|
|
},
|
2018-07-09 02:03:22 +03:00
|
|
|
{ // 17
|
|
|
|
|
headers: map[string]string{
|
2018-07-13 17:29:17 +03:00
|
|
|
"Accept": "text/plain",
|
2018-07-09 02:03:22 +03:00
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: expectedMetricFamilyAsText,
|
|
|
|
|
},
|
|
|
|
|
collector: uncheckedCollector{metricVec},
|
|
|
|
|
},
|
2018-07-13 17:29:17 +03:00
|
|
|
{ // 18
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: histogramCountCollisionMsg,
|
|
|
|
|
},
|
|
|
|
|
collector: histogram,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamilyWithCountSuffix,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{ // 19
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: bucketCollisionMsg,
|
|
|
|
|
},
|
|
|
|
|
collector: histogram,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamilyWithBucketSuffix,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{ // 20
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: summaryCountCollisionMsg,
|
|
|
|
|
},
|
|
|
|
|
collector: summary,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamilyWithCountSuffix,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{ // 21
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Content-Type": `text/plain; version=0.0.4; charset=utf-8`,
|
|
|
|
|
},
|
|
|
|
|
body: bytes.Join(
|
|
|
|
|
[][]byte{
|
|
|
|
|
summaryAsText,
|
|
|
|
|
externalMetricFamilyWithBucketSuffixAsText,
|
|
|
|
|
},
|
|
|
|
|
[]byte{},
|
|
|
|
|
),
|
|
|
|
|
},
|
|
|
|
|
collector: summary,
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamilyWithBucketSuffix,
|
|
|
|
|
},
|
|
|
|
|
},
|
2018-09-30 11:38:57 +03:00
|
|
|
{ // 22
|
|
|
|
|
headers: map[string]string{
|
|
|
|
|
"Accept": "text/plain",
|
|
|
|
|
},
|
|
|
|
|
out: output{
|
|
|
|
|
headers: map[string]string{
|
2018-09-30 16:37:40 +03:00
|
|
|
"Content-Type": `text/plain; charset=utf-8`,
|
2018-09-30 11:38:57 +03:00
|
|
|
},
|
|
|
|
|
body: duplicateLabelMsg,
|
|
|
|
|
},
|
|
|
|
|
externalMF: []*dto.MetricFamily{
|
|
|
|
|
externalMetricFamilyWithDuplicateLabel,
|
|
|
|
|
},
|
|
|
|
|
},
|
2014-04-02 15:31:22 +04:00
|
|
|
}
|
|
|
|
|
for i, scenario := range scenarios {
|
2016-08-03 15:57:02 +03:00
|
|
|
registry := prometheus.NewPedanticRegistry()
|
2016-08-05 15:57:49 +03:00
|
|
|
gatherer := prometheus.Gatherer(registry)
|
2015-03-15 17:47:56 +03:00
|
|
|
if scenario.externalMF != nil {
|
2016-08-05 15:57:49 +03:00
|
|
|
gatherer = prometheus.Gatherers{
|
|
|
|
|
registry,
|
|
|
|
|
prometheus.GathererFunc(func() ([]*dto.MetricFamily, error) {
|
|
|
|
|
return scenario.externalMF, nil
|
|
|
|
|
}),
|
|
|
|
|
}
|
2014-04-02 15:31:22 +04:00
|
|
|
}
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
|
|
|
|
|
if scenario.collector != nil {
|
2018-07-09 02:03:22 +03:00
|
|
|
registry.MustRegister(scenario.collector)
|
2014-04-02 15:31:22 +04:00
|
|
|
}
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
writer := httptest.NewRecorder()
|
2019-06-11 15:37:57 +03:00
|
|
|
handler := promhttp.HandlerFor(gatherer, promhttp.HandlerOpts{})
|
2014-04-02 15:31:22 +04:00
|
|
|
request, _ := http.NewRequest("GET", "/", nil)
|
|
|
|
|
for key, value := range scenario.headers {
|
|
|
|
|
request.Header.Add(key, value)
|
|
|
|
|
}
|
2019-06-11 15:37:57 +03:00
|
|
|
handler.ServeHTTP(writer, request)
|
2014-04-02 15:31:22 +04:00
|
|
|
|
|
|
|
|
for key, value := range scenario.out.headers {
|
2018-09-19 14:30:14 +03:00
|
|
|
if writer.Header().Get(key) != value {
|
2014-04-02 15:31:22 +04:00
|
|
|
t.Errorf(
|
|
|
|
|
"%d. expected %q for header %q, got %q",
|
|
|
|
|
i, value, key, writer.Header().Get(key),
|
|
|
|
|
)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
if !bytes.Equal(scenario.out.body, writer.Body.Bytes()) {
|
2014-04-02 15:31:22 +04:00
|
|
|
t.Errorf(
|
2016-08-05 15:57:49 +03:00
|
|
|
"%d. expected body:\n%s\ngot body:\n%s\n",
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
i, scenario.out.body, writer.Body.Bytes(),
|
2014-04-02 15:31:22 +04:00
|
|
|
)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
func TestHandler(t *testing.T) {
|
2014-04-02 15:31:22 +04:00
|
|
|
testHandler(t)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func BenchmarkHandler(b *testing.B) {
|
|
|
|
|
for i := 0; i < b.N; i++ {
|
|
|
|
|
testHandler(b)
|
|
|
|
|
}
|
|
|
|
|
}
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
|
2018-10-10 16:41:21 +03:00
|
|
|
func TestAlreadyRegistered(t *testing.T) {
|
2016-08-03 15:57:02 +03:00
|
|
|
original := prometheus.NewCounterVec(
|
2019-06-14 17:16:15 +03:00
|
|
|
prometheus.CounterOpts{
|
|
|
|
|
Name: "test",
|
|
|
|
|
Help: "help",
|
|
|
|
|
ConstLabels: prometheus.Labels{"const": "label"},
|
|
|
|
|
},
|
|
|
|
|
[]string{"foo", "bar"},
|
|
|
|
|
)
|
|
|
|
|
equalButNotSame := prometheus.NewCounterVec(
|
|
|
|
|
prometheus.CounterOpts{
|
|
|
|
|
Name: "test",
|
|
|
|
|
Help: "help",
|
|
|
|
|
ConstLabels: prometheus.Labels{"const": "label"},
|
|
|
|
|
},
|
|
|
|
|
[]string{"foo", "bar"},
|
|
|
|
|
)
|
|
|
|
|
originalWithoutConstLabel := prometheus.NewCounterVec(
|
2016-08-03 15:57:02 +03:00
|
|
|
prometheus.CounterOpts{
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
Name: "test",
|
|
|
|
|
Help: "help",
|
|
|
|
|
},
|
|
|
|
|
[]string{"foo", "bar"},
|
|
|
|
|
)
|
2019-06-14 17:16:15 +03:00
|
|
|
equalButNotSameWithoutConstLabel := prometheus.NewCounterVec(
|
2016-08-03 15:57:02 +03:00
|
|
|
prometheus.CounterOpts{
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
Name: "test",
|
|
|
|
|
Help: "help",
|
|
|
|
|
},
|
|
|
|
|
[]string{"foo", "bar"},
|
|
|
|
|
)
|
2019-06-14 17:16:15 +03:00
|
|
|
|
|
|
|
|
scenarios := []struct {
|
|
|
|
|
name string
|
|
|
|
|
originalCollector prometheus.Collector
|
|
|
|
|
registerWith func(prometheus.Registerer) prometheus.Registerer
|
|
|
|
|
newCollector prometheus.Collector
|
|
|
|
|
reRegisterWith func(prometheus.Registerer) prometheus.Registerer
|
|
|
|
|
}{
|
|
|
|
|
{
|
|
|
|
|
"RegisterNormallyReregisterNormally",
|
|
|
|
|
original,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer { return r },
|
|
|
|
|
equalButNotSame,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer { return r },
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"RegisterNormallyReregisterWrapped",
|
|
|
|
|
original,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer { return r },
|
|
|
|
|
equalButNotSameWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r)
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"RegisterWrappedReregisterWrapped",
|
|
|
|
|
originalWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r)
|
|
|
|
|
},
|
|
|
|
|
equalButNotSameWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r)
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"RegisterWrappedReregisterNormally",
|
|
|
|
|
originalWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r)
|
|
|
|
|
},
|
|
|
|
|
equalButNotSame,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer { return r },
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"RegisterDoublyWrappedReregisterDoublyWrapped",
|
|
|
|
|
originalWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWithPrefix(
|
|
|
|
|
"wrap_",
|
|
|
|
|
prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r),
|
|
|
|
|
)
|
|
|
|
|
},
|
|
|
|
|
equalButNotSameWithoutConstLabel,
|
|
|
|
|
func(r prometheus.Registerer) prometheus.Registerer {
|
|
|
|
|
return prometheus.WrapRegistererWithPrefix(
|
|
|
|
|
"wrap_",
|
|
|
|
|
prometheus.WrapRegistererWith(prometheus.Labels{"const": "label"}, r),
|
|
|
|
|
)
|
|
|
|
|
},
|
|
|
|
|
},
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
}
|
2019-06-14 17:16:15 +03:00
|
|
|
|
|
|
|
|
for _, s := range scenarios {
|
|
|
|
|
t.Run(s.name, func(t *testing.T) {
|
|
|
|
|
var err error
|
|
|
|
|
reg := prometheus.NewRegistry()
|
|
|
|
|
if err = s.registerWith(reg).Register(s.originalCollector); err != nil {
|
|
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
if err = s.reRegisterWith(reg).Register(s.newCollector); err == nil {
|
|
|
|
|
t.Fatal("expected error when registering new collector")
|
|
|
|
|
}
|
2022-08-03 07:30:51 +03:00
|
|
|
are := &prometheus.AlreadyRegisteredError{}
|
|
|
|
|
if errors.As(err, are) {
|
2019-06-14 17:16:15 +03:00
|
|
|
if are.ExistingCollector != s.originalCollector {
|
|
|
|
|
t.Error("expected original collector but got something else")
|
|
|
|
|
}
|
|
|
|
|
if are.ExistingCollector == s.newCollector {
|
|
|
|
|
t.Error("expected original collector but got new one")
|
|
|
|
|
}
|
|
|
|
|
} else {
|
|
|
|
|
t.Error("unexpected error:", err)
|
|
|
|
|
}
|
|
|
|
|
})
|
Create a public registry interface and separate out HTTP exposition
General context and approch
===========================
This is the first part of the long awaited wider refurbishment of
`client_golang/prometheus/...`. After a lot of struggling, I decided
to not go for one breaking big-bang, but cut things into smaller steps
after all, mostly to keep the changes manageable and easy to
review. I'm aiming for having the invasive breaking changes
concentrated in as few steps as possible (ideally one). Some steps
will not be breaking at all, but typically there will be breaking
changes that only affect quite special cases so that 95+% of users
will not be affected. This first step is an example for that, see
details below.
What's happening in this commit?
================================
This step is about finally creating an exported registry
interface. This could not be done by simply export the existing
internal implementation because the interface would be _way_ too
fat. This commit introduces a qutie lean `Registry` interface
(compared to the previous interval implementation). The functions that
act on the default registry are retained (with very few exceptions) so
that most use cases won't see a change. However, several of those are
deprecated now to clean up the namespace in the future.
The default registry is kept in the public variable
`DefaultRegistry`. This follows the example of the http package in the
standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`)
with the same implications. (This pattern is somewhat disputed within
the Go community but I chose to go with the devil you know instead of
creating something more complex or even disallowing any changes to the
default registry. The current approach gives everybody the freedom to
not touch DefaultRegistry or to do everything with a custom registry
to play save.)
Another important part in making the registry lean is the extraction
of the HTTP exposition, which also allows for customization of the
HTTP exposition. Note that the separation of metric collection and
exposition has the side effect that managing the MetricFamily and
Metric protobuf objects in a free-list or pool isn't really feasible
anymore. By now (with better GC in more recent Go versions), the
returns were anyway dimisishing. To be effective at all, scrapes had
to happen more often than GC cycles, and even then most elements of
the protobufs (everything excetp the MetricFamily and Metric structs
themselves) would still cause allocation churn. In a future breaking
change, the signature of the Write method in the Metric interface will
be adjusted accordingly. In this commit, avoiding breakage is more
important.
The following issues are fixed by this commit (some solved "on the
fly" now that I was touching the code anyway and it would have been
stupid to port the bugs):
https://github.com/prometheus/client_golang/issues/46
https://github.com/prometheus/client_golang/issues/100
https://github.com/prometheus/client_golang/issues/170
https://github.com/prometheus/client_golang/issues/205
Documentation including examples have been amended as required.
What future changes does this commit enable?
============================================
The following items are not yet implemented, but this commit opens the
possibility of implementing these independently.
- The separation of the HTTP exposition allows the implementation of
other exposition methods based on the Registry interface, as known
from other Prometheus client libraries, e.g. sending the metrics to
Graphite.
Cf. https://github.com/prometheus/client_golang/issues/197
- The public `Registry` interface allows the implementation of
convenience tools for testing metrics collection. Those tools can
inspect the collected MetricFamily protobufs and compare them to
expectation. Also, tests can use their own testing instance of a
registry.
Cf. https://github.com/prometheus/client_golang/issues/58
Notable non-goals of this commit
================================
Non-goals that will be tackled later
------------------------------------
The following two issues are quite closely connected to the changes in
this commit but the line has been drawn deliberately to address them
in later steps of the refurbishment:
- `InstrumentHandler` has many known problems. The plan is to create a
saner way to conveniently intrument HTTP handlers and remove the old
`InstrumentHandler` altogether. To keep breakage low for now, even
the default handler to expose metrics is still using the old
`InstrumentHandler`. This leads to weird naming inconsistencies but
I have deemed it better to not break the world right now but do it
in the change that provides better ways of instrumenting HTTP
handlers.
Cf. https://github.com/prometheus/client_golang/issues/200
- There is work underway to make the whole handling of metric
descriptors (`Desc`) more intuitive and transparent for the user
(including an ability for less strict checking,
cf. https://github.com/prometheus/client_golang/issues/47). That's
quite invasive from the perspective of the internal code, namely the
registry. I deliberately kept those changes out of this commit.
- While this commit adds new external dependency, the effort to vendor
anything within the library that is not visible in any exported
types will have to be done later.
Non-goals that _might_ be tackled later
---------------------------------------
There is a strong and understandable urge to divide the `prometheus`
package into a number of sub-packages (like `registry`, `collectors`,
`http`, `metrics`, …). However, to not run into a multitude of
circular import chains, this would need to break every single existing
usage of the library. (As just one example, if the ubiquitious
`prometheus.MustRegister` (with more than 2,000 uses on GitHub alone)
is kept in the `prometheus` package, but the other registry concerns
go into a new `registry` package, then the `prometheus` package would
import the `registry` package (to call the actual register method),
while at the same time the `registry` package needs to import the
`prometheus` package to access `Collector`, `Metric`, `Desc` and
more. If we moved `MustRegister` into the `registry` package,
thousands of code lines would have to be fixed (which would be easy if
the world was a mono repo, but it is not). If we moved everything else
the proposed registry package needs into packages of their own, we
would break thousands of other code lines.)
The main problem is really the top-level functions like
`MustRegister`, `Handler`, …, which effectively pull everything into
one package. Those functions are however very convenient for the easy
and very frequent use-cases.
This problem has to be revisited later.
For now, I'm trying to keep the amount of exported names in the
package as low as possible (e.g. I unexported expvarCollector in this
commit because the NewExpvarCollector constructor is enough to export,
and it is now consistent with other collectors, like the goCollector).
Non-goals that won't be tackled anytime soon
--------------------------------------------
Something that I have played with a lot is "streaming collection",
i.e. allow an implementation of the `Registry` interface that collects
metrics incrementally and serves them while doing so. As it has turned
out, this has many many issues and makes the `Registry` interface very
clunky. Eventually, I made the call that it is unlikely we will really
implement streaming collection; and making the interface more clunky
for something that might not even happen is really a big no-no. Note
that the `Registry` interface only creates the in-memory
representation of the metric family protobufs in one go. The
serializaton onto the wire can still be handled in a streaming fashion
(which hasn't been done so far, without causing any trouble, but might
be done in the future without breaking any interfaces).
What are the breaking changes?
==============================
- Signatures of functions pushing to Pushgateway have changed to allow
arbitrary grouping (which was planned for a long time anyway, and
now that I had to work on the Push code anyway for the registry
refurbishment, I finally did it,
cf. https://github.com/prometheus/client_golang/issues/100).
With the gained insight that pushing to the default registry is almost
never the right thing, and now that we are breaking the Push call
anyway, all the Push functions were moved to their own package,
which cleans up the namespace and is more idiomatic (pushing
Collectors is now literally done by `push.Collectors(...)`).
- The registry is doing more consistency checks by default now. Past
creators of inconsistent metrics could have masked the problem by
not setting `EnableCollectChecks`. Those inconsistencies will now be
detected. (But note that a "best effort" metrics collection is now
possible with `HandlerOpts.ErrorHandling = ContinueOnError`.)
- `EnableCollectChecks` is gone. The registry is now performing some
of those checks anyway (see previous item), and a registry with all
of those checks can now be created with `NewPedanticRegistry` (only
used for testing).
- `PanicOnCollectError` is gone. This behavior can now be configured
when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
|
|
|
}
|
|
|
|
|
}
|
2018-10-10 17:59:24 +03:00
|
|
|
|
2019-10-17 13:34:06 +03:00
|
|
|
// TestRegisterUnregisterCollector ensures registering and unregistering a
|
|
|
|
|
// collector doesn't leave any dangling metrics.
|
|
|
|
|
// We use NewGoCollector as a nice concrete example of a collector with
|
|
|
|
|
// multiple metrics.
|
|
|
|
|
func TestRegisterUnregisterCollector(t *testing.T) {
|
|
|
|
|
col := prometheus.NewGoCollector()
|
|
|
|
|
|
|
|
|
|
reg := prometheus.NewRegistry()
|
|
|
|
|
reg.MustRegister(col)
|
|
|
|
|
reg.Unregister(col)
|
|
|
|
|
if metrics, err := reg.Gather(); err != nil {
|
|
|
|
|
t.Error("error gathering sample metric")
|
|
|
|
|
} else if len(metrics) != 0 {
|
|
|
|
|
t.Error("should have unregistered metric")
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2018-10-10 17:59:24 +03:00
|
|
|
// TestHistogramVecRegisterGatherConcurrency is an end-to-end test that
|
|
|
|
|
// concurrently calls Observe on random elements of a HistogramVec while the
|
|
|
|
|
// same HistogramVec is registered concurrently and the Gather method of the
|
|
|
|
|
// registry is called concurrently.
|
|
|
|
|
func TestHistogramVecRegisterGatherConcurrency(t *testing.T) {
|
2018-12-06 13:22:18 +03:00
|
|
|
labelNames := make([]string, 16) // Need at least 13 to expose #512.
|
|
|
|
|
for i := range labelNames {
|
|
|
|
|
labelNames[i] = fmt.Sprint("label_", i)
|
|
|
|
|
}
|
|
|
|
|
|
2018-10-10 17:59:24 +03:00
|
|
|
var (
|
|
|
|
|
reg = prometheus.NewPedanticRegistry()
|
|
|
|
|
hv = prometheus.NewHistogramVec(
|
|
|
|
|
prometheus.HistogramOpts{
|
|
|
|
|
Name: "test_histogram",
|
|
|
|
|
Help: "This helps testing.",
|
|
|
|
|
ConstLabels: prometheus.Labels{"foo": "bar"},
|
|
|
|
|
},
|
2018-12-06 13:22:18 +03:00
|
|
|
labelNames,
|
2018-10-10 17:59:24 +03:00
|
|
|
)
|
|
|
|
|
labelValues = []string{"a", "b", "c", "alpha", "beta", "gamma", "aleph", "beth", "gimel"}
|
|
|
|
|
quit = make(chan struct{})
|
|
|
|
|
wg sync.WaitGroup
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
observe := func() {
|
|
|
|
|
defer wg.Done()
|
|
|
|
|
for {
|
|
|
|
|
select {
|
|
|
|
|
case <-quit:
|
|
|
|
|
return
|
|
|
|
|
default:
|
|
|
|
|
obs := rand.NormFloat64()*.1 + .2
|
2018-12-06 13:22:18 +03:00
|
|
|
values := make([]string, 0, len(labelNames))
|
|
|
|
|
for range labelNames {
|
|
|
|
|
values = append(values, labelValues[rand.Intn(len(labelValues))])
|
|
|
|
|
}
|
|
|
|
|
hv.WithLabelValues(values...).Observe(obs)
|
2018-10-10 17:59:24 +03:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
register := func() {
|
|
|
|
|
defer wg.Done()
|
|
|
|
|
for {
|
|
|
|
|
select {
|
|
|
|
|
case <-quit:
|
|
|
|
|
return
|
|
|
|
|
default:
|
|
|
|
|
if err := reg.Register(hv); err != nil {
|
2022-08-03 07:30:51 +03:00
|
|
|
if !errors.As(err, &prometheus.AlreadyRegisteredError{}) {
|
2018-10-10 17:59:24 +03:00
|
|
|
t.Error("Registering failed:", err)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
time.Sleep(7 * time.Millisecond)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
gather := func() {
|
|
|
|
|
defer wg.Done()
|
|
|
|
|
for {
|
|
|
|
|
select {
|
|
|
|
|
case <-quit:
|
|
|
|
|
return
|
|
|
|
|
default:
|
|
|
|
|
if g, err := reg.Gather(); err != nil {
|
|
|
|
|
t.Error("Gathering failed:", err)
|
|
|
|
|
} else {
|
|
|
|
|
if len(g) == 0 {
|
|
|
|
|
continue
|
|
|
|
|
}
|
|
|
|
|
if len(g) != 1 {
|
|
|
|
|
t.Error("Gathered unexpected number of metric families:", len(g))
|
|
|
|
|
}
|
2018-12-06 13:22:18 +03:00
|
|
|
if len(g[0].Metric[0].Label) != len(labelNames)+1 {
|
2018-10-10 17:59:24 +03:00
|
|
|
t.Error("Gathered unexpected number of label pairs:", len(g[0].Metric[0].Label))
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
time.Sleep(4 * time.Millisecond)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
wg.Add(10)
|
|
|
|
|
go observe()
|
|
|
|
|
go observe()
|
|
|
|
|
go register()
|
|
|
|
|
go observe()
|
|
|
|
|
go gather()
|
|
|
|
|
go observe()
|
|
|
|
|
go register()
|
|
|
|
|
go observe()
|
|
|
|
|
go gather()
|
|
|
|
|
go observe()
|
|
|
|
|
|
|
|
|
|
time.Sleep(time.Second)
|
|
|
|
|
close(quit)
|
|
|
|
|
wg.Wait()
|
|
|
|
|
}
|
2018-11-01 09:34:50 +03:00
|
|
|
|
|
|
|
|
func TestWriteToTextfile(t *testing.T) {
|
|
|
|
|
expectedOut := `# HELP test_counter test counter
|
|
|
|
|
# TYPE test_counter counter
|
2019-01-28 01:18:44 +03:00
|
|
|
test_counter{name="qux"} 1
|
2018-11-01 09:34:50 +03:00
|
|
|
# HELP test_gauge test gauge
|
|
|
|
|
# TYPE test_gauge gauge
|
|
|
|
|
test_gauge{name="baz"} 1.1
|
|
|
|
|
# HELP test_hist test histogram
|
|
|
|
|
# TYPE test_hist histogram
|
2019-01-28 01:18:44 +03:00
|
|
|
test_hist_bucket{name="bar",le="0.005"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.01"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.025"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.05"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.1"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.25"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="0.5"} 0
|
|
|
|
|
test_hist_bucket{name="bar",le="1"} 1
|
|
|
|
|
test_hist_bucket{name="bar",le="2.5"} 1
|
|
|
|
|
test_hist_bucket{name="bar",le="5"} 2
|
|
|
|
|
test_hist_bucket{name="bar",le="10"} 2
|
|
|
|
|
test_hist_bucket{name="bar",le="+Inf"} 2
|
2018-11-01 09:34:50 +03:00
|
|
|
test_hist_sum{name="bar"} 3.64
|
2019-01-28 01:18:44 +03:00
|
|
|
test_hist_count{name="bar"} 2
|
2018-11-01 09:34:50 +03:00
|
|
|
# HELP test_summary test summary
|
|
|
|
|
# TYPE test_summary summary
|
2019-01-28 01:18:44 +03:00
|
|
|
test_summary{name="foo",quantile="0.5"} 10
|
|
|
|
|
test_summary{name="foo",quantile="0.9"} 20
|
|
|
|
|
test_summary{name="foo",quantile="0.99"} 20
|
|
|
|
|
test_summary_sum{name="foo"} 30
|
|
|
|
|
test_summary_count{name="foo"} 2
|
2018-11-01 09:34:50 +03:00
|
|
|
`
|
|
|
|
|
|
|
|
|
|
registry := prometheus.NewRegistry()
|
|
|
|
|
|
|
|
|
|
summary := prometheus.NewSummaryVec(
|
|
|
|
|
prometheus.SummaryOpts{
|
|
|
|
|
Name: "test_summary",
|
|
|
|
|
Help: "test summary",
|
2019-06-11 15:37:57 +03:00
|
|
|
Objectives: map[float64]float64{
|
|
|
|
|
0.5: 0.05,
|
|
|
|
|
0.9: 0.01,
|
|
|
|
|
0.99: 0.001,
|
|
|
|
|
},
|
2018-11-01 09:34:50 +03:00
|
|
|
},
|
|
|
|
|
[]string{"name"},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
histogram := prometheus.NewHistogramVec(
|
|
|
|
|
prometheus.HistogramOpts{
|
|
|
|
|
Name: "test_hist",
|
|
|
|
|
Help: "test histogram",
|
|
|
|
|
},
|
|
|
|
|
[]string{"name"},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
gauge := prometheus.NewGaugeVec(
|
|
|
|
|
prometheus.GaugeOpts{
|
|
|
|
|
Name: "test_gauge",
|
|
|
|
|
Help: "test gauge",
|
|
|
|
|
},
|
|
|
|
|
[]string{"name"},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
counter := prometheus.NewCounterVec(
|
|
|
|
|
prometheus.CounterOpts{
|
|
|
|
|
Name: "test_counter",
|
|
|
|
|
Help: "test counter",
|
|
|
|
|
},
|
|
|
|
|
[]string{"name"},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
registry.MustRegister(summary)
|
|
|
|
|
registry.MustRegister(histogram)
|
|
|
|
|
registry.MustRegister(gauge)
|
|
|
|
|
registry.MustRegister(counter)
|
|
|
|
|
|
|
|
|
|
summary.With(prometheus.Labels{"name": "foo"}).Observe(10)
|
|
|
|
|
summary.With(prometheus.Labels{"name": "foo"}).Observe(20)
|
|
|
|
|
histogram.With(prometheus.Labels{"name": "bar"}).Observe(0.93)
|
|
|
|
|
histogram.With(prometheus.Labels{"name": "bar"}).Observe(2.71)
|
|
|
|
|
gauge.With(prometheus.Labels{"name": "baz"}).Set(1.1)
|
|
|
|
|
counter.With(prometheus.Labels{"name": "qux"}).Inc()
|
|
|
|
|
|
2022-08-02 11:27:49 +03:00
|
|
|
tmpfile, err := os.CreateTemp("", "prom_registry_test")
|
2018-11-01 09:34:50 +03:00
|
|
|
if err != nil {
|
|
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
defer os.Remove(tmpfile.Name())
|
|
|
|
|
|
2018-11-02 18:37:08 +03:00
|
|
|
if err := prometheus.WriteToTextfile(tmpfile.Name(), registry); err != nil {
|
|
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
2018-11-01 09:34:50 +03:00
|
|
|
|
2022-08-02 11:27:49 +03:00
|
|
|
fileBytes, err := os.ReadFile(tmpfile.Name())
|
2018-11-01 09:34:50 +03:00
|
|
|
if err != nil {
|
|
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
fileContents := string(fileBytes)
|
|
|
|
|
|
|
|
|
|
if fileContents != expectedOut {
|
2019-06-11 15:37:57 +03:00
|
|
|
t.Errorf(
|
|
|
|
|
"files don't match, got:\n%s\nwant:\n%s",
|
|
|
|
|
fileContents, expectedOut,
|
|
|
|
|
)
|
2018-11-01 09:34:50 +03:00
|
|
|
}
|
|
|
|
|
}
|
2019-10-14 21:02:58 +03:00
|
|
|
|
|
|
|
|
// collidingCollector is a collection of prometheus.Collectors,
|
|
|
|
|
// and is itself a prometheus.Collector.
|
|
|
|
|
type collidingCollector struct {
|
|
|
|
|
i int
|
|
|
|
|
name string
|
|
|
|
|
|
|
|
|
|
a, b, c, d prometheus.Collector
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Describe satisifies part of the prometheus.Collector interface.
|
|
|
|
|
func (m *collidingCollector) Describe(desc chan<- *prometheus.Desc) {
|
|
|
|
|
m.a.Describe(desc)
|
|
|
|
|
m.b.Describe(desc)
|
|
|
|
|
m.c.Describe(desc)
|
|
|
|
|
m.d.Describe(desc)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Collect satisifies part of the prometheus.Collector interface.
|
|
|
|
|
func (m *collidingCollector) Collect(metric chan<- prometheus.Metric) {
|
|
|
|
|
m.a.Collect(metric)
|
|
|
|
|
m.b.Collect(metric)
|
|
|
|
|
m.c.Collect(metric)
|
|
|
|
|
m.d.Collect(metric)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// TestAlreadyRegistered will fail with the old, weaker hash function. It is
|
|
|
|
|
// taken from https://play.golang.org/p/HpV7YE6LI_4 , authored by @awilliams.
|
|
|
|
|
func TestAlreadyRegisteredCollision(t *testing.T) {
|
|
|
|
|
reg := prometheus.NewRegistry()
|
|
|
|
|
|
|
|
|
|
for i := 0; i < 10000; i++ {
|
|
|
|
|
// A collector should be considered unique if its name and const
|
|
|
|
|
// label values are unique.
|
|
|
|
|
|
|
|
|
|
name := fmt.Sprintf("test-collector-%010d", i)
|
|
|
|
|
|
|
|
|
|
collector := collidingCollector{
|
|
|
|
|
i: i,
|
|
|
|
|
name: name,
|
|
|
|
|
|
|
|
|
|
a: prometheus.NewCounter(prometheus.CounterOpts{
|
|
|
|
|
Name: "my_collector_a",
|
|
|
|
|
ConstLabels: prometheus.Labels{
|
|
|
|
|
"name": name,
|
|
|
|
|
"type": "test",
|
|
|
|
|
},
|
|
|
|
|
}),
|
|
|
|
|
b: prometheus.NewCounter(prometheus.CounterOpts{
|
|
|
|
|
Name: "my_collector_b",
|
|
|
|
|
ConstLabels: prometheus.Labels{
|
|
|
|
|
"name": name,
|
|
|
|
|
"type": "test",
|
|
|
|
|
},
|
|
|
|
|
}),
|
|
|
|
|
c: prometheus.NewCounter(prometheus.CounterOpts{
|
|
|
|
|
Name: "my_collector_c",
|
|
|
|
|
ConstLabels: prometheus.Labels{
|
|
|
|
|
"name": name,
|
|
|
|
|
"type": "test",
|
|
|
|
|
},
|
|
|
|
|
}),
|
|
|
|
|
d: prometheus.NewCounter(prometheus.CounterOpts{
|
|
|
|
|
Name: "my_collector_d",
|
|
|
|
|
ConstLabels: prometheus.Labels{
|
|
|
|
|
"name": name,
|
|
|
|
|
"type": "test",
|
|
|
|
|
},
|
|
|
|
|
}),
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Register should not fail, since each collector has a unique
|
|
|
|
|
// set of sub-collectors, determined by their names and const label values.
|
|
|
|
|
if err := reg.Register(&collector); err != nil {
|
2022-08-03 07:30:51 +03:00
|
|
|
are := &prometheus.AlreadyRegisteredError{}
|
|
|
|
|
if !errors.As(err, are) {
|
2019-10-14 21:02:58 +03:00
|
|
|
t.Fatal(err)
|
|
|
|
|
}
|
|
|
|
|
|
2022-08-03 07:30:51 +03:00
|
|
|
previous := are.ExistingCollector.(*collidingCollector)
|
|
|
|
|
current := are.NewCollector.(*collidingCollector)
|
2019-10-14 21:02:58 +03:00
|
|
|
|
2022-08-03 07:30:51 +03:00
|
|
|
t.Errorf("Unexpected registration error: %q\nprevious collector: %s (i=%d)\ncurrent collector %s (i=%d)", are, previous.name, previous.i, current.name, current.i)
|
2019-10-14 21:02:58 +03:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-02-23 14:22:52 +03:00
|
|
|
|
|
|
|
|
type tGatherer struct {
|
|
|
|
|
done bool
|
|
|
|
|
err error
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (g *tGatherer) Gather() (_ []*dto.MetricFamily, done func(), err error) {
|
|
|
|
|
name := "g1"
|
|
|
|
|
val := 1.0
|
|
|
|
|
return []*dto.MetricFamily{
|
|
|
|
|
{Name: &name, Metric: []*dto.Metric{{Gauge: &dto.Gauge{Value: &val}}}},
|
|
|
|
|
}, func() { g.done = true }, g.err
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestNewMultiTRegistry(t *testing.T) {
|
|
|
|
|
treg := &tGatherer{}
|
|
|
|
|
|
|
|
|
|
t.Run("one registry", func(t *testing.T) {
|
|
|
|
|
m := prometheus.NewMultiTRegistry(treg)
|
|
|
|
|
ret, done, err := m.Gather()
|
|
|
|
|
if err != nil {
|
|
|
|
|
t.Error("gather failed:", err)
|
|
|
|
|
}
|
|
|
|
|
done()
|
|
|
|
|
if len(ret) != 1 {
|
|
|
|
|
t.Error("unexpected number of metric families, expected 1, got", ret)
|
|
|
|
|
}
|
|
|
|
|
if !treg.done {
|
|
|
|
|
t.Error("inner transactional registry not marked as done")
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
reg := prometheus.NewRegistry()
|
|
|
|
|
if err := reg.Register(prometheus.NewCounter(prometheus.CounterOpts{Name: "c1", Help: "help c1"})); err != nil {
|
|
|
|
|
t.Error("registration failed:", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Note on purpose two registries will have exactly same metric family name (but with different string).
|
|
|
|
|
// This behaviour is undefined at the moment.
|
|
|
|
|
if err := reg.Register(prometheus.NewGauge(prometheus.GaugeOpts{Name: "g1", Help: "help g1"})); err != nil {
|
|
|
|
|
t.Error("registration failed:", err)
|
|
|
|
|
}
|
|
|
|
|
treg.done = false
|
|
|
|
|
|
|
|
|
|
t.Run("two registries", func(t *testing.T) {
|
|
|
|
|
m := prometheus.NewMultiTRegistry(prometheus.ToTransactionalGatherer(reg), treg)
|
|
|
|
|
ret, done, err := m.Gather()
|
|
|
|
|
if err != nil {
|
|
|
|
|
t.Error("gather failed:", err)
|
|
|
|
|
}
|
|
|
|
|
done()
|
|
|
|
|
if len(ret) != 3 {
|
|
|
|
|
t.Error("unexpected number of metric families, expected 3, got", ret)
|
|
|
|
|
}
|
|
|
|
|
if !treg.done {
|
|
|
|
|
t.Error("inner transactional registry not marked as done")
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
treg.done = false
|
|
|
|
|
// Inject error.
|
|
|
|
|
treg.err = errors.New("test err")
|
|
|
|
|
|
|
|
|
|
t.Run("two registries, one with error", func(t *testing.T) {
|
|
|
|
|
m := prometheus.NewMultiTRegistry(prometheus.ToTransactionalGatherer(reg), treg)
|
|
|
|
|
ret, done, err := m.Gather()
|
2022-08-03 07:30:51 +03:00
|
|
|
if !errors.Is(err, treg.err) {
|
2022-02-23 14:22:52 +03:00
|
|
|
t.Error("unexpected error:", err)
|
|
|
|
|
}
|
|
|
|
|
done()
|
|
|
|
|
if len(ret) != 3 {
|
|
|
|
|
t.Error("unexpected number of metric families, expected 3, got", ret)
|
|
|
|
|
}
|
|
|
|
|
// Still on error, we expect done to be triggered.
|
|
|
|
|
if !treg.done {
|
|
|
|
|
t.Error("inner transactional registry not marked as done")
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
}
|
2022-08-23 12:09:29 +03:00
|
|
|
|
|
|
|
|
// This example shows how to use multiple registries for registering and
|
|
|
|
|
// unregistering groups of metrics.
|
|
|
|
|
func ExampleRegistry_grouping() {
|
|
|
|
|
// Create a global registry.
|
|
|
|
|
globalReg := prometheus.NewRegistry()
|
|
|
|
|
|
|
|
|
|
// Spawn 10 workers, each of which will have their own group of metrics.
|
|
|
|
|
for i := 0; i < 10; i++ {
|
|
|
|
|
// Create a new registry for each worker, which acts as a group of
|
|
|
|
|
// worker-specific metrics.
|
|
|
|
|
workerReg := prometheus.NewRegistry()
|
|
|
|
|
globalReg.Register(workerReg)
|
|
|
|
|
|
|
|
|
|
go func(workerID int) {
|
|
|
|
|
// Once the worker is done, it can unregister itself.
|
|
|
|
|
defer globalReg.Unregister(workerReg)
|
|
|
|
|
|
|
|
|
|
workTime := prometheus.NewCounter(prometheus.CounterOpts{
|
|
|
|
|
Name: "worker_total_work_time_milliseconds",
|
|
|
|
|
ConstLabels: prometheus.Labels{
|
|
|
|
|
// Generate a label unique to this worker so its metric doesn't
|
|
|
|
|
// collide with the metrics from other workers.
|
|
|
|
|
"worker_id": fmt.Sprintf("%d", workerID),
|
|
|
|
|
},
|
|
|
|
|
})
|
|
|
|
|
workerReg.MustRegister(workTime)
|
|
|
|
|
|
|
|
|
|
start := time.Now()
|
|
|
|
|
time.Sleep(time.Millisecond * time.Duration(rand.Intn(100)))
|
|
|
|
|
workTime.Add(float64(time.Since(start).Milliseconds()))
|
|
|
|
|
}(i)
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-12-15 18:07:45 +03:00
|
|
|
|
|
|
|
|
type customCollector struct {
|
|
|
|
|
collectFunc func(ch chan<- prometheus.Metric)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (co *customCollector) Describe(_ chan<- *prometheus.Desc) {}
|
|
|
|
|
|
|
|
|
|
func (co *customCollector) Collect(ch chan<- prometheus.Metric) {
|
|
|
|
|
co.collectFunc(ch)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// TestCheckMetricConsistency
|
|
|
|
|
func TestCheckMetricConsistency(t *testing.T) {
|
|
|
|
|
reg := prometheus.NewRegistry()
|
|
|
|
|
timestamp := time.Now()
|
|
|
|
|
|
|
|
|
|
desc := prometheus.NewDesc("metric_a", "", nil, nil)
|
|
|
|
|
metric := prometheus.MustNewConstMetric(desc, prometheus.CounterValue, 1)
|
|
|
|
|
|
|
|
|
|
validCollector := &customCollector{
|
|
|
|
|
collectFunc: func(ch chan<- prometheus.Metric) {
|
|
|
|
|
ch <- prometheus.NewMetricWithTimestamp(timestamp.Add(-1*time.Minute), metric)
|
|
|
|
|
ch <- prometheus.NewMetricWithTimestamp(timestamp, metric)
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
reg.MustRegister(validCollector)
|
|
|
|
|
_, err := reg.Gather()
|
|
|
|
|
if err != nil {
|
|
|
|
|
t.Error("metric validation should succeed:", err)
|
|
|
|
|
}
|
|
|
|
|
reg.Unregister(validCollector)
|
|
|
|
|
|
|
|
|
|
invalidCollector := &customCollector{
|
|
|
|
|
collectFunc: func(ch chan<- prometheus.Metric) {
|
|
|
|
|
ch <- prometheus.NewMetricWithTimestamp(timestamp, metric)
|
|
|
|
|
ch <- prometheus.NewMetricWithTimestamp(timestamp, metric)
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
reg.MustRegister(invalidCollector)
|
|
|
|
|
_, err = reg.Gather()
|
|
|
|
|
if err == nil {
|
|
|
|
|
t.Error("metric validation should return an error")
|
|
|
|
|
}
|
|
|
|
|
reg.Unregister(invalidCollector)
|
|
|
|
|
}
|