README
¶
collectd plugins in Go
About
This is experimental code to write collectd plugins in Go. It requires Go 1.5 or later and a recent version of the collectd sources to build.
Build
To set up your build environment, set the CGO_CPPFLAGS environment variable
so that cgo can find the required header files:
export COLLECTD_SRC="/path/to/collectd"
export CGO_CPPFLAGS="-I${COLLECTD_SRC}/src/daemon -I${COLLECTD_SRC}/src"
You can then compile your Go plugins with:
go build -buildmode=c-shared -o example.so
More information is available in the documentation of the collectd.org/plugin
package.
godoc collectd.org/plugin
Future
Only read and write callbacks are currently supported. Based on these
implementations it should be fairly straightforward to implement the remaining
callbacks. The init, shutdown, log, flush and missing callbacks are
all likely low-hanging fruit. The notification callback is a bit trickier
because it requires implementing notifications in the collectd.org/api package
and the (un)marshaling of notification_t. The (complex) config callback is
arguably the most important but, unfortunately, also the most complex to
implemented.
If you're willing to give any of this a shot, please ping @octo to avoid duplicate work.
Documentation
¶
Overview ¶
Package plugin exports the functions required to write collectd plugins in Go.
This package provides the abstraction necessary to write plugins for collectd in Go, compile them into a shared object and let the daemon load and use them.
Example plugin ¶
To understand how this module is being used, please consider the following example:
package main
import (
"time"
"collectd.org/api"
"collectd.org/plugin"
)
type ExamplePlugin struct{}
func (*ExamplePlugin) Read() error {
vl := &api.ValueList{
Identifier: api.Identifier{
Host: "example.com",
Plugin: "goplug",
Type: "gauge",
},
Time: time.Now(),
Interval: 10 * time.Second,
Values: []api.Value{api.Gauge(42)},
DSNames: []string{"value"},
}
if err := plugin.Write(context.Background(), vl); err != nil {
return err
}
return nil
}
func init() {
plugin.RegisterRead("example", &ExamplePlugin{})
}
func main() {} // ignored
The first step when writing a new plugin with this package, is to create a new "main" package. Even though it has to have a main() function to make cgo happy, the main() function is ignored. Instead, put your startup code into the init() function which essentially takes on the same role as the module_register() function in C based plugins.
Then, define a type which implements the Reader interface by implementing the "Read() error" function. In the example above, this type is called ExamplePlugin. Create an instance of this type and pass it to RegisterRead() in the init() function.
Build flags ¶
To compile your plugin, set up the CGO_CPPFLAGS environment variable and call "go build" with the following options:
export COLLECTD_SRC="/path/to/collectd"
export CGO_CPPFLAGS="-I${COLLECTD_SRC}/src/daemon -I${COLLECTD_SRC}/src"
go build -buildmode=c-shared -o example.so
Index ¶
- func Debug(v ...interface{}) error
- func Debugf(format string, v ...interface{}) error
- func Error(v ...interface{}) error
- func Errorf(format string, v ...interface{}) error
- func Info(v ...interface{}) error
- func Infof(format string, v ...interface{}) error
- func NewWriter() api.Writer
- func Notice(v ...interface{}) error
- func Noticef(format string, v ...interface{}) error
- func RegisterRead(name string, r Reader) error
- func RegisterWrite(name string, w api.Writer) error
- func Warning(v ...interface{}) error
- func Warningf(format string, v ...interface{}) error
- func Write(vl *api.ValueList) error
- type Reader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Debug ¶
func Debug(v ...interface{}) error
Debug logs a debugging message using plugin_log(). Arguments are handled in the manner of fmt.Print.
func Debugf ¶
Debugf logs a debugging message using plugin_log(). Arguments are handled in the manner of fmt.Printf.
func Error ¶
func Error(v ...interface{}) error
Error logs an error using plugin_log(). Arguments are handled in the manner of fmt.Print.
func Errorf ¶
Errorf logs an error using plugin_log(). Arguments are handled in the manner of fmt.Printf.
func Info ¶
func Info(v ...interface{}) error
Info logs a purely informal message using plugin_log(). Arguments are handled in the manner of fmt.Print.
func Infof ¶
Infof logs a purely informal message using plugin_log(). Arguments are handled in the manner of fmt.Printf.
func NewWriter ¶
NewWriter returns an object implementing the api.Writer interface for the collectd daemon.
func Notice ¶
func Notice(v ...interface{}) error
Notice logs a notice using plugin_log(). Arguments are handled in the manner of fmt.Print.
func Noticef ¶
Noticef logs a notice using plugin_log(). Arguments are handled in the manner of fmt.Printf.
func RegisterRead ¶
RegisterRead registers a new read function with the daemon which is called periodically.
func RegisterWrite ¶
RegisterWrite registers a new write function with the daemon which is called for every metric collected by collectd.
Please note that multiple threads may call this function concurrently. If you're accessing shared resources, such as a memory buffer, you have to implement appropriate locking around these accesses.
func Warning ¶
func Warning(v ...interface{}) error
Warning logs a warning using plugin_log(). Arguments are handled in the manner of fmt.Print.
Source Files