github.com/wfusion/gofusion@v1.1.14/common/infra/metrics/README.md (about)

     1  go-metrics
     2  ==========
     3  
     4  This library provides a `metrics` package which can be used to instrument code,
     5  expose application metrics, and profile runtime performance in a flexible manner.
     6  
     7  Current API: [![GoDoc](https://godoc.org/github.com/hashicorp/go-metrics?status.svg)](https://godoc.org/github.com/hashicorp/go-metrics)
     8  
     9  Sinks
    10  -----
    11  
    12  The `metrics` package makes use of a `MetricSink` interface to support delivery
    13  to any type of backend. Currently the following sinks are provided:
    14  
    15  * StatsiteSink : Sinks to a [statsite](https://github.com/statsite/statsite/) instance (TCP)
    16  * StatsdSink: Sinks to a [StatsD](https://github.com/statsd/statsd/) / statsite instance (UDP)
    17  * PrometheusSink: Sinks to a [Prometheus](http://prometheus.io/) metrics endpoint (exposed via HTTP for scrapes)
    18  * InmemSink : Provides in-memory aggregation, can be used to export stats
    19  * FanoutSink : Sinks to multiple sinks. Enables writing to multiple statsite instances for example.
    20  * BlackholeSink : Sinks to nowhere
    21  
    22  In addition to the sinks, the `InmemSignal` can be used to catch a signal,
    23  and dump a formatted output of recent metrics. For example, when a process gets
    24  a SIGUSR1, it can dump to stderr recent performance metrics for debugging.
    25  
    26  Labels
    27  ------
    28  
    29  Most metrics do have an equivalent ending with `WithLabels`, such methods
    30  allow to push metrics with labels and use some features of underlying Sinks
    31  (ex: translated into Prometheus labels).
    32  
    33  Since some of these labels may increase the cardinality of metrics, the
    34  library allows filtering labels using a allow/block list filtering system
    35  which is global to all metrics.
    36  
    37  * If `Config.AllowedLabels` is not nil, then only labels specified in this value will be sent to underlying Sink, otherwise, all labels are sent by default.
    38  * If `Config.BlockedLabels` is not nil, any label specified in this value will not be sent to underlying Sinks.
    39  
    40  By default, both `Config.AllowedLabels` and `Config.BlockedLabels` are nil, meaning that
    41  no tags are filtered at all, but it allows a user to globally block some tags with high
    42  cardinality at the application level.
    43  
    44  Examples
    45  --------
    46  
    47  Here is an example of using the package:
    48  
    49  ```go
    50  func SlowMethod() {
    51      // Profiling the runtime of a method
    52      defer metrics.MeasureSince([]string{"SlowMethod"}, time.Now())
    53  }
    54  
    55  // Configure a statsite sink as the global metrics sink
    56  sink, _ := metrics.NewStatsiteSink("statsite:8125")
    57  metrics.NewGlobal(metrics.DefaultConfig("service-name"), sink)
    58  
    59  // Emit a Key/Value pair
    60  metrics.EmitKey([]string{"questions", "meaning of life"}, 42)
    61  ```
    62  
    63  Here is an example of setting up a signal handler:
    64  
    65  ```go
    66  // Setup the inmem sink and signal handler
    67  inm := metrics.NewInmemSink(10*time.Second, time.Minute)
    68  sig := metrics.DefaultInmemSignal(inm)
    69  metrics.NewGlobal(metrics.DefaultConfig("service-name"), inm)
    70  
    71  // Run some code
    72  inm.SetGauge([]string{"foo"}, 42)
    73  inm.EmitKey([]string{"bar"}, 30)
    74  
    75  inm.IncrCounter([]string{"baz"}, 42)
    76  inm.IncrCounter([]string{"baz"}, 1)
    77  inm.IncrCounter([]string{"baz"}, 80)
    78  
    79  inm.AddSample([]string{"method", "wow"}, 42)
    80  inm.AddSample([]string{"method", "wow"}, 100)
    81  inm.AddSample([]string{"method", "wow"}, 22)
    82  
    83  ....
    84  ```
    85  
    86  When a signal comes in, output like the following will be dumped to stderr:
    87  
    88      [2014-01-28 14:57:33.04 -0800 PST][G] 'foo': 42.000
    89      [2014-01-28 14:57:33.04 -0800 PST][P] 'bar': 30.000
    90      [2014-01-28 14:57:33.04 -0800 PST][C] 'baz': Count: 3 Min: 1.000 Mean: 41.000 Max: 80.000 Stddev: 39.509
    91      [2014-01-28 14:57:33.04 -0800 PST][S] 'method.wow': Count: 3 Min: 22.000 Mean: 54.667 Max: 100.000 Stddev: 40.513