Commit Graph

46 Commits

Author SHA1 Message Date
beorn7 abf2762ffe Merge branch 'master' into dev-0.10 2018-11-03 17:49:10 +01:00
Peter Jausovec ea348d7c20 Update code based on the PR feedback
Signed-off-by: Peter Jausovec <peter.jausovec@oracle.com>
2018-11-02 09:01:14 -07:00
Peter Jausovec 902733d080 Add more info to the inconsistent cardinality errors
Signed-off-by: Peter Jausovec <peter.jausovec@oracle.com>
2018-10-31 11:01:42 -07:00
beorn7 c94f67cd07 Rename Delete / DeleteLabelValues → Remove / RemoveLabelValue
For metric vectors, that is.

This it to bring client_golang in line with the client library
guidelines. See #218.

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-10-16 15:12:52 +02:00
beorn7 f53420cd1d Rename metric vector method `Reset` to `Clear`
This it to bring client_golang in line with the client library
guidelines. See #218.

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-10-16 15:04:09 +02:00
beorn7 1cb875e111 Remove deprecated DefObjectives from Summary
Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-10-15 19:55:40 +02:00
beorn7 663a9ad019 Make Help strings optional
This is in line with
https://prometheus.io/docs/instrumenting/writing_clientlibs/#metric-description-and-help

Since the zero value of a string in Go is `""`, we cannot distinguish
between a Help string not set and an empty Help string. Thus, we just
make it formally optional here with an encouragement to set it in the
doc comment.

In v0.10, the Help string will probably become a "normal" argument of
the constructor rather than a field in an Opts struct.

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-09-17 12:07:31 +02:00
beorn7 713e6eb604 Let NewConst... functions detect invalid Desc
The error of the invalid Desc is returned in that case.

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-09-17 11:50:42 +02:00
Yutian Li 94f32c433e typo
Signed-off-by: Yutian Li <hotpxless@gmail.com>
2018-08-27 12:01:30 -04:00
beorn7 e064aa97f1 Check quantile label during SummaryVec construction
Also, document the existing behavior more clearly.

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-07-13 13:43:21 +02:00
beorn7 1ba60c7d58 Pull currying methods up into ObserverVec interface 2017-12-22 16:11:58 +01:00
beorn7 dd20712622 Allow currying of metric vec's
The idea behind it is described in detail in
https://github.com/prometheus/client_golang/issues/320 .

This commit also updates the example given in
promhttp/instrument_server_test.go , which nicely illustrates the
benefit of this change.

So far, currying could be emulated by creating different metric vec's
with different values in their ConstLabels. This was quite difficult
to grasp - which is essentially what was done in the example mentioned
above. Now that this use case can be solved without ConstLabels, we
can safely declare ConstLabels as rarely used. (Perhaps we can
deprecate them entirely one day, but I'll take a raincheck on that
when the changes of v0.10 have materialized.) This commit thus also
updates the ConstLabel doc comments in the various Opts. (It contained
fairly outdated stuff anyway.)
2017-12-22 15:56:11 +01:00
beorn7 10c55533cb Rename the receiver of `...Vec` methods from `m` to `v` 2017-12-21 14:06:39 +01:00
beorn7 9e1588b2a2 Pull `With` and `WithLabelValues` up into exported types
The "panic in case of error" code was so far in metricVec. This pulls
it up into the exported types like CounterVec. This is code
replication, but it avoids an explicit type conversion. Mostly,
however, this is preparation to make the wrapped metricVec an
interface (required for curried vec's).
2017-12-21 14:06:39 +01:00
beorn7 50b3332fd6 Polishing some doc comments 2017-09-13 12:48:29 +02:00
Povilas Versockas 77a1417b06 Change summary docs 2017-09-12 20:27:18 +03:00
Marco Jantke a956c5fdd6 improve validation function naming 2017-08-25 17:58:59 +02:00
Marco Jantke 0b8aef084e implement review feedback 2017-08-25 14:51:19 +02:00
Marco Jantke 703c4a9c6f add label value validation to NewConstMetric and friends 2017-08-20 00:09:51 +02:00
beorn7 f66cdf0736 Un-export MetricVec
This is in preparation for "curried" metric vecs, as discussed.

And it's a good thing anyway. The exported MetricVec was from a time
when I thought people would define own Metric types and then create
Vecs of it. That has never happened.
2017-06-28 17:55:59 +02:00
stuart nelson d01fd62222 new handler instrumentation (#285)
Add new HTTP handler instrumentation
2017-04-24 15:13:19 -04:00
beorn7 9c4b7780d7 Allow Summaries with empty objectives and deprecate DefObjectives
This also updates all tests and examples to use explicitly set
objectives.

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

Fixes #118
2016-11-23 18:35:02 +01:00
beorn7 434a8ed85d Bring back zero-alloc label-value access for metric vecs
Also, fix mutex copy-by-value bug.
2016-08-17 14:01:11 +02:00
Stephen J Day c4004ef5f6
benchmark: measure label resolution in MetricVec
Signed-off-by: Stephen J Day <stephen.day@docker.com>
2016-08-15 16:47:42 -07:00
beorn7 2e66d12fe5 Act on DefaultRegisterer and DefaultDeliverer where possible
Both point to the DefaultRegistry anyway, but users can now replace it
with interfaces rather than only other Registry instances.
2016-08-03 12:50:39 +02:00
beorn7 249069ec01 Unexport SelfCollector.
This is most likely used nowhere and can be unexported to clean up the
namespace.
2016-08-03 01:09:27 +02:00
beorn7 cf7e1caf17 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-08-02 18:46:22 +02:00
Robert Vollmert 1312da4c0c Inline hash/fnv. 2015-11-09 15:16:26 +01:00
Fabian Reinartz f2de0f589a Remove client_golang/model als direct dependency 2015-08-23 13:51:32 +02:00
Robert Vollmert 1e201f4328 Reword, using "φ-quantile". 2015-08-03 14:10:20 +02:00
Robert Vollmert 5b1aa4ab69 More explicit documentation of SummaryOpts.Objectives. 2015-08-03 13:49:15 +02:00
Bjoern Rabenstein 9c4fec0bce Implement constSummary and constHistogram. 2015-05-04 00:32:15 +02:00
beorn7 715be73ac9 Return NaN when summaries have no observations yet.
Also, properly handle decay upon Write().

This fixes https://github.com/prometheus/client_golang/issues/85 .
2015-03-15 16:33:56 +01:00
Julius Volz 738b69e61a Use non-rewritten Godep imports. 2015-02-27 16:49:40 +01:00
Julius Volz 169c8a68e1 Use godep with import rewriting for vendoring.
The new vendoring was produced by running:

    godep save -r ./examples/... ./prometheus/... ./text/... ./model/... ./extraction/...

Two things to note:

- "extraction/processor0_0_{1,2}_test.go" imported a package from
  "github.com/prometheus/prometheus", all for just one tiny testing
  function. To not have to deal with a circular vendoring dependency, I
  simply replaced the usage of the function by some in-line logic.

- godep grouped the rewritten imports slightly differently for some
  reason, but at least the standard library imports are still in a
  separate section. Not sure if it's worth manually keeping our old
  import grouping scheme or if we should simply use that godep-generated
  one.
2015-02-26 00:47:03 +01:00
beorn7 000ef45157 Replaced http by HTTP if used as the name of the protocol in English. 2015-02-19 15:54:26 +01:00
beorn7 b1e7299877 Turned "le" and "quantile" label names into constants. 2015-02-19 15:54:26 +01:00
beorn7 4c4f51d546 Catch illegal label names for summaries in histograms. 2015-02-19 15:54:26 +01:00
beorn7 6958242277 Add support for histograms to the Go client library. 2015-02-19 15:54:26 +01:00
Julius Volz 765fdaf37e Update protobuf library package name.
The Golang protocol buffer library has now moved to GitHub:

https://github.com/golang/protobuf

Although "go get"-ing the old package name still works, moving
everything to the new one will make vendoring cleaner.

See also https://github.com/matttproud/golang_protobuf_extensions/pull/7
2015-02-14 00:00:34 +01:00
Bjoern Rabenstein d7f8eb1083 Change "Prometheus Team" to "The Prometheus Authors". 2015-02-02 15:14:36 +01:00
Bjoern Rabenstein 15c9ded5a3 Fix the summary decay by avoiding the Merge method.
This makes the Observe method of summaries more expensive. :-(
2015-01-21 13:44:43 +01:00
Bjoern Rabenstein 6b9530d72e Update vendoring of perks to newest (fixed) version.
Adjust the API and usage accordingly.
Make tests stricter.

Since the merging is still faulty, test are broken now.
The next commit will fix it by avoiding merging.
2015-01-20 18:27:10 +01:00
Bjoern Rabenstein 159e96f6c7 Allow error reporting during metrics collection and simplify Register().
Both are interface changes I want to get in before public
announcement. They only break rare usage cases, and are always easy to
fix, but still we want to avoid breaking changes after a wider
announcement of the project.

The change of Register() simply removes the return of the Collector,
which nobody was using in practice. It was just bloating the call
syntax. Note that this is different from RegisterOrGet(), which is
used at various occasions where you want to register something that
might or might not be registered already, but if it is, you want the
previously registered Collector back (because that's the relevant
one).

WRT error reporting: I first tried the obvious way of letting the
Collector methods Describe() and Collect() return error. However, I
had to conclude that that bloated _many_ calls and their handling in
very obnoxious ways. On the other hand, the case where you actually
want to report errors during registration or collection is very
rare. Hence, this approach has the wrong trade-off. The approach taken
here might at first appear clunky but is in practice quite handy,
mostly because there is almost no change for the "normal" case of "no
special error handling", but also because it plays well with the way
descriptors and metrics are handled (via channels).

Explaining the approach in more detail:

- During registration / describe: Error handling was actually already
  in place (for invalid descriptors, which carry an error anyway). I
  only added a convenience function to create an invalid descriptor
  with a given error on purpose.

- Metrics are now treated in a similar way. The Write method returns
  an error now (the only change in interface). An "invalid metric" is
  provided that can be sent via the channel to signal that that metric
  could not be collected. It alse transports an error.

NON-GOALS OF THIS COMMIT:

This is NOT yet the major improvement of the whole registry part,
where we want a public Registry interface and plenty of modular
configurations (for error handling, various auto-metrics, http
instrumentation, testing, ...). However, we can do that whole thing
without breaking existing interfaces. For now (which is a significant
issue) any error during collection will either cause a 500 HTTP
response or a panic (depending on registry config). Later, we
definitely want to have a possibility to skip (and only report
somehow) non-collectible metrics instead of aborting the whole scrape.
2015-01-12 19:16:09 +01:00
Bjoern Rabenstein 010dc1af88 Vendorize perks/quantile.
Change-Id: I2b24bddf5a975a46ceb598db328c317982154466
2014-06-23 19:48:50 +02:00
Bjoern Rabenstein 5d40912fd2 Complete rewrite of the exposition library.
This rewrite had may backs and forths. In my git repository, it
consists of 35 commits which I cannot group or merge into reasonable
review buckets. Gerrit breaks fundamental git semantics, so I have to
squash the 35 commits into one for the review.

I'll push this not with refs/for/master, but with refs/for/next so
that we can transition after submission in a controlled fashion.

For the review, I recommend to start with looking at godoc and in
particular the many examples. After that, continue with a line-by-line
detailed review. (The big picture is hopefully as expected after
wrapping up the discussion earlier.)

Change-Id: Ib38cc46493a5139ca29d84020650929d94cac850
2014-06-17 14:08:22 +02:00