xs/vendor/gopkg.in/hlandau/measurable.v1/README.md

Measurable: The useless Go metric registration package that doesn't do anything

Measurable is a Go library for managing the registration of metrics such as counters and gauges, no matter how that metric data is eventually consumed.

The most noteworthy feature of measurable is that it doesn't do anything. It contains no functionality for providing metric data to any external service, and it contains no actual metric implementations.

The purpose of measurable is to act as an integration nexus, essentially a matchmaker between metric sources and metric consumers. This creates the important feature that your application's metrics can be expressed completely independently of how those metrics are exported.

Measurable doesn't implement any metric or metric export logic because it strives to be a neutral intermediary, which abstracts the interface between metrics and metric exporters.

Import as: gopkg.in/hlandau/measurable.v1

Measurable

A Measurable is an object that represents some metric. It is obliged only to implement the following interface:

type Measurable interface {
  MsName() string
  MsType() Type
}

Measurable is designed around interface upgrades. If you want to actually do anything with a Measurable, you must attempt to cast it to an interface with the methods you need. A Measurable is not obliged to implement any interface besides Measurable, but almost always will.

Here are some common interfaces implemented by Measurables, in descending order of importance:

• MsName() string — get the Measurable name.
• MsType() Type — get the Measurable type.
• MsInt64() int64 — get the Measurable as an int64.
• String() string — the standard Go String() interface.

All Measurables should implement MsName() string and MsType() Type.

Measurable-specific methods should always be prefixed by Ms so it is clear they are intended for consumption by Measurable consumers.

MsName, MsType and MsInt64 should suffice for most consumers of Counter and Gauge metric types.

Metrics should be named in lowercase using dots to create a hierarchy and dashes to separate words, e.g. someserver.http.request-count. These metric names may be transmuted by consumers as necessary for some graphing systems, such as Prometheus (which allows only underscores).

Standard Bindings

For a package which makes it easy to register and consume measurables, see the easymetric package.

Of course, nothing requires you to use the easymetric package. You are free to escew it and make your own.

Background Reading

• On Nexuses
• See also: Configurable

Licence

© 2015 Hugo Landau <hlandau@devever.net>    MIT License