stackdriver

README

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 https://github.com/google/go-metrics-stackdriver/issues/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!

Documentation

Overview

Package stackdriver provides a cloud monitoring sink for applications instrumented with the go-metrics library.

Index

• func DefaultBucketer(key []string) []float64
• func DefaultLabelExtractor(key []string, kind string) ([]string, []metrics.Label, error)
• type BucketFn
• type Config
• type ExtractLabelsFn
• type Logger
• type Sink
  • func NewSink(client *monitoring.MetricClient, config *Config) *Sink
  • func (s *Sink) AddSample(key []string, val float32)
  • func (s *Sink) AddSampleWithLabels(key []string, val float32, labels []metrics.Label)
  • func (s *Sink) Close(ctx context.Context) error
  • func (s *Sink) EmitKey(key []string, val float32)
  • func (s *Sink) IncrCounter(key []string, val float32)
  • func (s *Sink) IncrCounterWithLabels(key []string, val float32, labels []metrics.Label)
  • func (s *Sink) ResetCounter(key []string)
  • func (s *Sink) ResetCounterWithLabels(key []string, labels []metrics.Label)
  • func (s *Sink) SetGauge(key []string, val float32)
  • func (s *Sink) SetGaugeWithLabels(key []string, val float32, labels []metrics.Label)
  • func (s *Sink) Shutdown()

Functions

func DefaultBucketer

func DefaultBucketer(key []string) []float64

DefaultBucketer is the default BucketFn used to determing bucketing values for metrics.

func DefaultLabelExtractor

func DefaultLabelExtractor(key []string, kind string) ([]string, []metrics.Label, error)

DefaultLabelExtractor is the default ExtractLabelsFn and is a direct passthrough. Counter and Gauge metrics are renamed to include the type in their name to avoid duplicate metrics with the same name but different types (which is allowed by go-metrics but not by Stackdriver).

Types

type BucketFn

type BucketFn func([]string) []float64

BucketFn returns the histogram bucket thresholds based on the given metric name.

type Config

type Config struct {
	// The Google Cloud Project ID to publish metrics to.
	// Optional. GCP instance metadata is used to determine the ProjectID if
	// not set.
	ProjectID string
	// The label extractor provides a way to rewrite metric key into a new key
	// with multiple labels. This is useful if the instrumented code includes
	// variable parameters within a metric name.
	// Optional. Defaults to DefaultLabelExtractor.
	LabelExtractor ExtractLabelsFn
	// Prefix of the metrics recorded. Defaults to "go-metrics/" so a metric
	// "foo" will be recorded as "custom.googleapis.com/go-metrics/foo".
	Prefix *string
	// The bucketer is used to determine histogram bucket boundaries
	// for the sampled metrics. This will execute before the LabelExtractor.
	// Optional. Defaults to DefaultBucketer.
	Bucketer BucketFn
	// The interval between sampled metric points. Must be > 1 minute.
	// https://cloud.google.com/monitoring/custom-metrics/creating-metrics#writing-ts
	// Optional. Defaults to 1 minute.
	ReportingInterval time.Duration

	// The location of the running task. See:
	// https://cloud.google.com/monitoring/api/resources#tag_generic_task
	// Optional. GCP instance metadata is used to determine the location,
	// otherwise it defaults to 'global'.
	Location string
	// The namespace for the running task. See:
	// https://cloud.google.com/monitoring/api/resources#tag_generic_task
	// Optional. Defaults to 'default'.
	Namespace string
	// The job name for the running task. See:
	// https://cloud.google.com/monitoring/api/resources#tag_generic_task
	// Optional. Defaults to the running program name.
	Job string
	// The task ID for the running task. See:
	// https://cloud.google.com/monitoring/api/resources#tag_generic_task
	// Optional. Defaults to a combination of hostname+pid.
	TaskID string

	// Debug logging. Errors are always logged to stderr, but setting this to
	// true will log additional information that is helpful when debugging
	// errors.
	// Optional. Defaults to false.
	DebugLogs bool

	// MonitoredResource identifies the machine/service/resource that is
	// monitored. Different possible settings are defined here:
	// https://cloud.google.com/monitoring/api/resources
	//
	// Setting a nil MonitoredResource will run a defaultMonitoredResource
	// function.
	MonitoredResource *monitoredrespb.MonitoredResource

	// Logger that can be injected for custom log formatting.
	Logger Logger
}

Config options for the stackdriver Sink.

type ExtractLabelsFn

type ExtractLabelsFn func([]string, string) ([]string, []metrics.Label, error)

ExtractLabelsFn converts a given metric name and type into a new metric name and optionally additional labels. Errors will prevent the metric from writing to stackdriver.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
	Println(v ...interface{})
}

Logger is the log interface used in go-metrics-stackdriver

type Sink

type Sink struct {
	// contains filtered or unexported fields
}

Sink conforms to the metrics.MetricSink interface and is used to transmit metrics information to stackdriver.

Sink performs in-process aggregation of metrics to limit calls to stackdriver.

func NewSink

func NewSink(client *monitoring.MetricClient, config *Config) *Sink

NewSink creates a Sink to flush metrics to stackdriver every interval. The interval should be greater than 1 minute.

func (*Sink) AddSample

func (s *Sink) AddSample(key []string, val float32)

AddSample adds a sample to a histogram metric.

func (*Sink) AddSampleWithLabels

func (s *Sink) AddSampleWithLabels(key []string, val float32, labels []metrics.Label)

AddSampleWithLabels adds a sample to a histogram metric.

func (*Sink) Close

func (s *Sink) Close(ctx context.Context) error

Close closes the sink and flushes any remaining data.

func (*Sink) EmitKey

func (s *Sink) EmitKey(key []string, val float32)

EmitKey is not implemented.

func (*Sink) IncrCounter

func (s *Sink) IncrCounter(key []string, val float32)

IncrCounter increments a counter by a value.

func (*Sink) IncrCounterWithLabels

func (s *Sink) IncrCounterWithLabels(key []string, val float32, labels []metrics.Label)

IncrCounterWithLabels increments a counter by a value.

func (*Sink) ResetCounter

func (s *Sink) ResetCounter(key []string)

ResetCounter resets a counter to zero

func (*Sink) ResetCounterWithLabels

func (s *Sink) ResetCounterWithLabels(key []string, labels []metrics.Label)

ResetCounterWithLabels resets a counter to zero

func (*Sink) SetGauge

func (s *Sink) SetGauge(key []string, val float32)

SetGauge retains the last value it is set to.

func (*Sink) SetGaugeWithLabels

func (s *Sink) SetGaugeWithLabels(key []string, val float32, labels []metrics.Label)

SetGaugeWithLabels retains the last value it is set to.

func (*Sink) Shutdown

func (s *Sink) Shutdown()

Shutdown is a blocking function that flushes metrics in preparation of the application exiting.