github.com/samgwo/go-ethereum@v1.8.2-0.20180302101319-49bcb5fbd55e/metrics/README.md (about)

     1  go-metrics
     2  ==========
     3  
     4  ![travis build status](https://travis-ci.org/rcrowley/go-metrics.svg?branch=master)
     5  
     6  Go port of Coda Hale's Metrics library: <https://github.com/dropwizard/metrics>.
     7  
     8  Documentation: <http://godoc.org/github.com/rcrowley/go-metrics>.
     9  
    10  Usage
    11  -----
    12  
    13  Create and update metrics:
    14  
    15  ```go
    16  c := metrics.NewCounter()
    17  metrics.Register("foo", c)
    18  c.Inc(47)
    19  
    20  g := metrics.NewGauge()
    21  metrics.Register("bar", g)
    22  g.Update(47)
    23  
    24  r := NewRegistry()
    25  g := metrics.NewRegisteredFunctionalGauge("cache-evictions", r, func() int64 { return cache.getEvictionsCount() })
    26  
    27  s := metrics.NewExpDecaySample(1028, 0.015) // or metrics.NewUniformSample(1028)
    28  h := metrics.NewHistogram(s)
    29  metrics.Register("baz", h)
    30  h.Update(47)
    31  
    32  m := metrics.NewMeter()
    33  metrics.Register("quux", m)
    34  m.Mark(47)
    35  
    36  t := metrics.NewTimer()
    37  metrics.Register("bang", t)
    38  t.Time(func() {})
    39  t.Update(47)
    40  ```
    41  
    42  Register() is not threadsafe. For threadsafe metric registration use
    43  GetOrRegister:
    44  
    45  ```go
    46  t := metrics.GetOrRegisterTimer("account.create.latency", nil)
    47  t.Time(func() {})
    48  t.Update(47)
    49  ```
    50  
    51  **NOTE:** Be sure to unregister short-lived meters and timers otherwise they will
    52  leak memory:
    53  
    54  ```go
    55  // Will call Stop() on the Meter to allow for garbage collection
    56  metrics.Unregister("quux")
    57  // Or similarly for a Timer that embeds a Meter
    58  metrics.Unregister("bang")
    59  ```
    60  
    61  Periodically log every metric in human-readable form to standard error:
    62  
    63  ```go
    64  go metrics.Log(metrics.DefaultRegistry, 5 * time.Second, log.New(os.Stderr, "metrics: ", log.Lmicroseconds))
    65  ```
    66  
    67  Periodically log every metric in slightly-more-parseable form to syslog:
    68  
    69  ```go
    70  w, _ := syslog.Dial("unixgram", "/dev/log", syslog.LOG_INFO, "metrics")
    71  go metrics.Syslog(metrics.DefaultRegistry, 60e9, w)
    72  ```
    73  
    74  Periodically emit every metric to Graphite using the [Graphite client](https://github.com/cyberdelia/go-metrics-graphite):
    75  
    76  ```go
    77  
    78  import "github.com/cyberdelia/go-metrics-graphite"
    79  
    80  addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:2003")
    81  go graphite.Graphite(metrics.DefaultRegistry, 10e9, "metrics", addr)
    82  ```
    83  
    84  Periodically emit every metric into InfluxDB:
    85  
    86  **NOTE:** this has been pulled out of the library due to constant fluctuations
    87  in the InfluxDB API. In fact, all client libraries are on their way out. see
    88  issues [#121](https://github.com/rcrowley/go-metrics/issues/121) and
    89  [#124](https://github.com/rcrowley/go-metrics/issues/124) for progress and details.
    90  
    91  ```go
    92  import "github.com/vrischmann/go-metrics-influxdb"
    93  
    94  go influxdb.InfluxDB(metrics.DefaultRegistry,
    95    10e9, 
    96    "127.0.0.1:8086", 
    97    "database-name", 
    98    "username", 
    99    "password"
   100  )
   101  ```
   102  
   103  Periodically upload every metric to Librato using the [Librato client](https://github.com/mihasya/go-metrics-librato):
   104  
   105  **Note**: the client included with this repository under the `librato` package
   106  has been deprecated and moved to the repository linked above.
   107  
   108  ```go
   109  import "github.com/mihasya/go-metrics-librato"
   110  
   111  go librato.Librato(metrics.DefaultRegistry,
   112      10e9,                  // interval
   113      "example@example.com", // account owner email address
   114      "token",               // Librato API token
   115      "hostname",            // source
   116      []float64{0.95},       // percentiles to send
   117      time.Millisecond,      // time unit
   118  )
   119  ```
   120  
   121  Periodically emit every metric to StatHat:
   122  
   123  ```go
   124  import "github.com/rcrowley/go-metrics/stathat"
   125  
   126  go stathat.Stathat(metrics.DefaultRegistry, 10e9, "example@example.com")
   127  ```
   128  
   129  Maintain all metrics along with expvars at `/debug/metrics`:
   130  
   131  This uses the same mechanism as [the official expvar](http://golang.org/pkg/expvar/)
   132  but exposed under `/debug/metrics`, which shows a json representation of all your usual expvars
   133  as well as all your go-metrics.
   134  
   135  
   136  ```go
   137  import "github.com/rcrowley/go-metrics/exp"
   138  
   139  exp.Exp(metrics.DefaultRegistry)
   140  ```
   141  
   142  Installation
   143  ------------
   144  
   145  ```sh
   146  go get github.com/rcrowley/go-metrics
   147  ```
   148  
   149  StatHat support additionally requires their Go client:
   150  
   151  ```sh
   152  go get github.com/stathat/go
   153  ```
   154  
   155  Publishing Metrics
   156  ------------------
   157  
   158  Clients are available for the following destinations:
   159  
   160  * Librato - https://github.com/mihasya/go-metrics-librato
   161  * Graphite - https://github.com/cyberdelia/go-metrics-graphite
   162  * InfluxDB - https://github.com/vrischmann/go-metrics-influxdb
   163  * Ganglia - https://github.com/appscode/metlia
   164  * Prometheus - https://github.com/deathowl/go-metrics-prometheus
   165  * DataDog - https://github.com/syntaqx/go-metrics-datadog
   166  * SignalFX - https://github.com/pascallouisperez/go-metrics-signalfx