README.md

go-metrics-stackdriver

This library provides a stackdriver sink for applications instrumented with the go-metrics library.

🚨 Warning

This is not an officially supported Google product.

In general the author of this package would recommend instrumenting custom metrics for new code by following the official GCP documentation, especially for new applications.

This package is intended as a way to publish metrics for applications that are already instrumented with go-metrics without having to use a sidecar process like stackdriver-prometheus-sidecar.

🚨 Upgrading

Between v0.5.0 and v0.6.0, the behavior of the IncrCounter() method changed: previously it would create a GAUGE metric kind, but from v0.6.0 forward it will create a CUMULATIVE metric kind. (See #18 for a discussion.)

However, once a MetricDescriptor has been created in Google Cloud Monitoring, its metricKind field cannot be changed. So if you have any existing GAUGE metrics that were created by IncrCounter(), you will see errors in your logs when the v0.6.0 client attempts to update them and fails. Your options for handling this are:

1. Change the name of the metric you are passing to IncrCounter (creating a new metricDescriptor with a different name), or:
2. Delete the existing metricDescriptor using the delete API and let go-metrics re-create it as a CUMULATIVE metric

Additionally, v0.6.0 adds ResetCounter() and ResetCounterWithLabels() methods: calling these methods resets the counter value to zero.

Details

stackdriver.NewSink's return value satisfies the go-metrics library's MetricSink interface. When providing a stackdriver.Sink to libraries and applications instrumented against MetricSink, the metrics will be aggregated within this library and written to stackdriver as Generic Task timeseries metrics.

Example

import "github.com/google/go-metrics-stackdriver"
...
client, _ := monitoring.NewMetricClient(context.Background())
ss := stackdriver.NewSink(client, &stackdriver.Config{
  ProjectID: projectID,
})
...
ss.SetGauge([]string{"foo"}, 42)
ss.IncrCounter([]string{"baz"}, 1)
ss.AddSample([]string{"method", "const"}, 200)

The full example can be run from a cloud shell console to test how metrics are collected and displayed.

You can also try out the example using Cloud Run!