Write your own telegraf plugin

Noah Crowley, Developer Advocate
Getting Started Series
Write your Own Telegraf
plugin

© 2017 InfluxData. All rights reserved.2 © 2017 InfluxData. All rights reserved.2
✓ Telegraf overview
✓ Examples of Telegraf plugins
✓ Telegraf plugin architecture
✓ How to a write a Telegraf plugin (demo)
What we will be covering

Telegraf Overview

© 2018 InfluxData. All rights reserved.4
InfluxData Open Source Projects: TELEGRAF!

InfluxData Open Source Projects: TELEGRAF!

Telegraf
Telegraf is an Open Source plugin-driven server agent for
collecting & reporting metrics: “Push” or “Pull”.
• Used to batch metrics from multiple sources together in order to reduce the number
of atomic write requests
• Large collection of Plugins:
– Inputs
– Outputs
– Aggregators
– Processors
• Can act as an:
– Agent
– Collector
– Ingest Pipeline

Telegraf continued
• Metrics ingestion from the host system (cpu, I/O, network)
– Common programs (Hadoop, Postgres, Redis, etc.)
– Third party APIs (Mailchimp, CloudWatch, Google Analytics, etc.)
• Output plugins to send metrics to a variety of other datastores,
services, and message queues, including
– InfluxDB, Graphite, OpenTSDB, Datadog, Librato, Kafka, MQTT,
NSQ, Prometheus, and many others
• Over 140 plugins!

Telegraf Benefits
• Although if we start using it then it’s kind of the de-facto tool
anyway…
• Minimal memory footprint
• Tagging of metrics
• Easy contribution of functionality
• Strong Community contributions

Examples of Telegraf plugins

Some Telegraf plugins
statsd
Listens for data in statsd format and
outputs it to any configured output
apache
Collects data from the
/server-status?auto endpoint and
stores it
postgresql
Collects performance metrics about
postgres; uses data from the built in
pg_stat_database and
pg_stat_bgwriter views
win_perf_counters
Collects performance data from
Windows machines

Some Telegraf plugins
prometheus_client
Exposes all metrics on /metrics to be
polled by a Prometheus server
nginx
Read Nginx's basic status
(ngx_http_stub_status_module)
histogram
Creates histograms containing the
counts of field values within a range
kubernetes
Experimental; Talks to the kubelet
api using the /stats/summary
endpoint

How do I install it?
Download binaries at influxdata.com/downloads then:
Telegraf normally runs as a Linux service
$ telegraf -sample-config -input-filter haproxy -output-filter influxdb >
telegraf.conf
$ telegraf -config telegraf.conf
$ telegraf -sample-config -input-filter haproxy -output-filter influxdb >
/etc/telegraf/telegraf.conf
$ service telegraf start

Telegraf plugin architecture

The Open Source Collector Agent: Telegraf

Input interface
The plugin must conform to the telegraf.Input interface:
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
}

Let’s write a plugin

What do you need?
• Go 1.8+ installed and configured on your computer (1.9+
recommended)
• A desire to write a Telegraf plugin
• What is our plugin going to do?
• It will emit a trigonometric pattern called `trig`

Getting Started
This will create a new Telegraf binary at $GOPATH/bin/telegraf
$ go get github.com/influxdata/telegraf
$ cd $GOPATH/github.com/influxdata/telegraf
$ git checkout -b mySweetPlugin
$ make

Make your files and add boilerplate
$ cd plugins/inputs
$ mkdir trig
$ touch trig/trig.go
# Add boilerplate
$ cat trig/trig.go

Boilerplate
$ cat trig/trig.go
package trig
import (
"github.com/influxdata/telegraf"
"github.com/influxdata/telegraf/plugins/inputs"
)
type Trig struct {
}
func (s *Trig) SampleConfig() string {
return ""
}
func (s *Trig) Description() string {
return ""
}
func (s *Trig) Gather(acc telegraf.Accumulator) error {
return nil
}
func init() {
inputs.Add("trig", func() telegraf.Input { return &Trig{} })
}

Import your plugin
In the file -> telegraf/plugins/inputs/all/all.go
Add:
This imports your plugin to the main telegraf package and ensures
that it can run
_ "github.com/influxdata/telegraf/plugins/inputs/trig"

Add properties to your struct
There must be a property on the struct to hold any configuration
variables
Any other variables should be unexported.
x will hold state of the plugin between collection intervals, being
updated each one.
type Trig struct {
x float64
Amplitude float64
}

Add any configuration variables you need
Telegraf dynamically constructs configuration files by aggregating
the configurations for all of it’s plugins. This allows you to easily
generate configuration files with only certain plugins enabled by
just passing a couple of CLI flags.
var TrigConfig = `
## Set the amplitude
amplitude = 10.0
`
func (s *Trig) SampleConfig() string {
return TrigConfig
}

Add a simple description of your plugin
This description is included above the plugin configuration and
should briefly describe what your plugin does
func (s *Trig) Description() string {
return "Inserts sine and cosine waves for demonstration purposes"
}

Test it!
$ make
$ telegraf -sample-config -input-filter trig -output-filter influxdb
-debug
…
#
# INPUTS:
#
# Inserts sine and cosine waves for demonstration purposes
[[inputs.trig]]
## Set the amplitude
amplitude = 10.0

The Gather (telegraf.Accumulator) Function
• The Gather function is the heart of the plugin and is run every
time telegraf collects metrics.
• This number is configurable via the [agent]interval=10s
configuration option in the top level config in telegraf.
• Plugins can also be written to collect at different intervals.
• The important function is the
telegraf.Accumulator.AddFields(measurement,
tags, fields). This defines a new point in influxdb with
the timestamp being the collection time.

Write your Gather function!
func (s *Trig) Gather(acc telegraf.Accumulator) error {
sinner := math.Sin((s.x*math.Pi)/5.0) * s.Amplitude
cosinner := math.Cos((s.x*math.Pi)/5.0) * s.Amplitude
fields := make(map[string]interface{})
fields["sine"] = sinner
fields["cosine"] = cosinner
tags := make(map[string]string)
s.x += 1.0
acc.AddFields("trig", fields, tags)
return nil
}

Add starting state
Starting state can be defined in the struct you pass to the
input.Add() function. For our example we need to initialize x
This function packages up the whole plugin (all the methods are
defined on the Trig{} struct) and gives it to the Telegraf agent.
The agent iterates through all of the plugins that are enabled every
collection and calls their gather
func init() {
inputs.Add("trig", func() telegraf.Input { return &Trig{x: 0.0} })
}

Compile and test your plugin
$ make
$ telegraf -sample-config -input-filter trig -output-filter influxdb >>
telegraf.conf.test
$ telegraf -config telegraf.conf.test -debug
2016/03/24 11:50:26 Starting Telegraf (version 1.3.0-223-gf543dbb)
2016/03/24 11:50:26 Loaded outputs: influxdb
2016/03/24 11:50:26 Loaded inputs: trig
2016/03/24 11:50:26 Tags enabled: host=XXXXXX.local
2016/03/24 11:50:26 Agent Config: Interval:10s, Debug:false, Quiet:false,
Hostname:"XXXXXX.local", Flush Interval:10s
2016/03/24 11:50:30 Gathered metrics, (10s interval), from 1 inputs in
237.28µs

Graph it with Chronograf!

Write some tests...
package trig
import (
"math"
"testing"
"github.com/influxdata/telegraf/testutil"
)
func TestTrig(t *testing.T) {
s := &Trig{
Amplitude: 10.0,
}
for i := 0.0; i < 10.0; i++ {
var acc testutil.Accumulator
sine := math.Sin((i*math.Pi)/5.0) * s.Amplitude
cosine := math.Cos((i*math.Pi)/5.0) * s.Amplitude
s.Gather(&acc)
fields := make(map[string]interface{})
fields["sine"] = sine
fields["cosine"] = cosine
acc.AssertContainsFields(t, "trig", fields)
}
}

How to submit a plugin
Must include:
• a README.md file,
• a LICENSE file,
• and a sample of the output/input format
https://github.com/influxdata/telegraf/pulls

noah@influxdata.com @noahcrowley

Write your own telegraf plugin

More Related Content

What's hot (20)

Similar to Write your own telegraf plugin (20)

More from InfluxData (20)

Recently uploaded (20)

Write your own telegraf plugin