Trait MuninPlugin

pub trait MuninPlugin {
    // Required methods
    fn config<W: Write>(&self, handle: &mut BufWriter<W>) -> Result<()>;
    fn acquire<W: Write>(
        &mut self,
        handle: &mut BufWriter<W>,
        config: &Config,
        epoch: u64,
    ) -> Result<()>;

    // Provided methods
    fn daemon(&mut self, config: &Config) -> Result<()> { ... }
    fn fetch<W: Write>(
        &mut self,
        handle: &mut BufWriter<W>,
        config: &Config,
    ) -> Result<()> { ... }
    fn check_autoconf(&self) -> bool { ... }
    fn autoconf(&self) { ... }
    fn simple_start(&mut self, name: String) -> Result<bool> { ... }
    fn start(&mut self, config: Config) -> Result<bool> { ... }
}

Defines a Munin Plugin and the needed functions

Required Methods

fn config<W: Write>(&self, handle: &mut BufWriter<W>) -> Result<()>

Write out a munin config, read the Developing plugins guide from munin for everything you can print out here.

Note that munin expects this to appear on stdout, so the plugin gives you a handle to write to, which is setup as a std::io::BufWriter to stdout. The std::io::BufWriter capacity defaults to 8192 bytes, but if you need more, its size can be set using Config::config_size. An example where this may be useful is a munin multigraph plugin that outputs config for many graphs.

Example

fn config<W: Write>(&self, handle: &mut BufWriter<W>) -> Result<()> {
    writeln!(handle, "graph_title Load average")?;
    writeln!(handle, "graph_args --base 1000 -l 0")?;
    writeln!(handle, "graph_vlabel load")?;
    writeln!(handle, "graph_scale no")?;
    writeln!(handle, "graph_category system")?;
    writeln!(handle, "load.label load")?;
    writeln!(handle, "load.warning 10")?;
    writeln!(handle, "load.critical 120")?;
    writeln!(handle, "graph_info The load average of the machine describes how many processes are in the run-queue (scheduled to run immediately.")?;
    writeln!(handle, "load.info Average load for the five minutes.")?;
    Ok(())
}

fn acquire<W: Write>( &mut self, handle: &mut BufWriter<W>, config: &Config, epoch: u64, ) -> Result<()>

Acquire data

Acquire is called whenever data should be gathered. For a standard plugin this will be every 5 minutes, a streaming plugin will call acquire once a second. Acquire is expected to do whatever is neccessary to gather the data that the plugin is supposed to gather. It should writeln!() it to the provided handle, which - depending on the plugin type - will either be connected to stdout or a cachefile. The data written out has to be in munin compatible format:

• standard plugin: fieldname.value VALUE
• streaming plugin: fieldname.value EPOCH:VALUE where fieldname matches the config output, EPOCH is the unix epoch in seconds and VALUE is whatever value got calculated.

Example 1, standard plugin

fn acquire<W: Write>(&mut self, handle: &mut BufWriter<W>, config: &Config, epoch: u64) -> Result<()> {
    let load = (LoadAverage::new().unwrap().five * 100.0) as isize;
    writeln!(handle, "load.value {}", load)?;
    Ok(())
}

Example 2, streaming plugin

fn acquire<W: Write>(&mut self, handle: &mut BufWriter<W>, config: &Config, epoch: u64) -> Result<()> {
    // Read in the received and transferred bytes, store as u64
    let rx: u64 = std::fs::read_to_string(&self.if_rxbytes)?.trim().parse()?;
    let tx: u64 = std::fs::read_to_string(&self.if_txbytes)?.trim().parse()?;

    // And now write out values
    writeln!(handle, "{0}_tx.value {1}:{2}", self.interface, epoch, tx)?;
    writeln!(handle, "{0}_rx.value {1}:{2}", self.interface, epoch, rx)?;

    Ok(())
}

Provided Methods

fn daemon(&mut self, config: &Config) -> Result<()>

Daemonize

This function is called whenever the plugin gets run with the acquire argument. That usually happens on fetch and acquire gets run in the background. daemon() will lock its pidfile, to show it is running, start a loop, run once a second, calling MuninPlugin::acquire.

fn fetch<W: Write>( &mut self, handle: &mut BufWriter<W>, config: &Config, ) -> Result<()>

Fetch delivers actual data to munin. This is called whenever the plugin is called without an argument. If the config::Config::dirtyconfig setting is true (auto-detected from environment set by munin), this will also be called right after having called MuninPlugin::config.

The size of the BufWriter this function uses is configurable from Config::fetch_size.

This function will adjust its behaviour based on the plugin being a standard or streaming plugin. For standard plugins it will simply call acquire, so data is gathered and written to the provided handle (and as such, to stdout where munin expects it).

For streaming plugins it will create a temporary file beside the config::Config::plugin_cache, will rename the config::Config::plugin_cache and then use std::io::copy to “copy” the data to the provided handle.

Overriding this function

If you want to override this function, you should ensure that (for streaming plugins) you ensure that the cache file is reset, whenever fetch() runs, or old data may be given to munin needlessly. You also need to ensure to not accidently deleting data when dealing with your cachefile. For example: You read the whole cachefile, then output it to munin, then delete it - and during the halfsecond this took, new data appeared in the file, now lost.

fn check_autoconf(&self) -> bool

Check whatever is neccessary to decide if the plugin can auto-configure itself.

For example a network load plugin may check if network interfaces exists and then return true, something presenting values of a daemon like apache or ntp may check if that is installed - and possibly if fetching values is possible.

If this function is not overwritten, it defaults to false.

fn autoconf(&self)

Tell munin if the plugin supports autoconf.

Munin expects a simple yes or no on stdout, so we just print it, depending on the return value of MuninPlugin::check_autoconf. The default of that is a plain false. If it is possible for your plugin to detect, if it can autoconfigure itself, then implement the logic in MuninPlugin::check_autoconf and have it return true.

fn simple_start(&mut self, name: String) -> Result<bool>

A simplified start, only need a name, for the rest, defaults are fine.

This is just a tiny bit of “being lazy is good” and will create the MuninPlugin::config with the given name, then call the real start function. Only useful for plugins that do not use daemonization or need other config changes to run successfully..

fn start(&mut self, config: Config) -> Result<bool>

The main plugin function, this will deal with parsing commandline arguments and doing what is expected of the plugin (present config, fetch values, whatever).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors