Collect Rack

Collect Rack is a web frontend for graphing .rrd files generated by collectd.

Before Collect Rack I made rrd2html.rb which is a very minimal (you could say code golfed) CGI application.
This project was born out of dissatisfaction with rrd2html.rb and inspired by pommi/CGP.

The "Collect" part of the name refers to collectd. The "Rack" part for it being a Rack app.

Web Framework	Sinatra
Templating Engine	Slim
Gateway Interface	Rack
Server	Puma or other Rack::Handler
Graphing	rrdtool
Data Collection	collectd

Features

Speed

Collect Rack aims to be significantly faster than existing web frontends for collectd.
By the magic of using puma as the default webserver collect rack can be aggressively parallelized.
The application also interacts with the official Ruby bindings of librrd instead of spawning a process, and the output is streamed through a pipe directly to the webserver.
When rendering many graphs Collect Rack has about twice the speed of CGP.

FLUSH

It can also utilize the unixsock plugin to flush the caches of the plugins its graphing.
This means that your graphs will always be up-to-date even with a large CacheTimeout setting.

collectd.conf parsing

CollectRack can parse your existing collectd.conf file to draw configuration values from.
You can even configure CollectRack specific settings via your existing collectd.conf.

Running

After running bundle install, the app can be started using bin/rackup, bin/puma or ruby src/app.rb. I personally recommand starting Collect Rack via puma.

When using puma you can configure middleware using config.ru and modify the puma configuration in config/puma.

There is also a package available for OpenSUSE.

Using a systemd.service

Please see the collectrack.service shipped with the OpenSUSE package for reference.

If you’re using a packaged version of collect rack and you’d like to change the default behaviour use a systemd override.

#/etc/systemd/system/collectrack.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/share/collectrack/bin/puma -e production -b unix:/run/collectrack.sock

To run Collect Rack with additional middleware you can choose to configure your own config.ru rackup file and execute that instead.

There’s also the Puma documentation regarding systemd.

Requirements

About librrd and the RRD.so

Collect Rack relies on functions in the ruby bindings for rrdtool.
These bindings are distributed alongside rrdtool in most linux distributions.
In some distributions it is shipped seperately as ruby-rrdtool.

However for some years the ruby bindings in rrdtool weren’t being linked correctly.
This was fixed upstream (cbb9a81) but hasn’t been part of a release yet.

To fix this Collect Rack currently ships with a working RRD.so file in libs/RRD.so.
This library was dynamically linked on an x86_64 OpenSUSE Tumbleweed installation and will likely not work on every environment.
You may need to build rrdtool and then place the RRD.so ruby binding in libs/.

OpenSUSE has backported the patch (request 1277244).

Ruby 3.4

Collect Rack uses some Ruby 3.4 features.

Configuration

Collect Rack uses the same syntax as collectd.conf and by default it searches for your existing /etc/collectd.conf.

If you want to use a config file that is not /etc/collectd.conf you can specify it using the COLLECTD_CONFIG environment variable.

For options specific to CollectRack you can use a block called CollectRack.

An example config could look like this:

BaseDir "/var/lib/collectd"

<CollectRack>
  PluginConfDir "/opt/collectrack/plugins"
  FlushSocket   true
  CollectdMiddleware true

</CollectRack>

<Plugin unixsock>
  SocketFile "/run/collectd.sock"
</Plugin>

Options for the CollectRack block are:

• PluginConfDir: Where to draw .yaml plugin configurations from. Default ./plugins.

• FlushSocket: Flush the collectd cache when drawing graphs. The unixsock plugin must be configured for this to work. Default true.

• CollectdMiddleware: Enable middleware for own sending metrics to collectd

FlushSocket is suboptimal for response times. If for whatever reason your goal is to render as much graphs per second as possible leave it off.

Default plugin behavior

Collect Rack ships aims to ship with instructions to graph most popular collectd plugins (see ./plugins).
However I cannot configure all plugins for all environments and some plugins are inherently unpredictable.
So there is a default behavior for graphing unknown databases.

This default behavior is to draw a separate graph for each .rrd file found in a plugin instance.
A line is then drawn for each ds in the database.

This doesn’t work well for some plugins like memory or cpu which have multiple data sources saved as ds value across multiple databases.
For these a single graph with data across all databases would be preferred.

However most plugins store different units in different files.
So for most other plugins the current behavior produces good graphs, even for generally unconfigurable plugins like sensor.

Configuration Parser

This project ships a ruby implementation of the collectd.conf parser made with rexical and racc. Its code lives in src/config. You could use this in your own projects if you need to parse collectd configurations. See the readme at src/config/README.adoc.

Development

Please see the DEVELOPMENT.adoc file for instructions on how to develop for and release collectrack.