Crate collectd_plugin
source ·Expand description
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.9.0"
Serde support is enabled by default for configuration parsing.
Then put this in your crate root:
ⓘ
extern crate collectd_plugin;
Rust 1.20 or later is needed to build.
This repo is tested on the following:
- Collectd 5.4 (Ubuntu 14.04)
- Collectd 5.5 (Ubuntu 16.04)
- Collectd 5.7 (and above) (Ubuntu 18.04)
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
#[macro_use]
extern crate collectd_plugin;
use collectd_plugin::{
ConfigItem, Plugin, PluginCapabilities, PluginManager, PluginRegistration, Value,
ValueListBuilder,
};
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
Module used exclusively to setup the
collectd_plugin!
macro. No public functions from here
should be used.Macros
A simple wrapper around the collectd’s plugin_log, which in turn wraps
vsnprintf
.Sets up all the ffi entry points that collectd expects when given a
PluginManager
.Structs
CdTime
allows for ergonomic interop between collectd’s cdtime_t
and chrono’s Duration
and
DateTime
. The single field represents epoch nanoseconds.Bridges the gap between collectd and rust logging. Terminology and filters methods found here
are from env_logger.
Parsed key, values, children objects from the Collectd config.
Bitflags of capabilities that a plugin advertises to collectd.
Bitflags of capabilities that a plugin manager advertises to collectd
Contains values and metadata that collectd has collected from plugins
Creates a value list to report values to collectd.
Name and value of a reported metric
Enums
A parsed value from the Collectd config
The available levels that collectd exposes to log messages.
How many instances of the plugin will be registered
The value that a plugin reports can be any one of the following types
Traits
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)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
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).