= Tahoe-LAFS Stats-Gatherer Plugins =

1.  Overview
2.  Plugins Details
  1.  Helper Plugins
  2.  Traffic Plugins
  3.  Storage Plugins
  4.  Load Plugins
3.  Plugins Installation
4.  Plugins Testing

= Overview =

This is the README for the munin stats-gatherer plugins (see ticket #966).

For running these plugins you need to have a Tahoe-LAFS stats-gatherer node.

You can find more information in the file docs/stats.txt.

For plugins configuration please read tahoe-stats_conf.

= Plugins Details =

== Helper Plugins ==

  These plugins need a Tahoe-LAFS Helper:

 || tahoe_stats_helper_active_uploads          || Shows the number of files actively being processed by the helper            ||
 || tahoe_stats_helper_encoded_bytes           || Shows the number of bytes encoded by the helper                             ||
 || tahoe_stats_helper_encoding_files          || Shows the number of encoding files                                          ||
 || tahoe_stats_helper_encoding_filesize       || Shows total size of encoding files                                          ||
 || tahoe_stats_helper_encoding_files_old      || Shows total size of old encoding files                                      ||
 || tahoe_stats_helper_fetched_bytes           || Shows the number of bytes fetched by the helper                             ||
 || tahoe_stats_helper_incoming_files          || Shows the number of incoming files                                          ||
 || tahoe_stats_helper_incoming_filesize       || Shows total size of incoming files                                          ||
 || tahoe_stats_helper_incoming_files_old      || Shows total size of old incoming files                                      ||
 || tahoe_stats_helper_upload_already_present  || Shows the number of uploads whose files are already present in the grid     ||
 || tahoe_stats_helper_upload_need_upload      || Shows the number of uploads whose files are not already present in the grid ||
 || tahoe_stats_helper_upload_requests         || Shows the number of upload requests arriving at the helper                  ||

== Traffic Plugins ==

 || tahoe_stats_mutable_files_published  || Shows the number of mutable files published  ||
 || tahoe_stats_mutable_files_retrieved  || Shows the number of files retrieved          ||
 || tahoe_stats_uploader_bytes_uploaded  || Shows the number of bytes uploaded           ||
 || tahoe_stats_uploader_files_uploaded  || Shows the number of files uploaded           ||

== Storage Plugins ==

 || tahoe_stats_storage_allocated            || Shows space allocated             ||
 || tahoe_stats_storage_bytes_added          || Shows cumulative bytes added      ||
 || tahoe_stats_storage_bytes_freed          || Shows cumulative bytes removed    ||
 || tahoe_stats_storage_disk_used            || Shows space consumed              ||
 || tahoe_stats_storage_operations_allocate  || Shows how many allocate_buckets operations occurred per second. Each immutable file upload causes one such operation per server.  ||
 || tahoe_stats_storage_operations_get       || Shows how many get_bucket operations occurred per second. Each immutable file download/check causes one such operation per server. ||
 || tahoe_stats_storage_bytes_added          || Shows how many readv operations occurred per second. Each dirnode read causes one such operation per server.                       ||
 || tahoe_stats_storage_operations_writev    || Shows how many writev operations occurred per second. Each mutable file/dirnode write causes one such operation per server.        ||

== Load Plugins ==

 || tahoe_stats_runtime_load_peak       || Shows peak reactor delay                                                                        ||
 || tahoe_stats_runtime_load_avg        || Shows average reactor delay                                                                     ||
 || tahoe_stats_cpu_monitor_15min_avg   || Estimate of what percentage of system CPU time was consumed by the node process, 15min average  ||
 || tahoe_stats_cpu_monitor_5min_avg    || Estimate of what percentage of system CPU time was consumed by the node process, 5min average   ||
 
= Plugins Installation =

tahoe_stats need to be renamed/copied/linked to the plugin name you want. You need to do this for each graph you want.

For example:

If you want to show the "Tahoe-LAFS Runtime Load Average Graph":

Just copy tahoe_stats to '/etc/munin/plugins/tahoe_stats_runtime_load_avg'

If you want all graphs you can run these commands:

{{{
 cp tahoe_stats /etc/munin/plugins/tahoe_stats.bak 
 # the .bak extension is needed, otherwise Munin-Node will try to run it.
 cd /etc/munin/plugins/
 chmod +x tahoe_stats.bak
 for FILE in `grep "'tahoe_" tahoe_stats.bak | cut -d\' -f2`; do ln -s tahoe_stats.bak $FILE;done;
}}}
   
Edit the configuration file "tahoe-stats_conf" and copy it to /etc/munin/plugin-conf.d/

Reload the Munin-Node process: /etc/init.d/munin-node reload

Note: You need to wait 5 minutes before Munin-Node creates any graphs
  
= Plugins Testing =
  
To test a plugin you can run: munin-run <plugin_file>

For example:
{{{
 # munin-run tahoe_stats_storage_disk_used
 RM1X_gfsd.value 28093239296
 [..]
}}}
  
To display graph configuration add 'config' at the end of command line:
{{{
 #munin-run tahoe_stats_storage_disk_used config
 graph_title Tahoe-LAFS Storage Server Disk Used
 graph_vlabel bytes
 graph_category Tahoe-LAFS Stats-Gatherer_storage_server
 graph_info This graph shows disk usage for Tahoe
 graph_args --base 1024
 RM1X_gfsd.label RM1X_gfsd
 RM1X_gfsd.draw LINE1
 [..]
}}}