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.15.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).