telegraf

package module
v1.17.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2021 License: MIT Imports: 1 Imported by: 0

README

Telegraf Circle CI Docker pulls

Slack Status

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:

Minimum Requirements

Telegraf shares the same minimum requirements as Go:

  • Linux kernel version 2.6.23 or later
  • Windows 7 or later
  • FreeBSD 11.2 or later
  • MacOS 10.11 El Capitan or later

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 Go version 1.13 or newer, the Makefile requires GNU make.

  1. Install Go >=1.13 (1.15 recommended)
  2. Clone the Telegraf repository: 
    cd ~/src
git clone https://github.com/influxdata/telegraf.git
  3. Run make from the source directory 
    cd ~/src/telegraf
make
Changelog

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

Nightly Builds

These builds are generated from the master branch:

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 --section-filter agent:inputs:outputs --input-filter cpu --output-filter influxdb config
Run a single telegraf collection, outputting 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

Parsers

Serializers

Processor Plugins

Aggregator Plugins

Output Plugins

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Accumulator added in v0.2.0 

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 added in v1.17.3 

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 added in v1.17.3 

type Aggregator interface {
	PluginDescriber

	// 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 added in v1.17.3 

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 added in v1.17.3 

type Field struct {
	Key   string
	Value interface{}
}

Field represents a single field key and value.

type Initializer added in v1.17.3 

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 added in v1.17.3 

type Input interface {
	PluginDescriber

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

type Logger added in v1.17.3 

type Logger interface {
	// Errorf logs an error message, patterned after log.Printf.
	Errorf(format string, args ...interface{})
	// Error logs an error message, patterned after log.Print.
	Error(args ...interface{})
	// Debugf logs a debug message, patterned after log.Printf.
	Debugf(format string, args ...interface{})
	// Debug logs a debug message, patterned after log.Print.
	Debug(args ...interface{})
	// Warnf logs a warning message, patterned after log.Printf.
	Warnf(format string, args ...interface{})
	// Warn logs a warning message, patterned after log.Print.
	Warn(args ...interface{})
	// Infof logs an information message, patterned after log.Printf.
	Infof(format string, args ...interface{})
	// Info logs an information message, patterned after log.Print.
	Info(args ...interface{})
}

Logger defines an interface for logging.

type Metric added in v1.17.3 

type Metric interface {
	// Name is the primary identifier for the Metric and corresponds to the
	// measurement in the InfluxDB data model.
	Name() string

	// Tags returns the tags as a map.  This method is deprecated, use TagList instead.
	Tags() map[string]string

	// TagList returns the tags as a slice ordered by the tag key in lexical
	// bytewise ascending order.  The returned value should not be modified,
	// use the AddTag or RemoveTag methods instead.
	TagList() []*Tag

	// Fields returns the fields as a map.  This method is deprecated, use FieldList instead.
	Fields() map[string]interface{}

	// FieldList returns the fields as a slice in an undefined order.  The
	// returned value should not be modified, use the AddField or RemoveField
	// methods instead.
	FieldList() []*Field

	// Time returns the timestamp of the metric.
	Time() time.Time

	// Type returns a general type for the entire metric that describes how you
	// might interpret, aggregate the values.
	//
	// This method may be removed in the future and its use is discouraged.
	Type() ValueType

	// SetName sets the metric name.
	SetName(name string)

	// AddPrefix adds a string to the front of the metric name.  It is
	// equivalent to m.SetName(prefix + m.Name()).
	//
	// This method is deprecated, use SetName instead.
	AddPrefix(prefix string)

	// AddSuffix appends a string to the back of the metric name.  It is
	// equivalent to m.SetName(m.Name() + suffix).
	//
	// This method is deprecated, use SetName instead.
	AddSuffix(suffix string)

	// GetTag returns the value of a tag and a boolean to indicate if it was set.
	GetTag(key string) (string, bool)

	// HasTag returns true if the tag is set on the Metric.
	HasTag(key string) bool

	// AddTag sets the tag on the Metric.  If the Metric already has the tag
	// set then the current value is replaced.
	AddTag(key, value string)

	// RemoveTag removes the tag if it is set.
	RemoveTag(key string)

	// GetField returns the value of a field and a boolean to indicate if it was set.
	GetField(key string) (interface{}, bool)

	// HasField returns true if the field is set on the Metric.
	HasField(key string) bool

	// AddField sets the field on the Metric.  If the Metric already has the field
	// set then the current value is replaced.
	AddField(key string, value interface{})

	// RemoveField removes the tag if it is set.
	RemoveField(key string)

	// SetTime sets the timestamp of the Metric.
	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()

	// SetAggregate indicates the metric is an aggregated value.
	//
	// This method may be removed in the future and its use is discouraged.
	SetAggregate(bool)

	// IsAggregate returns true if the Metric is an aggregate.
	//
	// This method may be removed in the future and its use is discouraged.
	IsAggregate() bool
}

Metric is the type of data that is processed by Telegraf. Input plugins, and to a lesser degree, Processor and Aggregator plugins create new Metrics and Output plugins write them.

type Output added in v1.17.3 

type Output interface {
	PluginDescriber

	// Connect to the Output; connect is only called once when the plugin starts
	Connect() error
	// Close any connections to the Output. Close is called once when the output
	// is shutting down. Close will not be called until all writes have finished,
	// and Write() will not be called once Close() has been, so locking is not
	// necessary.
	Close() error
	// Write takes in group of points to be written to the Output
	Write(metrics []Metric) error
}

type PluginDescriber added in v1.17.3 

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

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

PluginDescriber contains the functions all plugins must implement to describe themselves to Telegraf. Note that all plugins may define a logger that is not part of the interface, but will receive an injected logger if it's set. eg: Log telegraf.Logger `toml:"-"`

type Processor added in v1.17.3 

type Processor interface {
	PluginDescriber

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

Processor is a processor plugin interface for defining new inline processors. these are extremely efficient and should be used over StreamingProcessor if you do not need asynchronous metric writes.

type ServiceInput added in v1.17.3 

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.
	// Metrics should not be written out to the accumulator once stop returns, so
	// Stop() should stop reading and wait for any in-flight metrics to write out
	// to the accumulator before returning.
	Stop()
}

type StreamingProcessor added in v1.17.3 

type StreamingProcessor interface {
	PluginDescriber

	// Start is called once when the plugin starts; it is only called once per
	// plugin instance, and never in parallel.
	// Start should return once it is ready to receive metrics.
	// The passed in accumulator is the same as the one passed to Add(), so you
	// can choose to save it in the plugin, or use the one received from Add().
	Start(acc Accumulator) error

	// Add is called for each metric to be processed. The Add() function does not
	// need to wait for the metric to be processed before returning, and it may
	// be acceptable to let background goroutine(s) handle the processing if you
	// have slow processing you need to do in parallel.
	// Keep in mind Add() should not spawn unbounded goroutines, so you may need
	// to use a semaphore or pool of workers (eg: reverse_dns plugin does this)
	// Metrics you don't want to pass downstream should have metric.Drop() called,
	// rather than simply omitting the acc.AddMetric() call
	Add(metric Metric, acc Accumulator) error

	// Stop gives you an opportunity to gracefully shut down the processor.
	// Once Stop() is called, Add() will not be called any more. If you are using
	// goroutines, you should wait for any in-progress metrics to be processed
	// before returning from Stop().
	// When stop returns, you should no longer be writing metrics to the
	// accumulator.
	Stop() error
}

StreamingProcessor is a processor that can take in a stream of messages

type Tag added in v1.17.3 

type Tag struct {
	Key   string
	Value string
}

Tag represents a single tag key and value.

type TrackingAccumulator added in v1.17.3 

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 added in v1.17.3 

type TrackingID uint64

TrackingID uniquely identifies a tracked metric group

type ValueType added in v1.17.3 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
telegraf
aws
choice
Package choice provides basic functions for working with plugin options that must be one of several values.
 Package choice provides basic functions for working with plugin options that must be one of several values.
docker
globpath
goplugin
limiter
process
rotate
snmp
syslog
templating
plugins
aggregators
aggregators/all
aggregators/basicstats
aggregators/final
aggregators/histogram
aggregators/merge
aggregators/minmax
aggregators/valuecounter
common/encoding
common/kafka
common/logrus
common/proxy
common/shim
common/shim/example/cmd
common/tls
inputs
inputs/activemq
inputs/aerospike
inputs/all
inputs/amqp_consumer
inputs/apache
inputs/apcupsd
inputs/aurora
inputs/azure_storage_queue
inputs/bcache
inputs/beanstalkd
inputs/bind
inputs/bond
inputs/burrow
inputs/cassandra
inputs/ceph
inputs/cgroup
inputs/chrony
inputs/cisco_telemetry_mdt
inputs/clickhouse
inputs/cloud_pubsub
inputs/cloud_pubsub_push
inputs/cloudwatch
inputs/conntrack
inputs/consul
inputs/couchbase
inputs/couchdb
inputs/cpu
inputs/dcos
inputs/disk
inputs/diskio
inputs/disque
inputs/dmcache
inputs/dns_query
inputs/docker
Helper functions copied from https://github.com/docker/cli/blob/master/cli/command/container/stats_helpers.go
 Helper functions copied from https://github.com/docker/cli/blob/master/cli/command/container/stats_helpers.go
inputs/docker_log
inputs/dovecot
inputs/ecs
inputs/elasticsearch
inputs/ethtool
inputs/eventhub_consumer
inputs/exec
inputs/execd
inputs/execd/examples
inputs/execd/shim
inputs/execd/shim/example/cmd
inputs/fail2ban
inputs/fibaro
inputs/file
inputs/filecount
inputs/filestat
inputs/fireboard
inputs/fluentd
inputs/github
inputs/gnmi
inputs/graylog
inputs/haproxy
inputs/hddtemp
inputs/hddtemp/go-hddtemp
inputs/http
inputs/http_listener_v2
inputs/http_response
inputs/httpjson
inputs/icinga2
inputs/infiniband
inputs/influxdb
inputs/influxdb_listener
inputs/influxdb_v2_listener
inputs/intel_powerstat
inputs/intel_rdt
inputs/internal
inputs/interrupts
inputs/ipmi_sensor
inputs/ipset
inputs/iptables
inputs/ipvs
inputs/jenkins
inputs/jolokia
inputs/jolokia2
inputs/jti_openconfig_telemetry
inputs/jti_openconfig_telemetry/auth
Package authentication is a generated protocol buffer package.
 Package authentication is a generated protocol buffer package.
inputs/jti_openconfig_telemetry/oc
Package telemetry is a generated protocol buffer package.
 Package telemetry is a generated protocol buffer package.
inputs/kafka_consumer
inputs/kafka_consumer_legacy
inputs/kapacitor
inputs/kernel
inputs/kernel_vmstat
inputs/kibana
inputs/kinesis_consumer
inputs/kube_inventory
inputs/kubernetes
inputs/lanz
inputs/leofs
inputs/linux_sysctl_fs
inputs/logparser
inputs/logstash
inputs/lustre2
Lustre 2.x Telegraf plugin Lustre (http://lustre.org/) is an open-source, parallel file system for HPC environments.
 Lustre 2.x Telegraf plugin Lustre (http://lustre.org/) is an open-source, parallel file system for HPC environments.
inputs/mailchimp
inputs/marklogic
inputs/mcrouter
inputs/mem
inputs/memcached
inputs/mesos
inputs/minecraft
inputs/minecraft/internal/rcon
Package rcon implements the communication protocol for communicating with RCON servers.
 Package rcon implements the communication protocol for communicating with RCON servers.
inputs/modbus
inputs/mongodb
inputs/monit
inputs/mqtt_consumer
inputs/multifile
inputs/mysql
inputs/mysql/v1
inputs/mysql/v2
inputs/nats
inputs/nats_consumer
inputs/neptune_apex
Package neptuneapex implements an input plugin for the Neptune Apex aquarium controller.
 Package neptuneapex implements an input plugin for the Neptune Apex aquarium controller.
inputs/net
inputs/net_response
inputs/nginx
inputs/nginx_plus
inputs/nginx_plus_api
inputs/nginx_sts
inputs/nginx_upstream_check
inputs/nginx_vts
inputs/nsd
inputs/nsq
inputs/nsq_consumer
inputs/nstat
inputs/ntpq
inputs/nvidia_smi
inputs/opcua
inputs/openldap
inputs/openntpd
inputs/opensmtpd
inputs/openweathermap
inputs/passenger
inputs/pf
inputs/pgbouncer
inputs/phpfpm
Package fcgi implements the FastCGI protocol.
 Package fcgi implements the FastCGI protocol.
inputs/ping
inputs/postfix
inputs/postgresql
inputs/postgresql_extensible
inputs/powerdns
inputs/powerdns_recursor
inputs/processes
inputs/procstat
inputs/prometheus
inputs/proxmox
inputs/puppetagent
inputs/rabbitmq
inputs/raindrops
inputs/ras
inputs/redfish
inputs/redis
inputs/rethinkdb
inputs/riak
inputs/riemann_listener
inputs/salesforce
inputs/sensors
inputs/sflow
inputs/sflow/binaryio
inputs/smart
inputs/snmp
inputs/snmp_legacy
inputs/snmp_trap
inputs/socket_listener
inputs/solr
inputs/sqlserver
inputs/stackdriver
inputs/statsd
inputs/suricata
inputs/swap
inputs/synproxy
inputs/syslog
inputs/sysstat
inputs/system
inputs/systemd_units
inputs/tail
inputs/tcp_listener
inputs/teamspeak
inputs/temp
inputs/tengine
inputs/tomcat
inputs/trig
inputs/twemproxy
inputs/udp_listener
inputs/unbound
inputs/uwsgi
Package uwsgi implements a telegraf plugin for collecting uwsgi stats from the uwsgi stats server.
 Package uwsgi implements a telegraf plugin for collecting uwsgi stats from the uwsgi stats server.
inputs/varnish
inputs/vsphere
inputs/webhooks
inputs/webhooks/filestack
inputs/webhooks/github
inputs/webhooks/mandrill
inputs/webhooks/papertrail
inputs/webhooks/particle
inputs/webhooks/rollbar
inputs/win_eventlog
Package win_eventlog Input plugin to collect Windows Event Log messages
 Package win_eventlog Input plugin to collect Windows Event Log messages
inputs/win_perf_counters
inputs/win_services
inputs/wireguard
inputs/wireless
inputs/x509_cert
Package x509_cert reports metrics from an SSL certificate.
 Package x509_cert reports metrics from an SSL certificate.
inputs/zfs
inputs/zipkin
inputs/zipkin/cmd/stress_test_write
inputs/zipkin/cmd/thrift_serialize
A small cli utility meant to convert json to zipkin thrift binary format, and vice versa.
 A small cli utility meant to convert json to zipkin thrift binary format, and vice versa.
inputs/zipkin/codec
inputs/zipkin/codec/jsonV1
inputs/zipkin/codec/thrift
inputs/zipkin/trace
inputs/zookeeper
outputs
outputs/all
outputs/amon
outputs/amqp
outputs/application_insights
outputs/application_insights/mocks
Code generated by mockery v1.0.0 Code generated by mockery v1.0.0
 Code generated by mockery v1.0.0 Code generated by mockery v1.0.0
outputs/azure_monitor
outputs/cloud_pubsub
outputs/cloudwatch
outputs/cratedb
outputs/datadog
outputs/discard
outputs/dynatrace
outputs/elasticsearch
outputs/exec
outputs/execd
outputs/file
outputs/graphite
outputs/graylog
outputs/health
outputs/http
outputs/influxdb
outputs/influxdb_v2
outputs/instrumental
outputs/kafka
outputs/kinesis
outputs/librato
outputs/logzio
outputs/mqtt
outputs/nats
outputs/newrelic
outputs/nsq
outputs/opentsdb
outputs/prometheus_client
outputs/prometheus_client/v1
outputs/prometheus_client/v2
outputs/riemann
outputs/riemann_legacy
outputs/socket_writer
outputs/stackdriver
outputs/sumologic
outputs/syslog
outputs/timestream
outputs/warp10
outputs/wavefront
outputs/yandex_cloud_monitoring
parsers
parsers/collectd
parsers/csv
parsers/dropwizard
parsers/form_urlencoded
parsers/graphite
parsers/grok
parsers/influx
parsers/json
parsers/logfmt
parsers/nagios
parsers/prometheus
parsers/prometheus/common
parsers/value
parsers/wavefront
processors
processors/all
processors/clone
processors/converter
processors/date
processors/dedup
processors/defaults
processors/enum
processors/execd
processors/filepath
processors/ifname
processors/override
processors/parser
processors/pivot
processors/port_name
processors/printer
processors/regex
processors/rename
processors/reverse_dns
processors/reverse_dns/parallel
processors/s2geo
processors/starlark
processors/strings
processors/tag_limit
processors/template
processors/topk
processors/unpivot
serializers
serializers/carbon2
serializers/graphite
serializers/influx
serializers/json
serializers/nowmetric
serializers/prometheus
serializers/prometheusremotewrite
serializers/splunkmetric
serializers/wavefront
selfstat is a package for tracking and collecting internal statistics about telegraf.
 selfstat is a package for tracking and collecting internal statistics about telegraf.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.