README.md

   1 [![Build Status](https://travis-ci.org/ibnfirnas/beam_stats.svg?branch=master)](https://travis-ci.org/ibnfirnas/beam_stats)
   2
   3 beam_stats
   4 ==========
   5
   6 Periodically collects and pushes VM metrics to arbitrary consumer processes,
   7 which, in-turn, can do whatever they want with the given data (such as
   8 serialize and forward to some time series storage). Includes, off by default,
   9 example implementations of consumers for:
  10
  11 - StatsD (`beam_stats_consumer_statsd`)
  12 - Graphite (`beam_stats_consumer_graphite`)
  13 - CSV file (`beam_stats_consumer_csv`)
  14
  15 Essentially like `folsomite`, but different. Different in the following ways:
  16
  17 - More-general: consumers other than graphite can be defined
  18 - More-focused: only concerned with VM metrics, while `folsomite` ships off
  19   _everything_ from `folsom` (in addition to VM metrics)
  20 - Easier-(for me!)-to-reason-about implementation:
  21     + Well-defined metrics-to-binary conversions, as opposed to the
  22       nearly-arbitrary term-to-string conversions used in `folsomite`
  23     + Spec'd, tested and Dialyzed
  24
  25 ### Adding consumers
  26
  27 #### At app config time
  28
  29 ```erlang
  30 {env,
  31   [ {production_interval , 30000}
  32   , {consumers,
  33       [ {beam_stats_consumer_statsd,
  34           [ {consumption_interval , 60000}
  35           , {dst_host             , "localhost"}
  36           , {dst_port             , 8125}
  37           , {src_port             , 8124}
  38           , {num_msgs_per_packet  , 10}
  39           ]}
  40       , {beam_stats_consumer_graphite,
  41           [ {consumption_interval , 60000}
  42           , {host                 , "localhost"}
  43           , {port                 , 2003}
  44           , {timeout              , 5000}
  45           ]}
  46       , {beam_stats_consumer_csv,
  47           [ {consumption_interval , 60000}
  48           , {path                 , "beam_stats.csv"}
  49           ]}
  50       , {some_custom_consumer_module,
  51           [ {some_custom_option_a, "abc"}
  52           , {some_custom_option_b, 123}
  53           ]}
  54
  55       ]}
  56   ]}
  57 ```
  58
  59 #### Dynamically
  60
  61 ```erlang
  62 beam_stats_consumer:add(consumer_module, ConsumerOptions).
  63 ```
  64
  65 ### Removing consumers
  66
  67 Not yet implemented.