telegraf

README

Telegraf

Telegraf is an agent for collecting, processing, aggregating, and writing metrics.

Design goals are to have a minimal memory footprint with a plugin system so that developers in the community can easily add support for collecting metrics.

Telegraf is plugin-driven and has the concept of 4 distinct plugin types:

1. Input Plugins collect metrics from the system, services, or 3rd party APIs
2. Processor Plugins transform, decorate, and/or filter metrics
3. Aggregator Plugins create aggregate metrics (e.g. mean, min, max, quantiles, etc.)
4. Output Plugins write metrics to various destinations

New plugins are designed to be easy to contribute, pull requests are welcomed and we work to incorporate as many pull requests as possible.

Try in Browser 🚀

You can try Telegraf right in your browser in the Telegraf playground.

Contributing

There are many ways to contribute:

• Fix and report bugs
• Improve documentation
• Review code and feature proposals
• Answer questions and discuss here on github and on the Community Site
• Contribute plugins

Installation:

You can download the binaries directly from the downloads page or from the releases section.

Ansible Role:

Ansible role: https://github.com/rossmcdonald/telegraf

From Source:

Telegraf requires golang version 1.10 or newer, the Makefile requires GNU make.

1. Install Go >=1.10 (1.12 recommended)
2. Install dep ==v0.5.0
3. Download Telegraf source:

   go get -d github.com/influxdata/telegraf
   

4. Run make from the source directory

   cd "$HOME/go/src/github.com/influxdata/telegraf"
   make
   

Changelog

View the changelog for the latest updates and changes by version.

Nightly Builds

These builds are generated from the master branch:

• telegraf_nightly_amd64.deb
• telegraf_nightly_arm64.deb
• telegraf-nightly.arm64.rpm
• telegraf_nightly_armel.deb
• telegraf-nightly.armel.rpm
• telegraf_nightly_armhf.deb
• telegraf-nightly.armv6hl.rpm
• telegraf-nightly_freebsd_amd64.tar.gz
• telegraf-nightly_freebsd_i386.tar.gz
• telegraf_nightly_i386.deb
• telegraf-nightly.i386.rpm
• telegraf-nightly_linux_amd64.tar.gz
• telegraf-nightly_linux_arm64.tar.gz
• telegraf-nightly_linux_armel.tar.gz
• telegraf-nightly_linux_armhf.tar.gz
• telegraf-nightly_linux_i386.tar.gz
• telegraf-nightly_linux_s390x.tar.gz
• telegraf_nightly_s390x.deb
• telegraf-nightly.s390x.rpm
• telegraf-nightly_windows_amd64.zip
• telegraf-nightly_windows_i386.zip
• telegraf-nightly.x86_64.rpm
• telegraf-static-nightly_linux_amd64.tar.gz

How to use it:

See usage with:

telegraf --help

Generate a telegraf config file:

telegraf config > telegraf.conf

Generate config with only cpu input & influxdb output plugins defined:

telegraf --input-filter cpu --output-filter influxdb config

Run a single telegraf collection, outputing metrics to stdout:

telegraf --config telegraf.conf --test

Run telegraf with all plugins defined in config file:

telegraf --config telegraf.conf

Run telegraf, enabling the cpu & memory input, and influxdb output plugins:

telegraf --config telegraf.conf --input-filter cpu:mem --output-filter influxdb

Documentation

Latest Release Documentation.

For documentation on the latest development code see the documentation index.

Input Plugins

• activemq
• aerospike
• amqp_consumer (rabbitmq)
• apache
• aurora
• aws cloudwatch
• bcache
• beanstalkd
• bind
• bond
• burrow
• cassandra (deprecated, use jolokia2)
• ceph
• cgroup
• chrony
• cisco_telemetry_gnmi
• cisco_telemetry_mdt
• cloud_pubsub Google Cloud Pub/Sub
• cloud_pubsub_push Google Cloud Pub/Sub push endpoint
• conntrack
• consul
• couchbase
• couchdb
• cpu
• DC/OS
• diskio
• disk
• disque
• dmcache
• dns query time
• docker
• docker_log
• dovecot
• ecs (Amazon Elastic Container Service, Fargate)
• elasticsearch
• exec (generic executable plugin, support JSON, influx, graphite and nagios)
• fail2ban
• fibaro
• file
• filestat
• filecount
• fluentd
• github
• graylog
• haproxy
• hddtemp
• httpjson (generic JSON-emitting http service plugin)
• http_listener (deprecated, renamed to influxdb_listener)
• http_listener_v2
• http (generic HTTP plugin, supports using input data formats)
• http_response
• icinga2
• influxdb
• influxdb_listener
• internal
• interrupts
• ipmi_sensor
• ipset
• iptables
• ipvs
• jenkins
• jolokia2 (java, cassandra, kafka)
• jolokia (deprecated, use jolokia2)
• jti_openconfig_telemetry
• kafka_consumer
• kapacitor
• kinesis
• kernel
• kernel_vmstat
• kibana
• kubernetes
• kube_inventory
• leofs
• linux_sysctl_fs
• logparser
• lustre2
• mailchimp
• mcrouter
• memcached
• mem
• mesos
• minecraft
• mongodb
• mqtt_consumer
• multifile
• mysql
• nats_consumer
• nats
• neptune_apex
• net
• net_response
• netstat
• nginx
• nginx_plus_api
• nginx_plus
• nginx_upstream_check
• nginx_vts
• nsq_consumer
• nsq
• nstat
• ntpq
• nvidia_smi
• openldap
• opensmtpd
• openweathermap
• pf
• pgbouncer
• phpfpm
• phusion passenger
• ping
• postfix
• postgresql_extensible
• postgresql
• powerdns
• powerdns_recursor
• processes
• procstat
• prometheus (can be used for Caddy server)
• puppetagent
• rabbitmq
• raindrops
• redis
• rethinkdb
• riak
• salesforce
• sensors
• smart
• snmp_legacy
• snmp
• socket_listener
• solr
• sql server (microsoft)
• stackdriver
• statsd
• swap
• syslog
• sysstat
• system
• tail
• temp
• tcp_listener
• teamspeak
• tengine
• tomcat
• twemproxy
• udp_listener
• unbound
• varnish
• vsphere VMware vSphere
• webhooks
  • filestack
  • github
  • mandrill
  • papertrail
  • particle
  • rollbar
• win_perf_counters (windows performance counters)
• win_services
• wireless
• x509_cert
• zfs
• zipkin
• zookeeper

Parsers

• InfluxDB Line Protocol
• Collectd
• CSV
• Dropwizard
• FormUrlencoded
• Graphite
• Grok
• JSON
• Logfmt
• Nagios
• Value, ie: 45 or "booyah"
• Wavefront

Serializers

• InfluxDB Line Protocol
• JSON
• Graphite
• ServiceNow
• SplunkMetric
• Carbon2
• Wavefront

Processor Plugins

• converter
• date
• enum
• override
• parser
• pivot
• printer
• regex
• rename
• strings
• topk
• unpivot

Aggregator Plugins

• basicstats
• final
• histogram
• minmax
• valuecounter

Output Plugins

• influxdb (InfluxDB 1.x)
• influxdb_v2 (InfluxDB 2.x)
• amon
• amqp (rabbitmq)
• application_insights
• aws kinesis
• aws cloudwatch
• azure_monitor
• cloud_pubsub Google Cloud Pub/Sub
• cratedb
• datadog
• discard
• elasticsearch
• file
• graphite
• graylog
• health
• http
• instrumental
• kafka
• librato
• mqtt
• nats
• nsq
• opentsdb
• prometheus
• riemann
• riemann_legacy
• socket_writer
• stackdriver
• syslog
• tcp
• udp
• wavefront

Documentation

Index

• type Accumulator
• type AggregatingOutput
• type Aggregator
• type DeliveryInfo
• type Field
• type Initializer
• type Input
• type Metric
• type Output
• type Processor
• type ServiceInput
• type Tag
• type TrackingAccumulator
• type TrackingID
• type ValueType

Types

type Accumulator

type Accumulator interface {
	// AddFields adds a metric to the accumulator with the given measurement
	// name, fields, and tags (and timestamp). If a timestamp is not provided,
	// then the accumulator sets it to "now".
	AddFields(measurement string,
		fields map[string]interface{},
		tags map[string]string,
		t ...time.Time)

	// AddGauge is the same as AddFields, but will add the metric as a "Gauge" type
	AddGauge(measurement string,
		fields map[string]interface{},
		tags map[string]string,
		t ...time.Time)

	// AddCounter is the same as AddFields, but will add the metric as a "Counter" type
	AddCounter(measurement string,
		fields map[string]interface{},
		tags map[string]string,
		t ...time.Time)

	// AddSummary is the same as AddFields, but will add the metric as a "Summary" type
	AddSummary(measurement string,
		fields map[string]interface{},
		tags map[string]string,
		t ...time.Time)

	// AddHistogram is the same as AddFields, but will add the metric as a "Histogram" type
	AddHistogram(measurement string,
		fields map[string]interface{},
		tags map[string]string,
		t ...time.Time)

	// AddMetric adds an metric to the accumulator.
	AddMetric(Metric)

	// SetPrecision sets the timestamp rounding precision.  All metrics addeds
	// added to the accumulator will have their timestamp rounded to the
	// nearest multiple of precision.
	SetPrecision(precision time.Duration)

	// Report an error.
	AddError(err error)

	// Upgrade to a TrackingAccumulator with space for maxTracked
	// metrics/batches.
	WithTracking(maxTracked int) TrackingAccumulator
}

Accumulator allows adding metrics to the processing flow.

type AggregatingOutput

type AggregatingOutput interface {
	Output

	// Add the metric to the aggregator
	Add(in Metric)
	// Push returns the aggregated metrics and is called every flush interval.
	Push() []Metric
	// Reset signals the the aggregator period is completed.
	Reset()
}

AggregatingOutput adds aggregating functionality to an Output. May be used if the Output only accepts a fixed set of aggregations over a time period. These functions may be called concurrently to the Write function.

type Aggregator

type Aggregator interface {
	// SampleConfig returns the default configuration of the Input.
	SampleConfig() string

	// Description returns a one-sentence description on the Input.
	Description() string

	// Add the metric to the aggregator.
	Add(in Metric)

	// Push pushes the current aggregates to the accumulator.
	Push(acc Accumulator)

	// Reset resets the aggregators caches and aggregates.
	Reset()
}

Aggregator is an interface for implementing an Aggregator plugin. the RunningAggregator wraps this interface and guarantees that Add, Push, and Reset can not be called concurrently, so locking is not required when implementing an Aggregator plugin.

type DeliveryInfo

type DeliveryInfo interface {
	// ID is the TrackingID
	ID() TrackingID

	// Delivered returns true if the metric was processed successfully.
	Delivered() bool
}

DeliveryInfo provides the results of a delivered metric group.

type Field

type Field struct {
	Key   string
	Value interface{}
}

type Initializer

type Initializer interface {
	// Init performs one time setup of the plugin and returns an error if the
	// configuration is invalid.
	Init() error
}

Initializer is an interface that all plugin types: Inputs, Outputs, Processors, and Aggregators can optionally implement to initialize the plugin.

type Input

type Input interface {
	// SampleConfig returns the default configuration of the Input
	SampleConfig() string

	// Description returns a one-sentence description on the Input
	Description() string

	// Gather takes in an accumulator and adds the metrics that the Input
	// gathers. This is called every "interval"
	Gather(Accumulator) error
}

type Metric

type Metric interface {
	// Getting data structure functions
	Name() string
	Tags() map[string]string
	TagList() []*Tag
	Fields() map[string]interface{}
	FieldList() []*Field
	Time() time.Time
	Type() ValueType

	// Name functions
	SetName(name string)
	AddPrefix(prefix string)
	AddSuffix(suffix string)

	// Tag functions
	GetTag(key string) (string, bool)
	HasTag(key string) bool
	AddTag(key, value string)
	RemoveTag(key string)

	// Field functions
	GetField(key string) (interface{}, bool)
	HasField(key string) bool
	AddField(key string, value interface{})
	RemoveField(key string)

	SetTime(t time.Time)

	// HashID returns an unique identifier for the series.
	HashID() uint64

	// Copy returns a deep copy of the Metric.
	Copy() Metric

	// Accept marks the metric as processed successfully and written to an
	// output.
	Accept()

	// Reject marks the metric as processed unsuccessfully.
	Reject()

	// Drop marks the metric as processed successfully without being written
	// to any output.
	Drop()

	// Mark Metric as an aggregate
	SetAggregate(bool)
	IsAggregate() bool
}

type Output

type Output interface {
	// Connect to the Output
	Connect() error
	// Close any connections to the Output
	Close() error
	// Description returns a one-sentence description on the Output
	Description() string
	// SampleConfig returns the default configuration of the Output
	SampleConfig() string
	// Write takes in group of points to be written to the Output
	Write(metrics []Metric) error
}

type Processor

type Processor interface {
	// SampleConfig returns the default configuration of the Input
	SampleConfig() string

	// Description returns a one-sentence description on the Input
	Description() string

	// Apply the filter to the given metric.
	Apply(in ...Metric) []Metric
}

type ServiceInput

type ServiceInput interface {
	Input

	// Start the ServiceInput.  The Accumulator may be retained and used until
	// Stop returns.
	Start(Accumulator) error

	// Stop stops the services and closes any necessary channels and connections
	Stop()
}

type Tag

type Tag struct {
	Key   string
	Value string
}

type TrackingAccumulator

type TrackingAccumulator interface {
	Accumulator

	// Add the Metric and arrange for tracking feedback after processing..
	AddTrackingMetric(m Metric) TrackingID

	// Add a group of Metrics and arrange for a signal when the group has been
	// processed.
	AddTrackingMetricGroup(group []Metric) TrackingID

	// Delivered returns a channel that will contain the tracking results.
	Delivered() <-chan DeliveryInfo
}

TrackingAccumulator is an Accumulator that provides a signal when the metric has been fully processed. Sending more metrics than the accumulator has been allocated for without reading status from the Accepted or Rejected channels is an error.

type TrackingID

type TrackingID uint64

TrackingID uniquely identifies a tracked metric group

type ValueType

type ValueType int

ValueType is an enumeration of metric types that represent a simple value.

const (
	Counter ValueType
	Gauge
	Untyped
	Summary
	Histogram
)

Possible values for the ValueType enum.