Commit Graph

145 Commits

Author SHA1 Message Date
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
Uwe Dauernheim c1e8a41238 Fix typo in doc string 2016-08-01 23:14:45 +02:00
Andrew Stuart e63e6e3db7
Extend MustRegister function to accept variadic args 2016-07-11 15:04:23 -07:00
Matt Bostock c7f1ecb643 Fix GoDoc indentation
The line after the first in each bullet point was appearing as
preformatted blocks when viewed as HTML in GoDoc.
2016-06-27 15:26:48 +01:00
Chris Lonng 7752efd9d6 comment contains some misspell 2016-06-27 17:49:34 +08:00
Björn Rabenstein 488edd04dc Merge pull request #202 from mattyw/01-docs
prometheus/docs: Added a link to the metric types page
2016-05-31 11:15:28 +02:00
mattyw 3c063fb533 prometheus/docs: Added a link to the metric types page 2016-05-31 10:07:50 +01:00
beorn7 f6b16ed256 Document the issues of InstrumentHandler
Obvious next step: Fix those issues.
2016-05-15 17:59:51 +02:00
Matt Harden e3340f3371 Fix max_fds process collector test
This test fails when max_fds is a large value; say 4.5e+06, for example. Change it to match virtual_memory_bytes, which also has to handle large values.
2016-05-12 16:55:21 -07:00
Brian Brazil 09374d92aa Remove anti-pattern of having target labels in instrumentation example. 2016-03-17 13:22:20 +00:00
Harmen e48dd8ee97 fix go_memstats_last_gc_time_seconds division 2016-02-08 01:28:30 +01:00
Michael Stapelberg c1370d07ca Strip trailing / from push URL.
This circumvents the following problem:
• The prometheus client library appends “/metrics/…” to the pushURL.
• When pushURL ends in a trailing slash, the URL becomes e.g.
  http://pushgateway.example.com:9091//metrics/…
• The pushgateway will reply with an HTTP 307 status code
  (temporary redirect).
• While Go’s net/http client follows redirects by default, it will only
  follow HTTP 302 (Found) and HTTP 303 (See Other) redirects for PUT and
  POST requests, which the prometheus client library uses.

Hence, when calling e.g.:

    prometheus.Push("foo", "bar", "http://pushgateway.example.com:9091/")

…your metrics would not actually get pushed successfully, but rather
you’d see the error message:

    2015/11/26 10:59:49 main.go:209: unexpected status code 307 while pushing to http://push...
2015-11-26 19:16:53 +01:00
Michael Stapelberg 1a09b46c2e fix typo: s/addr/url/ 2015-11-25 08:46:01 +01:00
Harmen 5d4fdca1a5 use local fnv hash everywhere 2015-11-12 14:07:23 +01:00
Björn Rabenstein cfd904193d Merge pull request #180 from dnesting/dnesting-sort-metrics
Make metric sort stable and sort by timestamp
2015-11-10 22:31:22 +01:00
David Nesting b0bd184e74 Simplify metricSorter timestamp comparison and improve comment 2015-11-10 09:37:58 -05:00
David Nesting 544f65f7fc metricSorter stops relying on time.Now and respects nil timestamps 2015-11-09 17:14:07 -05:00
David Nesting 5fb1b89678 Make metric sort stable and sort by timestamp 2015-11-09 16:55:26 -05:00
Robert Vollmert 8c96b12588 try getting metrics with a read lock, first 2015-11-09 15:16:26 +01:00
Robert Vollmert 5183814775 ok not has 2015-11-09 15:16:26 +01:00
Robert Vollmert 1312da4c0c Inline hash/fnv. 2015-11-09 15:16:26 +01:00
Robert Vollmert 39a26f2e35 concurrency benchmark 2015-11-09 14:34:37 +01:00
Björn Rabenstein e51041b3fa Merge pull request #146 from KevinPike/memstats
memstats collection
2015-10-08 16:32:47 +02:00
Kevin Pike db58b27d95 heap bytes released total 2015-10-07 11:21:49 -07:00
Kevin Pike 1eb8d032a8 use counter for heap released bytes 2015-10-06 08:18:17 -07:00
Kevin Pike 9a6b9d3ddf fix descriptions 2015-10-05 09:27:28 -07:00
Kevin Pike 6c7a1db6bf don't reuse memstats 2015-10-05 07:37:59 -07:00
Kevin Pike 8a031ee219 unembed memstats collector 2015-10-02 18:10:36 -07:00
beorn7 90ddfa1c1e Move from client_golang/text to common/expfmt 2015-09-17 13:06:43 +02:00
Björn Rabenstein 29939ec908 Merge pull request #160 from ardan-bkennedy/master
Update histogram_test.go
2015-08-28 12:34:13 +02:00
Fabian Reinartz f2de0f589a Remove client_golang/model als direct dependency 2015-08-23 13:51:32 +02:00
Julius Volz 4a339dcbca Fix minor typos in comment. 2015-08-17 12:58:16 +02:00
William Kennedy f075821cbb Update histogram_test.go
These tests are always timing out in our Jenkins CI environment. We have moved our timeout to 2 minutes. I have added a check for the short flag so other can skip these tests as we are until this can be identified.
2015-08-12 17:51:21 -04:00
William Kennedy a794f77b54 Update go_collector_test.go
We are running into a timeout with TestHistogramConcurrency on our Jenkins box. I noticed in the stack trace for the timeout this block.

goroutine 2348 [chan send]:
github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus.(*goCollector).Collect(0xc20801e8e0, 0xc20800a7e0)
	/var/lib/jenkins/jobs/Kober/workspace/src/github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus/go_collector.go:49 +0x6dd
github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus.func·028()
	/var/lib/jenkins/jobs/Kober/workspace/src/github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus/go_collector_test.go:27 +0x11a
created by github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus.TestGoCollector
	/var/lib/jenkins/jobs/Kober/workspace/src/github.comcast.com/ventris/kober/vnd/github.com/prometheus/client_golang/prometheus/go_collector_test.go:28 +0x35e

This suggested that even though the TestGoCollector test was finished, a goroutine was still hanging around. I traced it back to the call to c.Collect always sending twice of the provided channel. This change receives that second value and allows the goroutine to finish with the test.

Still can't figure out why TestHistogramConcurrency is timing out after 2 minutes :(
2015-08-12 15:23:41 -04: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
Kevin Pike c945ed62c1 use metrics struct. include more statistics 2015-07-21 20:29:02 -07:00
Kevin Pike 5e9294fbb7 continue to fix errors 2015-07-21 08:38:46 -07:00
Kevin Pike 59305998f6 remove prometheus namespace references, copy paste error 2015-07-21 08:34:50 -07:00
Kevin Pike b14b149930 use counters where applicable, improve descriptions 2015-07-21 08:24:22 -07:00
Kevin Pike 8a6e3ecf23 adds general and heap memory statistics 2015-07-20 20:55:38 -07:00
beorn7 7abba842b0 Document the possibility to create "empty" metrics in a metric vector.
This fixes https://github.com/prometheus/client_golang/issues/119.
2015-07-15 13:13:56 +02:00
Julius Volz a03cc290e7 Merge pull request #139 from prometheus/fix-untyped-ref
Fix doc-comment reference to Untyped metric.
2015-06-13 12:22:23 +02:00
Julius Volz 209414d85f Mention histograms in doc.go. 2015-06-13 12:20:08 +02:00
Julius Volz b6525949dd Fix doc-comment reference to Untyped metric. 2015-06-13 02:16:27 +02:00
beorn7 59f2c7d8b0 Fix a number of minor things.
- Clarify documentation about sorting requirements.
- Add missing histogram support in consistency check.
- Add label sorting to consistency check.
- Improve error messages when reporting a metric.
  (Previously, the metric name was not printed.)
2015-06-09 12:03:07 +02:00
Tomasz Elendt dd4dd69878 Solve "The Proxy Problem" of InstrumentHandler
InstrumentHandler provides proxy object over given http.ResponseWriter
- responseWriterDelegator that only implements the bare minimum
required of an http.ResponseWriter and doesn’t implement any interface
upgrades (http.Flusher, http.Hijacker, etc.). This commit fixes it by
providing fancyResponseWriterDelegator with all the fancy bells and
whistles if standard library http.ResponseWriter is detected.

Heavily inspired by Goji's middleware.

https://avtok.com/2014/11/05/interface-upgrades.html#the-proxy-problem
2015-06-04 23:48:40 +02:00
Tomasz Elendt 288762e79c Change responseWriterDelegator.written to int64
Change responseWriterDelegator.written to int64 so that responses
bigger than 4GB could be properly observed on 32 bit systems.
2015-06-04 23:14:37 +02:00
beorn7 10eab41b48 Make LabelNameRE public. 2015-06-01 15:41:09 +02:00
Michael Stapelberg 23ef520369 doc fix: s/DefObjectives/DefBuckets/ 2015-05-30 17:30:45 +02:00