(Draft)
It's the README file for munin stats-gatherer plugins
Please see ticket #966

= Tahoe-LAFS Stats-Gatherer plugins =

1.  Overview
2.  Plugins details 
  2.1.  Helper plugins
  2.2.  Traffic plugins
  2.3.  Storage plugins
  2.4.  Load plugins
3.  Plugins Installation
4.  Plugins testing

== Overview ==

  For running these plugins you need to have a Tahoe-LAFS stats-gatherer node.
  You can find more infomation in file docs/stats.txt

  For plugins configration 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 cummulative bytes added
  tahoe_stats_storage_bytes_freed:            Shows cummulative bytes removed
  tahoe_stats_storage_disk_used:              Shows space consumed
  tahoe_stats_storage_operations_allocate:    Shows how many allocate_buckets operations occured per second.
                                              Each immutable file upload causes one such operation per server

  tahoe_stats_storage_operations_get:         This graph shows how many get_bucket operations occured per second.
                                              Each immutable file download/check causes one such operation per server

  tahoe_stats_storage_bytes_added:            Shows how many readv operations occured per second.
                                              Each dirnode read causes one such operation per server.

  tahoe_stats_storage_operations_writev:      Shows how many writev operations occured 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;
   
    After, 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 5min before Munin-Node perform graphs
  
= Plugins testing =
  
  To test 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' a 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
    [..]