README
¶
metrics
A library for collecting statsd metrics.
The library's only strong opinion is that your application should catalog the names and types of the metrics that it generates. Other than that, it is just a convenient, generic wrapper around go-metrics for statsd, specifically.
Install
go get github.com/rclark/metrics
Configure a client
The library defines a client struct that you configure with
- a list of tags that should be applied to all metrics the client emits, and
- the address for a statsd sink.
You can choose whether to configure a package-global client, or pass the a client through your application.
// To create a client struct to pass through your application:
client, err := metrics.NewClient(metrics.WithSinkAddress("0.0.0.0:8125"))
// Or to configure the global client:
err := metrics.GlobalConfig(metrics.WithSinkAddress("0.0.0.0:8125"))
Define metric identifiers
In your codebase, define identifiers for each metric that your application generates. An identifier is just the metric's name, and its type. There are 4 types:
- Count: Used to track the number of events per unit time.
- Gauge: Used to track a measured value at a point in time.
- Distribution: Used to track the statistical distribution of a value over time.
- Timing: Used to track the statistical distribution of a duration over time.
Use a type-specific function to generate metric identifiers in your application. By doing this in one place in your program, you will have a catalog of all the metrics that are important to your application.
var BackgroundJobsFailed = metrics.CountMetric("background.jobs.failed")
var BackgroundJobsDuration = metrics.TimingMetric("background.jobs.duration")
var BackgroundJobsQueueDepth = metrics.GaugeMetric("background.jobs.queue")
Emit metrics
Use the Emit() function if you are passing a client through your application:
err := metrics.Emit(client, BackgroundJobsFailed, 1)
Or use the GlobalEmit() function if you are relying on a package-global client:
err := metrics.GlobalEmit(BackgroundJobsFailed, 1)
Documentation
¶
Overview ¶
Package metrics is a library for collecting statsd metrics.
The library's only strong opinion is that your application should catalog the names and types of the metrics that it generates. Other than that, it is just a convenient, generic wrapper around go-metrics for statsd, specifically.
Index ¶
- func Emit[V valueType](client Client, metric Identifier[V], val V, opts ...metricOption) error
- func GlobalClose() error
- func GlobalConfig(opts ...clientOption) (err error)
- func GlobalEmit[V valueType](metric Identifier[V], val V, opts ...metricOption) error
- func WithPersistentTags(tags ...string) clientOption
- func WithSinkAddress(addr string) clientOption
- func WithTags(tags ...string) metricOption
- type Client
- type Identifier
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Emit ¶
func Emit[V valueType](client Client, metric Identifier[V], val V, opts ...metricOption) error
Emit emits a value for the provided metric Identifier using the provided Client.
Options include:
Example ¶
package main
import (
"log"
"github.com/rclark/metrics"
)
func main() {
client, err := metrics.NewClient()
if err != nil {
log.Fatal(err)
}
var BackgroundJobsFailed = metrics.CountMetric("background.jobs.failed")
err = metrics.Emit(
client, BackgroundJobsFailed, 1,
metrics.WithTags("job-name:failure"),
)
if err != nil {
log.Fatal(err)
}
}
Output:
func GlobalClose ¶
func GlobalClose() error
GlobalClose can be used to flush any metrics in the global Client, prior to an application shutting down.
func GlobalConfig ¶
func GlobalConfig(opts ...clientOption) (err error)
GlobalConfig configures the package's global Client, allowing for the use of the GlobalEmit function.
Options include:
Example ¶
package main
import (
"fmt"
"log"
"os"
"github.com/rclark/metrics"
)
func main() {
host, _ := os.Hostname()
err := metrics.GlobalConfig(
metrics.WithPersistentTags("env:testing", fmt.Sprintf("host:%s", host)),
metrics.WithSinkAddress("127.0.0.1:8125"),
)
if err != nil {
log.Fatal(err)
}
defer metrics.GlobalClose()
}
Output:
func GlobalEmit ¶
func GlobalEmit[V valueType](metric Identifier[V], val V, opts ...metricOption) error
GlobalEmit emits a value for the provided metric Identifier using the Client configured for the package globally, see GlobalConfig.
Options include:
Example ¶
package main
import (
"log"
"github.com/rclark/metrics"
)
func main() {
var BackgroundJobsFailed = metrics.CountMetric("background.jobs.failed")
err := metrics.GlobalEmit(
BackgroundJobsFailed, 1,
metrics.WithTags("job-name:failure"),
)
if err != nil {
log.Fatal(err)
}
}
Output:
func WithPersistentTags ¶
func WithPersistentTags(tags ...string) clientOption
WithPersistentTags configures a set of tags that should be applied to all metrics emitted by the Client. Tags should be strings of the form key:value.
func WithSinkAddress ¶
func WithSinkAddress(addr string) clientOption
WithSinkAddress sets the address of the statsd sink to which the Client will emit metrics. The default address is "127.0.0.1:8125".
func WithTags ¶
func WithTags(tags ...string) metricOption
WithTags applies a set of tags to the metric being emitted. These are appended to the Client's persistent tags (see WithPersistentTags). Tags should be strings of the form key:value.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is configured to emit metrics to a statsd sink.
func NewClient ¶
NewClient creates a new Client.
Options include:
Example ¶
package main
import (
"fmt"
"log"
"os"
"github.com/rclark/metrics"
)
func main() {
host, _ := os.Hostname()
client, err := metrics.NewClient(
metrics.WithPersistentTags("env:testing", fmt.Sprintf("host:%s", host)),
metrics.WithSinkAddress("127.0.0.1:8125"),
)
if err != nil {
log.Fatal(err)
}
defer client.Close()
}
Output:
type Identifier ¶
type Identifier[V valueType] struct {
// contains filtered or unexported fields
}
Identifier holds the name and type of a single metric.
func CountMetric ¶
func CountMetric(name string) Identifier[int32]
CountMetric creates a metric Identifier for a count metric.
func DistributionMetric ¶
func DistributionMetric(name string) Identifier[float32]
DistributionMetric creates a metric Identifier for a distribution metric.
func GaugeMetric ¶
func GaugeMetric(name string) Identifier[float32]
GaugeMetric creates a metric Identifier for a gauge metric.
func TimingMetric ¶
func TimingMetric(name string) Identifier[time.Duration]
TimingMetric creates a metric Identifier for a distribution metric that captures timing.
Source Files
Directories