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 ( "context" "fmt" "time" "collectd.org/api" "collectd.org/plugin" ) type examplePlugin struct{} func (examplePlugin) Read(ctx context.Context) 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(ctx, vl); err != nil { return fmt.Errorf("plugin.Write: %w", 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 Interval() (time.Duration, error)
- func Name(ctx context.Context) (string, bool)
- func Notice(v ...interface{}) error
- func Noticef(format string, v ...interface{}) error
- func RegisterLog(name string, l Logger) error
- func RegisterRead(name string, r Reader, opts ...ReadOption) error
- func RegisterShutdown(name string, s Shutter) error
- func RegisterWrite(name string, w api.Writer) error
- func Timeout() (time.Duration, error)
- func Warning(v ...interface{}) error
- func Warningf(format string, v ...interface{}) error
- func Write(ctx context.Context, vl *api.ValueList) error
- type Logger
- type ReadOption
- type Reader
- type Severity
- type Shutter
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 Interval ¶ added in v0.4.0
Interval returns the interval in which read callbacks are being called. May only be called from within a read callback.
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 RegisterLog ¶ added in v0.4.0
RegisterLog registers a logging function with the daemon which is called whenever a log message is generated.
func RegisterRead ¶
func RegisterRead(name string, r Reader, opts ...ReadOption) error
RegisterRead registers a new read function with the daemon which is called periodically.
func RegisterShutdown ¶ added in v0.4.0
RegisterShutdown registers a shutdown function with the daemon which is called when the plugin is required to shutdown gracefully.
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 Timeout ¶ added in v0.4.0
Timeout returns the duration after which this plugin's metrics are considered stale and are pruned from collectd's internal metrics cache.
func Warning ¶
func Warning(v ...interface{}) error
Warning logs a warning using plugin_log(). Arguments are handled in the manner of fmt.Print.
func Warningf ¶
Warningf logs a warning using plugin_log(). Arguments are handled in the manner of fmt.Printf.
func Write ¶
Write converts a ValueList and calls the plugin_dispatch_values() function of the collectd daemon.
The following fields are optional and will be filled in if empty / zero:
· vl.Identifier.Host
· vl.Identifier.Plugin
· vl.Time
· vl.Interval
Use api.WriterFunc to pass this function as an api.Writer.
Types ¶
type ReadOption ¶ added in v0.4.0
type ReadOption func(o *readOpt)
ReadOption is an option for the RegisterRead function.
func WithGroup ¶ added in v0.4.0
func WithGroup(g string) ReadOption
WithGroup sets the group name of the read callback. If unspecified, "golang" is used. Set to the empty string to clear the group name.
func WithInterval ¶ added in v0.4.0
func WithInterval(d time.Duration) ReadOption
WithInterval sets the interval in which the read callback is being called. If unspecified, or when set to zero, collectd's global default is used.
The vast majority of plugins SHOULD NOT set this option explicitly and respect the user's configuration by using the default instead.
type Reader ¶
Reader defines the interface for read callbacks, i.e. Go functions that are called periodically from the collectd daemon. The context passed to the Read() function has a timeout based on collectd's "Timeout" global config option. It defaults to twice the plugin's read interval.