Crate collectd_plugin

Collectd is a ubiquitous system statistics collection daemon. collectd_plugin leverages Collectd’s ability to dynamically load plugins and creates an ergonomic, yet extremely low cost abstraction API to interface with Collectd.

Features:

• No unnecessary allocations when submitting / receiving values, logging
• Register multiple plugin instances
• Automatic deserialization of plugin configs via Serde (can opt-out)
• Deployment: compile against collectd version and scp to server
• Referenced Rust libraries are statically linked
• Help writing thread safe plugins thanks to the Rust compiler

Usage

Add to your Cargo.toml:

[dependencies]
collectd-plugin = "0.14.0"

Rust 1.33 or later is needed to build.

Works with any collectd version 5.4+, but all users will need to specify the collectd api version they want to target via the COLLECTD_VERSION environment variable (or rely on $(collectd -h) or COLLECTD_PATH variable).

COLLECTED_VERSION	Compatible Range
5.4	[5.4, 5.5)
5.5	[5.5, 5.7)
5.7	[5.7,)

Quickstart

Below is a complete plugin that dummy reports load values to collectd, as it registers a READ hook. For an implementation that reimplements Collectd’s own load plugin, see plugins/load

use collectd_plugin::{
    ConfigItem, Plugin, PluginCapabilities, PluginManager, PluginRegistration, Value,
    ValueListBuilder, collectd_plugin
};
use std::error;

#[derive(Default)]
struct MyPlugin;

// A manager decides the name of the family of plugins and also registers one or more plugins based
// on collectd's configuration files
impl PluginManager for MyPlugin {
    // A plugin needs a unique name to be referenced by collectd
    fn name() -> &'static str {
        "myplugin"
    }

    // Our plugin might have configuration section in collectd.conf, which will be passed here if
    // present. Our contrived plugin doesn't care about configuration so it returns only a single
    // plugin (itself).
    fn plugins(_config: Option<&[ConfigItem]>) -> Result<PluginRegistration, Box<error::Error>> {
        Ok(PluginRegistration::Single(Box::new(MyPlugin)))
    }
}

impl Plugin for MyPlugin {
    // We define that our plugin will only be reporting / submitting values to writers
    fn capabilities(&self) -> PluginCapabilities {
        PluginCapabilities::READ
    }

    fn read_values(&self) -> Result<(), Box<error::Error>> {
        // Create a list of values to submit to collectd. We'll be sending in a vector representing the
        // "load" type. Short-term load is first (15.0) followed by mid-term and long-term. The number
        // of values that you submit at a time depends on types.db in collectd configurations
        let values = vec![Value::Gauge(15.0), Value::Gauge(10.0), Value::Gauge(12.0)];

        // Submit our values to collectd. A plugin can submit any number of times.
        ValueListBuilder::new(Self::name(), "load")
            .values(&values)
            .submit()?;

        Ok(())
    }
}

// We pass in our plugin manager type
collectd_plugin!(MyPlugin);

Modules

bindings
de
internal	Module used exclusively to setup the collectd_plugin! macro. No public functions from here should be used.
ser

Macros

collectd_log_raw	A simple wrapper around the collectd’s plugin_log, which in turn wraps vsnprintf.
collectd_plugin	Sets up all the ffi entry points that collectd expects when given a PluginManager.

Structs

CacheRateError	Errors that occur when retrieving rates
CdTime	CdTime allows for ergonomic interop between collectd’s cdtime_t and chrono’s Duration and DateTime. The single field represents epoch nanoseconds.
CollectdLoggerBuilder	Bridges the gap between collectd and rust logging. Terminology and filters methods found here are from env_logger.
ConfigItem	Parsed key, values, children objects from the Collectd config.
PluginCapabilities	Bitflags of capabilities that a plugin advertises to collectd.
PluginManagerCapabilities	Bitflags of capabilities that a plugin manager advertises to collectd
ValueList	Contains values and metadata that collectd has collected from plugins
ValueListBuilder	Creates a value list to report values to collectd.
ValueReport	Name and value of a reported metric

Enums

ConfigError	Error that occurred while translating the collectd config to rust structures.
ConfigValue	A parsed value from the Collectd config
LogLevel	The available levels that collectd exposes to log messages.
MetaValue	The value of a metadata entry associated with a ValueList. Metadata can be added using ValueListBuilder::metadata method.
PluginRegistration	How many instances of the plugin will be registered
ReceiveError	Error that occurred while receiving values from collectd to write
SubmitError	Errors that occur when submitting values to collectd
Value	The value that a plugin reports can be any one of the following types

Traits

Plugin	An individual plugin that is capable of reporting values to collectd, receiving values from other plugins, or logging messages. A plugin must implement Sync + Send as collectd could be sending values to be written or logged concurrently. The Rust compiler will ensure that everything not thread safe is wrapped in a Mutex (or another compatible datastructure)
PluginManager	Defines the entry point for a collectd plugin. Based on collectd’s configuration, a PluginManager will register any number of plugins (or return an error)

Functions

collectd_log

Sends message and log level to collectd. This bypasses any configuration setup via CollectdLoggerBuilder, so collectd configuration soley determines if a level is logged and where it is delivered. Messages that are too long are truncated (1024 was the max length as of collectd-5.7).