shim

README

Telegraf Execd Go Shim

The goal of this shim is to make it trivial to extract an internal input, processor, or output plugin from the main Telegraf repo out to a stand-alone repo. This allows anyone to build and run it as a separate app using one of the execd plugins:

• inputs.execd
• processors.execd
• outputs.execd

Steps to externalize a plugin

1. Move the project to an external repo, it's recommended to preserve the path structure, (but not strictly necessary). eg if your plugin was at plugins/inputs/cpu, it's recommended that it also be under plugins/inputs/cpu in the new repo. For a further example of what this might look like, take a look at ssoroka/rand or danielnelson/telegraf-plugins
2. Copy main.go into your project under the cmd folder. This will be the entrypoint to the plugin when run as a stand-alone program, and it will call the shim code for you to make that happen. It's recommended to have only one plugin per repo, as the shim is not designed to run multiple plugins at the same time (it would vastly complicate things).
3. Edit the main.go file to import your plugin. Within Telegraf this would have been done in an all.go file, but here we don't split the two apart, and the change just goes in the top of main.go. If you skip this step, your plugin will do nothing. eg: _ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"
4. Optionally add a plugin.conf for configuration specific to your plugin. Note that this config file must be separate from the rest of the config for Telegraf, and must not be in a shared directory where Telegraf is expecting to load all configs. If Telegraf reads this config file it will not know which plugin it relates to. Telegraf instead uses an execd config block to look for this plugin.

Steps to build and run your plugin

1. Build the cmd/main.go. For my rand project this looks like go build -o rand cmd/main.go
2. If you're building an input, you can test out the binary just by running it. eg ./rand -config plugin.conf Depending on your polling settings and whether you implemented a service plugin or an input gathering plugin, you may see data right away, or you may have to hit enter first, or wait for your poll duration to elapse, but the metrics will be written to STDOUT. Ctrl-C to end your test. If you're testig a processor or output manually, you can still do this but you will need to feed valid metrics in on STDIN to verify that it is doing what you want. This can be a very valuable debugging technique before hooking it up to Telegraf.
3. Configure Telegraf to call your new plugin binary. For an input, this would look something like:

[[inputs.execd]]
  command = ["/path/to/rand", "-config", "/path/to/plugin.conf"]
  signal = "none"

Refer to the execd plugin readmes for more information.

Congratulations!

You've done it! Consider publishing your plugin to github and open a Pull Request back to the Telegraf repo letting us know about the availability of your external plugin.

Documentation

Index

• Constants
• func DefaultImportedPlugins() (config, error)
• func LoadConfig(filePath *string) (loaded loadedConfig, err error)
• type Logger
  • func NewLogger() *Logger
  • func (l *Logger) Debug(args ...interface{})
  • func (l *Logger) Debugf(format string, args ...interface{})
  • func (l *Logger) Error(args ...interface{})
  • func (l *Logger) Errorf(format string, args ...interface{})
  • func (l *Logger) Info(args ...interface{})
  • func (l *Logger) Infof(format string, args ...interface{})
  • func (l *Logger) Warn(args ...interface{})
  • func (l *Logger) Warnf(format string, args ...interface{})
• type Shim
  • func New() *Shim
  • func (s *Shim) AddInput(input telegraf.Input) error
  • func (s *Shim) AddOutput(output telegraf.Output) error
  • func (s *Shim) AddProcessor(processor telegraf.Processor) error
  • func (s *Shim) AddStreamingProcessor(processor telegraf.StreamingProcessor) error
  • func (s *Shim) LoadConfig(filePath *string) error
  • func (s *Shim) Log() telegraf.Logger
  • func (s *Shim) LogName() string
  • func (s *Shim) MakeMetric(m telegraf.Metric) telegraf.Metric
  • func (s *Shim) Run(pollInterval time.Duration) error
  • func (s *Shim) RunInput(pollInterval time.Duration) error
  • func (s *Shim) RunOutput() error
  • func (s *Shim) RunProcessor() error

Constants

const (
	// PollIntervalDisabled is used to indicate that you want to disable polling,
	// as opposed to duration 0 meaning poll constantly.
	PollIntervalDisabled = time.Duration(0)
)

Functions

func DefaultImportedPlugins

func DefaultImportedPlugins() (config, error)

DefaultImportedPlugins defaults to whatever plugins happen to be loaded and have registered themselves with the registry. This makes loading plugins without having to define a config dead easy.

func LoadConfig

func LoadConfig(filePath *string) (loaded loadedConfig, err error)

LoadConfig loads the config and returns inputs that later need to be loaded.

Types

type Logger

type Logger struct{}

Logger defines a logging structure for plugins. external plugins can only ever write to stderr and writing to stdout would interfere with input/processor writing out of metrics.

func NewLogger

func NewLogger() *Logger

NewLogger creates a new logger instance

func (*Logger) Debug

func (l *Logger) Debug(args ...interface{})

Debug logs a debug message, patterned after log.Print.

func (*Logger) Debugf

func (l *Logger) Debugf(format string, args ...interface{})

Debugf logs a debug message, patterned after log.Printf.

func (*Logger) Error

func (l *Logger) Error(args ...interface{})

Error logs an error message, patterned after log.Print.

func (*Logger) Errorf

func (l *Logger) Errorf(format string, args ...interface{})

Errorf logs an error message, patterned after log.Printf.

func (*Logger) Info

func (l *Logger) Info(args ...interface{})

Info logs an information message, patterned after log.Print.

func (*Logger) Infof

func (l *Logger) Infof(format string, args ...interface{})

Infof logs an information message, patterned after log.Printf.

func (*Logger) Warn

func (l *Logger) Warn(args ...interface{})

Warn logs a warning message, patterned after log.Print.

func (*Logger) Warnf

func (l *Logger) Warnf(format string, args ...interface{})

Warnf logs a warning message, patterned after log.Printf.

type Shim

type Shim struct {
	Input     telegraf.Input
	Processor telegraf.StreamingProcessor
	Output    telegraf.Output
	// contains filtered or unexported fields
}

Shim allows you to wrap your inputs and run them as if they were part of Telegraf, except built externally.

func New

func New() *Shim

New creates a new shim interface

func (*Shim) AddInput

func (s *Shim) AddInput(input telegraf.Input) error

AddInput adds the input to the shim. Later calls to Run() will run this input.

func (*Shim) AddOutput

func (s *Shim) AddOutput(output telegraf.Output) error

AddOutput adds the input to the shim. Later calls to Run() will run this.

func (*Shim) AddProcessor

func (s *Shim) AddProcessor(processor telegraf.Processor) error

AddProcessor adds the processor to the shim. Later calls to Run() will run this.

func (*Shim) AddStreamingProcessor

func (s *Shim) AddStreamingProcessor(processor telegraf.StreamingProcessor) error

AddStreamingProcessor adds the processor to the shim. Later calls to Run() will run this.

func (*Shim) LoadConfig

func (s *Shim) LoadConfig(filePath *string) error

LoadConfig Adds plugins to the shim

func (*Shim) Log

func (s *Shim) Log() telegraf.Logger

Log satisfies the MetricMaker interface

func (*Shim) LogName

func (s *Shim) LogName() string

LogName satisfies the MetricMaker interface

func (*Shim) MakeMetric

func (s *Shim) MakeMetric(m telegraf.Metric) telegraf.Metric

MakeMetric satisfies the MetricMaker interface

func (*Shim) Run

func (s *Shim) Run(pollInterval time.Duration) error

Run the input plugins..

func (*Shim) RunInput

func (s *Shim) RunInput(pollInterval time.Duration) error

func (*Shim) RunOutput

func (s *Shim) RunOutput() error

func (*Shim) RunProcessor

func (s *Shim) RunProcessor() error