stackdriver

README

Stackdriver Google Cloud Monitoring Output Plugin

This plugin writes to the Google Cloud Monitoring API (formerly Stackdriver) and requires authentication with Google Cloud using either a service account or user credentials

This plugin accesses APIs which are chargeable; you might incur costs.

Requires project to specify where Stackdriver metrics will be delivered to.

By default, Metrics are grouped by the namespace variable and metric key - eg: custom.googleapis.com/telegraf/system/load5. However, this is not the best practice. Setting metric_name_format = "official" will produce a more easily queried format of: metric_type_prefix/[namespace_]name_key/kind. If the global namespace is not set, it is omitted as well.

Resource type is configured by the resource_type variable (default global).

Additional resource labels can be configured by resource_labels. By default the required project_id label is always set to the project variable.

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Configuration

# Configuration for Google Cloud Stackdriver to send metrics to
[[outputs.stackdriver]]
  ## GCP Project
  project = "erudite-bloom-151019"

  ## The namespace for the metric descriptor
  ## This is optional and users are encouraged to set the namespace as a
  ## resource label instead. If omitted it is not included in the metric name.
  namespace = "telegraf"

  ## Metric Type Prefix
  ## The DNS name used with the metric type as a prefix.
  # metric_type_prefix = "custom.googleapis.com"

  ## Metric Name Format
  ## Specifies the layout of the metric name, choose from:
  ##  * path: 'metric_type_prefix_namespace_name_key'
  ##  * official: 'metric_type_prefix/namespace_name_key/kind'
  # metric_name_format = "path"

  ## Metric Data Type
  ## By default, telegraf will use whatever type the metric comes in as.
  ## However, for some use cases, forcing int64, may be preferred for values:
  ##   * source: use whatever was passed in
  ##   * double: preferred datatype to allow queries by PromQL.
  # metric_data_type = "source"

  ## Tags as resource labels
  ## Tags defined in this option, when they exist, are added as a resource
  ## label and not included as a metric label. The values from tags override
  ## the values defined under the resource_labels config options.
  # tags_as_resource_label = []

  ## Custom resource type
  # resource_type = "generic_node"

  ## Additional resource labels
  # [outputs.stackdriver.resource_labels]
  #   node_id = "$HOSTNAME"
  #   namespace = "myapp"
  #   location = "eu-north0"

Restrictions

Stackdriver does not support string values in custom metrics, any string fields will not be written.

The Stackdriver API does not allow writing points which are out of order, older than 24 hours, or more with resolution greater than than one per point minute. Since Telegraf writes the newest points first and moves backwards through the metric buffer, it may not be possible to write historical data after an interruption.

Points collected with greater than 1 minute precision may need to be aggregated before then can be written. Consider using the basicstats aggregator to do this.

Histogram / distribution and delta metrics are not yet supported. These will be dropped silently unless debugging is on.

Note that the plugin keeps an in-memory cache of the start times and last observed values of all COUNTER metrics in order to comply with the requirements of the stackdriver API. This cache is not GCed: if you remove a large number of counters from the input side, you may wish to restart telegraf to clear it.

Documentation

Index

• Constants
• func GetCounterCacheKey(m telegraf.Metric, f *telegraf.Field) string
• func NewCounterCache(log telegraf.Logger) *counterCache
• func NewCounterCacheEntry(value *monpb.TypedValue, ts *tspb.Timestamp) *counterCacheEntry
• type Stackdriver
  • func (s *Stackdriver) Close() error
  • func (s *Stackdriver) Connect() error
  • func (s *Stackdriver) Init() error
  • func (*Stackdriver) SampleConfig() string
  • func (s *Stackdriver) Write(metrics []telegraf.Metric) error

Constants

const (
	// QuotaLabelsPerMetricDescriptor is the limit
	// to labels (tags) per metric descriptor.
	QuotaLabelsPerMetricDescriptor = 10
	// QuotaStringLengthForLabelKey is the limit
	// to string length for label key.
	QuotaStringLengthForLabelKey = 100
	// QuotaStringLengthForLabelValue is the limit
	// to string length for label value.
	QuotaStringLengthForLabelValue = 1024

	// MaxInt is the max int64 value.
	MaxInt = int(^uint(0) >> 1)
)

Functions

func GetCounterCacheKey

func GetCounterCacheKey(m telegraf.Metric, f *telegraf.Field) string

func NewCounterCache

func NewCounterCache(log telegraf.Logger) *counterCache

func NewCounterCacheEntry

func NewCounterCacheEntry(value *monpb.TypedValue, ts *tspb.Timestamp) *counterCacheEntry

Types

type Stackdriver

type Stackdriver struct {
	Project              string            `toml:"project"`
	Namespace            string            `toml:"namespace"`
	ResourceType         string            `toml:"resource_type"`
	ResourceLabels       map[string]string `toml:"resource_labels"`
	MetricTypePrefix     string            `toml:"metric_type_prefix"`
	MetricNameFormat     string            `toml:"metric_name_format"`
	MetricDataType       string            `toml:"metric_data_type"`
	TagsAsResourceLabels []string          `toml:"tags_as_resource_label"`
	Log                  telegraf.Logger   `toml:"-"`
	// contains filtered or unexported fields
}

Stackdriver is the Google Stackdriver config info.

func (*Stackdriver) Close

func (s *Stackdriver) Close() error

Close will terminate the session to the backend, returning error if an issue arises.

func (*Stackdriver) Connect

func (s *Stackdriver) Connect() error

Connect initiates the primary connection to the GCP project.

func (*Stackdriver) Init

func (s *Stackdriver) Init() error

func (*Stackdriver) SampleConfig

func (*Stackdriver) SampleConfig() string

func (*Stackdriver) Write

func (s *Stackdriver) Write(metrics []telegraf.Metric) error

Split metrics up by timestamp and send to Google Cloud Stackdriver