ocean.net.collectd.Collectd

An utility class to interact with collectd-unixsock plugin

This class is a simple wrapper around Collectd's functionalities, providing parsing and communication means.

Most users will not want to use this module directly and should prefer the high-level stats API provided in ocean.util.log.Stats.

Public Imports

ocean.net.collectd.Identifier
public import ocean.net.collectd.Identifier;

Members

Classes

Collectd
class Collectd

Collectd wrapper class

CollectdException
class CollectdException

Exception to be thrown when an error happens in Collectd

Examples

Usage example

void sendCollectdData ()
{
    // Every call to collectd (but `listval`) needs to use an `Identifier`.
    // See Collectd's documentation for more information. Here we create an
    // app-global identifier.
    Identifier id =
    {
        host:               "example.com",
        plugin:             "http_server",
        type:               "requests",       // how much traffic it handles
        plugin_instance:    "1",              // the instance number
        type_instance:      "worker-1"
    };

    // Note that if you have a Collectd-provided identifier, you can
    // read it using `Identifier.create`
    // Here we use the convenience overload that throws on error, however
    // there is one version which returns a message if the parsing failed.
    auto id2 = Identifier.create("sociomantic.com/http_server-1/requests-worker-1");

    // Construct a Collectd instance that connect() to the socket.
    // If the connect() fails, an `ErrnoIOException` is thrown.
    // The parameter is the path of the Collectd socket
    auto collectd = new Collectd("/var/run/collectd.socket");

    // From this point on you can use the instance to talk to the socket.
    // Once a function that returns a set of data is called (e.g. `listval`),
    // no other function should be called until the result is fully
    // processed, as this class internally uses a rotating buffer to
    // minimize memory allocations.
    // If a new request is started while the previous one isn't
    // fully processed, a `CollectdException` will be thrown.

    // When writing a value, you need a structure that match a definition
    // in your `types.db` file.
    //
    // The documentation of `types.db` can be found here:
    // https://collectd.org/documentation/manpages/types.db.5.shtml
    //
    // The name of the struct doesn't matter, only what's in `id`.
    // To simplify the example, we use a struct that is defined by default
    // in `types.db`.
    // Note: the definition is `bytes value:GAUGE:0:U`
    static struct Charge { double value; }
    Charge charge = Charge(42.0);

    // Write an entry to collectd.
    collectd.putval(id, charge);
    // Will send `PUTVAL current_unix_timestamp:42` on the wire
}

See Also

Meta

License

Boost Software License Version 1.0. See LICENSE_BOOST.txt for details. Alternatively, this file may be distributed under the terms of the Tango 3-Clause BSD License (see LICENSE_BSD.txt for details).