README.md

   1 [![Build Status](https://travis-ci.org/xandkar/beam_stats.svg?branch=master)](https://travis-ci.org/xandkar/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           % If you want to name your node something other than what
  41           % erlang:node() returns:
  42           , {static_node_name     , <<"unicorn_at_rainbow">>}
  43           ]}
  44       , {beam_stats_consumer_graphite,
  45           [ {consumption_interval , 60000}
  46           , {host                 , "localhost"}
  47           , {port                 , 2003}
  48           , {timeout              , 5000}
  49           ]}
  50       , {beam_stats_consumer_csv,
  51           [ {consumption_interval , 60000}
  52           , {path                 , "beam_stats.csv"}
  53           ]}
  54       , {some_custom_consumer_module,
  55           [ {some_custom_option_a, "abc"}
  56           , {some_custom_option_b, 123}
  57           ]}
  58
  59       ]}
  60   ]}
  61 ```
  62
  63 #### Dynamically
  64
  65 ```erlang
  66 beam_stats_consumer:add(consumer_module, ConsumerOptions).
  67 ```
  68
  69 ### Removing consumers
  70
  71 Not yet implemented.