| 0 | |
// Package metrics provides a framework for application instrumentation. All
|
| 1 | |
// metrics are safe for concurrent use. Considerable design influence has been
|
| 2 | |
// taken from https://github.com/codahale/metrics and https://prometheus.io.
|
|
0 |
// Package metrics provides a framework for application instrumentation. It's
|
|
1 |
// primarily designed to help you get started with good and robust
|
|
2 |
// instrumentation, and to help you migrate from a less-capable system like
|
|
3 |
// Graphite to a more-capable system like Prometheus. If your organization has
|
|
4 |
// already standardized on an instrumentation system like Prometheus, and has no
|
|
5 |
// plans to change, it may make sense to use that system's instrumentation
|
|
6 |
// library directly.
|
| 3 | 7 |
//
|
| 4 | |
// This package contains the common interfaces. Your code should take these
|
| 5 | |
// interfaces as parameters. Implementations are provided for different
|
| 6 | |
// instrumentation systems in the various subdirectories.
|
|
8 |
// This package provides three core metric abstractions (Counter, Gauge, and
|
|
9 |
// Histogram) and implementations for almost all common instrumentation
|
|
10 |
// backends. Each metric has an observation method (Add, Set, or Observe,
|
|
11 |
// respectively) used to record values, and a With method to "scope" the
|
|
12 |
// observation by various parameters. For example, you might have a Histogram to
|
|
13 |
// record request durations, parameterized by the method that's being called.
|
|
14 |
//
|
|
15 |
// var requestDuration metrics.Histogram
|
|
16 |
// // ...
|
|
17 |
// requestDuration.With("method", "MyMethod").Observe(time.Since(begin))
|
|
18 |
//
|
|
19 |
// This allows a single high-level metrics object (requestDuration) to work with
|
|
20 |
// many code paths somewhat dynamically. The concept of With is fully supported
|
|
21 |
// in some backends like Prometheus, and not supported in other backends like
|
|
22 |
// Graphite. So, With may be a no-op, depending on the concrete implementation
|
|
23 |
// you choose.
|
| 7 | 24 |
//
|
| 8 | 25 |
// Usage
|
| 9 | 26 |
//
|
| 10 | |
// Metrics are dependencies and should be passed to the components that need
|
|
27 |
// Metrics are dependencies, and should be passed to the components that need
|
| 11 | 28 |
// them in the same way you'd construct and pass a database handle, or reference
|
| 12 | |
// to another component. So, create metrics in your func main, using whichever
|
| 13 | |
// concrete implementation is appropriate for your organization.
|
|
29 |
// to another component. Metrics should *not* be created in the global scope.
|
|
30 |
// Instead, instantiate metrics in your func main, using whichever concrete
|
|
31 |
// implementation is appropriate for your organization.
|
| 14 | 32 |
//
|
| 15 | 33 |
// latency := prometheus.NewSummaryFrom(stdprometheus.SummaryOpts{
|
| 16 | 34 |
// Namespace: "myteam",
|
|
| 39 | 57 |
// api := NewAPI(store, logger, latency)
|
| 40 | 58 |
// http.ListenAndServe("/", api)
|
| 41 | 59 |
//
|
|
60 |
// Note that metrics are "write-only" interfaces.
|
|
61 |
//
|
| 42 | 62 |
// Implementation details
|
|
63 |
//
|
|
64 |
// All metrics are safe for concurrent use. Considerable design influence has
|
|
65 |
// been taken from https://github.com/codahale/metrics and
|
|
66 |
// https://prometheus.io.
|
| 43 | 67 |
//
|
| 44 | 68 |
// Each telemetry system has different semantics for label values, push vs.
|
| 45 | 69 |
// pull, support for histograms, etc. These properties influence the design of
|