Commit Graph

832 Commits

Author SHA1 Message Date
Björn Rabenstein 9753225510 Merge pull request #251 from Comradin/master
Documentation enhancement
2016-11-02 11:23:09 +01:00
Marcus Franke 17f1add33c Changed example sources according to the basic documentation example 2016-11-02 10:52:31 +01:00
Marcus Franke 473bcd5aa1 [docs] enhanced the basic example
To protect people from starting their exporter multiple times, one has to
evaluate the error returned by http.ListenAndServe().
2016-11-02 10:48:36 +01:00
Björn Rabenstein 3fb8ace93b Merge pull request #247 from prometheus/beorn7/deprecation
Remove deprecated features that are esay to replace
2016-10-26 13:07:08 +02:00
Björn Rabenstein 134be0b978 Merge pull request #246 from prometheus/beorn7/process_collector
Convert process collector to const metrics
2016-10-25 18:28:59 +02:00
beorn7 2fee50beaa Remove deprecated features that are esay to replace
That's the "soft" part of the deprecation: Everything that has been
marked deprecated in v0.8 or earlier and is straight-forward to
replace by a non-deprecated way, is removed here.

Sadly, this does not include the HTTP part. We first need to provide a
replacement for HTTP instrumentation (as planned for v0.8) to then
remove the deprecated parts in v0.9.
2016-10-25 18:28:15 +02:00
beorn7 6450fc55b1 Convert process collector to const metrics
This is needed to remove the deprecated Set method from the Counter.
2016-10-25 18:19:24 +02:00
Björn Rabenstein 334af0119a Merge pull request #243 from prometheus/beorn7/testing
Adding a test for non-monotonic buckets
2016-10-17 14:35:36 +02:00
beorn7 6373fd9334 Adding a test for non-monotonic buckets 2016-10-17 13:57:02 +02:00
Tobias Schmidt 5636dc67ae Merge pull request #238 from prometheus/beorn7/lint
Add goreport card and remove warnings where feasible
2016-09-16 14:03:40 -04:00
beorn7 c9325a4a67 Add goreport card and remove warnings where feasible 2016-09-16 19:59:04 +02:00
Björn Rabenstein 8aae34f3ff Merge pull request #236 from nghialv/master
Fix goroutine leak
2016-09-12 12:34:28 +02:00
nghialv bc86b956d7 fix goroutine leak 2016-09-11 00:24:13 +09:00
Björn Rabenstein ea6e1db4cb Merge pull request #234 from prometheus/fabxc-patch-1
update Go version for CI
2016-08-29 10:57:35 +02:00
Fabian Reinartz a2588d79ba Use go 1.6.3 2016-08-29 10:56:19 +02:00
Fabian Reinartz 91a6ade697 update Go version for CI 2016-08-29 08:10:35 +02:00
Björn Rabenstein c5b7fccd20 Merge pull request #226 from prometheus/beorn7/alloc
Bring back zero-alloc label-value access for metric vecs
2016-08-17 17:48:24 +02:00
Björn Rabenstein 1b2608708e Merge pull request #227 from prometheus/beorn7/release
Cut v0.8.0
2016-08-17 17:47:56 +02:00
beorn7 9604506fff Cut v0.8.0 2016-08-17 16:08:12 +02:00
Tobias Schmidt a4d14b3d4f Merge pull request #225 from prometheus/beorn7/testing
Add "real" collision to MetricVec tests
2016-08-17 09:34:56 -04: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
beorn7 1f823ab271 Refactor tests
Also, add a "real" collision to the tests.
2016-08-17 12:19:50 +02:00
beorn7 00d39222c2 Naming nit 2016-08-17 10:36:20 +02:00
Björn Rabenstein dadfef856f Merge pull request #221 from stevvooe/benchmark-with-labels-metric-vec
metricvec: handle hash collision for labeled metrics
2016-08-17 09:36:54 +02:00
Stephen J Day 4db77b04a8
metricvec: refactor collision handling to handle equality
After increasing unit test coverage, it was found that the split
function call nature of metric matching wasn't working well in many
cases. By increasing test coverage, we've ensured that both the fast
path and fallback collision path are working appropriately.

With these changes, there is a further performance hit, but now the
results are ensured to be correct.

Signed-off-by: Stephen J Day <stephen.day@docker.com>
2016-08-16 18:34:16 -07:00
Stephen J Day 3cf50db5fd
metricvec: handle hash collision for labeled metrics
While hash collisions are quite rare, the current state of the client
library carries a risk of merging two separate label values into a
single metric bucket. The effects are near impossible to detect and the
result will be missing or incorrect counters.

This changeset handles hash collisions by falling back to collision
resolution if multiple label values hash to the same value. This works
similar to separate chaining using a slice. Extra storage is minimized
to only the value key slice to that metrics can be differentiated
within a bucket.

In general, the cost of handling collisions is completely minimized
under normal operation. Performance does show slight increases in
certain areas, but these are more likely statistically anomalies. More
importantly, zero allocation behavior for metrics is preserved on the
fast path. Minimal allocations may be made during collision handling but
this has minimal effect.

Benchmark comparisons with and without collision resolution follow.

```
benchmark                                                         old ns/op     new ns/op     delta
BenchmarkCounterWithLabelValues-4                                 99.0          107           +8.08%
BenchmarkCounterWithLabelValuesConcurrent-4                       79.6          91.0          +14.32%
BenchmarkCounterWithMappedLabels-4                                518           542           +4.63%
BenchmarkCounterWithPreparedMappedLabels-4                        127           137           +7.87%
BenchmarkCounterNoLabels-4                                        19.5          19.1          -2.05%
BenchmarkGaugeWithLabelValues-4                                   97.4          110           +12.94%
BenchmarkGaugeNoLabels-4                                          12.4          10.3          -16.94%
BenchmarkSummaryWithLabelValues-4                                 1204          915           -24.00%
BenchmarkSummaryNoLabels-4                                        936           847           -9.51%
BenchmarkHistogramWithLabelValues-4                               147           147           +0.00%
BenchmarkHistogramNoLabels-4                                      50.6          49.3          -2.57%
BenchmarkHistogramObserve1-4                                      37.9          37.5          -1.06%
BenchmarkHistogramObserve2-4                                      122           137           +12.30%
BenchmarkHistogramObserve4-4                                      310           352           +13.55%
BenchmarkHistogramObserve8-4                                      691           729           +5.50%
BenchmarkHistogramWrite1-4                                        3374          3097          -8.21%
BenchmarkHistogramWrite2-4                                        5310          5051          -4.88%
BenchmarkHistogramWrite4-4                                        12094         10690         -11.61%
BenchmarkHistogramWrite8-4                                        19416         17755         -8.55%
BenchmarkHandler-4                                                11934304      13765894      +15.35%
BenchmarkSummaryObserve1-4                                        1119          1105          -1.25%
BenchmarkSummaryObserve2-4                                        3679          3430          -6.77%
BenchmarkSummaryObserve4-4                                        10678         7982          -25.25%
BenchmarkSummaryObserve8-4                                        22974         16689         -27.36%
BenchmarkSummaryWrite1-4                                          25962         14680         -43.46%
BenchmarkSummaryWrite2-4                                          38019         35073         -7.75%
BenchmarkSummaryWrite4-4                                          78027         56816         -27.18%
BenchmarkSummaryWrite8-4                                          117220        132248        +12.82%
BenchmarkMetricVecWithLabelValuesBasic-4                          138           133           -3.62%
BenchmarkMetricVecWithLabelValues2Keys10ValueCardinality-4        150           144           -4.00%
BenchmarkMetricVecWithLabelValues4Keys10ValueCardinality-4        263           256           -2.66%
BenchmarkMetricVecWithLabelValues2Keys100ValueCardinality-4       145           155           +6.90%
BenchmarkMetricVecWithLabelValues10Keys100ValueCardinality-4      606           634           +4.62%
BenchmarkMetricVecWithLabelValues10Keys1000ValueCardinality-4     746           641           -14.08%

benchmark                                                         old allocs     new allocs     delta
BenchmarkCounterWithLabelValues-4                                 0              0              +0.00%
BenchmarkCounterWithLabelValuesConcurrent-4                       0              0              +0.00%
BenchmarkCounterWithMappedLabels-4                                2              2              +0.00%
BenchmarkCounterWithPreparedMappedLabels-4                        0              0              +0.00%
BenchmarkCounterNoLabels-4                                        0              0              +0.00%
BenchmarkGaugeWithLabelValues-4                                   0              0              +0.00%
BenchmarkGaugeNoLabels-4                                          0              0              +0.00%
BenchmarkSummaryWithLabelValues-4                                 0              0              +0.00%
BenchmarkSummaryNoLabels-4                                        0              0              +0.00%
BenchmarkHistogramWithLabelValues-4                               0              0              +0.00%
BenchmarkHistogramNoLabels-4                                      0              0              +0.00%
BenchmarkMetricVecWithLabelValuesBasic-4                          0              0              +0.00%
BenchmarkMetricVecWithLabelValues2Keys10ValueCardinality-4        0              0              +0.00%
BenchmarkMetricVecWithLabelValues4Keys10ValueCardinality-4        0              0              +0.00%
BenchmarkMetricVecWithLabelValues2Keys100ValueCardinality-4       0              0              +0.00%
BenchmarkMetricVecWithLabelValues10Keys100ValueCardinality-4      0              0              +0.00%
BenchmarkMetricVecWithLabelValues10Keys1000ValueCardinality-4     0              0              +0.00%

benchmark                                                         old bytes     new bytes     delta
BenchmarkCounterWithLabelValues-4                                 0             0             +0.00%
BenchmarkCounterWithLabelValuesConcurrent-4                       0             0             +0.00%
BenchmarkCounterWithMappedLabels-4                                336           336           +0.00%
BenchmarkCounterWithPreparedMappedLabels-4                        0             0             +0.00%
BenchmarkCounterNoLabels-4                                        0             0             +0.00%
BenchmarkGaugeWithLabelValues-4                                   0             0             +0.00%
BenchmarkGaugeNoLabels-4                                          0             0             +0.00%
BenchmarkSummaryWithLabelValues-4                                 0             0             +0.00%
BenchmarkSummaryNoLabels-4                                        0             0             +0.00%
BenchmarkHistogramWithLabelValues-4                               0             0             +0.00%
BenchmarkHistogramNoLabels-4                                      0             0             +0.00%
BenchmarkMetricVecWithLabelValuesBasic-4                          0             0             +0.00%
BenchmarkMetricVecWithLabelValues2Keys10ValueCardinality-4        0             0             +0.00%
BenchmarkMetricVecWithLabelValues4Keys10ValueCardinality-4        0             0             +0.00%
BenchmarkMetricVecWithLabelValues2Keys100ValueCardinality-4       0             0             +0.00%
BenchmarkMetricVecWithLabelValues10Keys100ValueCardinality-4      0             0             +0.00%
BenchmarkMetricVecWithLabelValues10Keys1000ValueCardinality-4     0             0             +0.00%
```

Signed-off-by: Stephen J Day <stephen.day@docker.com>
2016-08-15 16:47:53 -07: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
Bjoern Rabenstein 25db044749 Fix doc comment typo 2016-08-15 23:22:46 +02:00
beorn7 390e874a3f Fix doc comment typo 2016-08-15 15:54:18 +02:00
Björn Rabenstein 66058aac3a Merge pull request #214 from prometheus/beorn7/registry
Create a public registry interface and separate out HTTP exposition
2016-08-15 13:47:46 +02:00
beorn7 a6321dd0b1 Create a "merge gatherer"
This allows to finally get rid of the infamous injection hook in the
interface. The old SetMetricFamilyInjectionHook still exist as a
deprecated function but is now implemented with the new plumbing under
the hood.

Now that we have multiple Gatherer implementation, I renamed
push.Registry to push.FromGatherer.

This commit also improves the consistency checks, which happened as a
byproduct of the refactoring to allow checking in both the "merge
gatherer" Gatherers as well as in the normal Registry.
2016-08-12 21:34:17 +02:00
beorn7 1dc03a72f6 Replace hashicorp/go-multierror by own implementation
The own implementation is much easier as it only has to serve our one
use case.
2016-08-04 16:03:06 +02:00
beorn7 f0c45acc50 Rename Deliver into Gather 2016-08-04 15:26:27 +02:00
beorn7 f9c977b1d6 Doc: Make the AlreadyRegisteredError example a real example 2016-08-04 11:41:02 +02:00
beorn7 bc0b2a3b17 Move http stuff in its own package promhttp
To keep backwards compatibility while not creating circular import
chains, some code had to be duplicated. But all functions using it
have been declared deprecated hereby.

The new ways of instrumenting handlers will all go into the new
package, and ultimately, the prometheus package itself will be
completely igorant of HTTP.
2016-08-03 18:06:48 +02: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 e5c6302150 Fix a number of doc comments and similar nits 2016-08-03 12:23:37 +02:00
beorn7 5a918da56d Tweaked push package
- Moved the Deliverer parameter to the end of the list to mirror
  Collectors in push.Collectors.
- Improved doc comment and added an example for push.Registry.
2016-08-03 12:00:19 +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 9c3fe750dd Expose the registry implementation and add two interfaces.
Registry is now a struct, which implements two interfaces, Registrerer
and Deliverer. The latter is particularly important as it is now the
argument type for pushes and HTTP handler construction (i.e. it is
easy to implement a custom Deliverer for testing or other
purposes). The Registerer interface is not used as a parameter type
but can (and should) be used by users of custom registries so that
they can easily do things like mocking it out for testing purposes.

With the broken up interfaces, adding MustRegister to the interface is
not such a big deal anymore (interface is still small). And since
setting the injection hook is such a rare thing to happen, it is
acceptable to not have it in any of the interfaces.

The renaming from `Collect` to `Deliver` was done to avoid confusion
with Collectors. (The registry _collects_ from the Collectors, and
then _delivers_ to the exposition mechanism.)
2016-08-03 01:02:34 +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
Fabian Reinartz 52437c81da Merge pull request #213 from stapelberg/patch-1
api: document goroutine safeness
2016-08-02 00:22:46 -07:00
Brian Brazil b672480095 Merge pull request #215 from djui/patch-1
Fix typo in doc string
2016-08-01 22:18:14 +01:00
Uwe Dauernheim c1e8a41238 Fix typo in doc string 2016-08-01 23:14:45 +02:00
Michael Stapelberg 7b5f88727a api: document goroutine safeness 2016-08-01 00:11:57 +02:00
Björn Rabenstein 28be15864e Merge pull request #211 from andrewstuart/variadic-register
Add *RegisterAll functions with variadic args
2016-07-12 00:22:38 +02:00
Andrew Stuart e63e6e3db7
Extend MustRegister function to accept variadic args 2016-07-11 15:04:23 -07:00
Brian Brazil 9f1ed1ed4a Merge pull request #209 from mattbostock/fix_doc_indentation
Fix GoDoc indentation
2016-06-27 15:36:20 +01: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
Fabian Reinartz 928b9836d4 Merge pull request #208 from chrislonng/master
comment contains some misspell
2016-06-27 12:12:15 +02:00