# What is this ?

Drone is a monitoring library designed to collect data from your application and export them
to virtually any monitoring tool.
Its core is heavily based on the impressive works of Coda Hale on the metrics java library.

A fully working example is included in examples/simple, to run it
(I suppose you already cloned the repository and have a prompt at the root of it):

    gem install bundler
    bundle
    ruby examples/simple.rb
  
The example will output the collected statistics directly on the console every second.

# Supported Runtimes

- MRI 1.8.7+
- Rubinius 1.2.2+


# Status
 - Most of the features I wanted in are (see below for usage examples):
  - timing method calls
  - method calls rate
  - counters
  - gauges

 - Good test coverage
 
 The gem was created for a specific need and is currently used in preproduction environment,
 no major bugs until now.


# How is it done

The library is split in different parts

- the core:<br/>
  it contains all the API used to declare which data to collect and how as well as the storage for them

- the metrics:<br/>
  that is all the metrics type the library know.

- the interfaces:<br/>
  those are the parts which will decides how the stored data are made available.

- the schedulers:</br>
  this is where the timers are scheduled, currently there is only one scheduler: eventmachine

- the storage:<br/>
  this part decides where the actual data for the metrics are stored, the default is to store them
  in memory but other possible options are: redis, memcached, etc...
  The goal for external storage is to allow concurrent applications to share the same metrics, an
  immediate example of such application is a rails application ran under passenger or any other spawner

## Constraints

- the name of each metric can be formatted how it pleases you (note that output interfaces may expect some format)
  but the name is expected to be unique or you could end up reusing the same metric without wanting it.
  (this only applies to monitor_time and monitor_rate helpers but could apply anywhere else as needed)

# Usage
  
  I try to keep things as simple as possible, there is currently two ways to use
  this library:
  
  - the first one is to just instantiate metrics by hand and use them directly
  
      ``` ruby
      require 'drone'
      Drone::init_drone()
      @counter = Drone::Metris::Counter.new('my_counter')
    
      def some_method
        @counter.inc()
      end
      ```
  
  - the other way is to instrument a class:
  
      ``` ruby
      require 'drone'
      Drone::init_drone()
      
      class User
        include Drone::Monitoring
        
        monitor_rate("users/new")
        def initialize(login, pass); end
        
        monitor_time("users/rename")
        def rename(new_login); end
        
      end
      ```
      
      This code will create three metrics:
      - "users/new"       : how many users are created each second
      - "users/rename"    : how much time renaming a user takes and how many users are renamed
                            each second
      
  
Once you have your data you need to add a way to serve them, each lives in a separate
gem to limit the core's dependencies so the only one in core is:
  
  - console output (puts), mainly for debug:
  
      ``` ruby
      require 'drone'
      Drone::init_drone()
      Drone::add_output(:console, 1)
      ```
      
      The values will be printed on the console at the inter
  
  The others output are available in their own gems:
  
  - drone_json:<br/>
    The stats are served by a thin server in json
  
  - drone_collectd:<br/>
    The stats are send to a collectd daemon.
  
# Goals

  My goal is to be able to serve stats efficiently from any ruby 1.9 application built
  on top of eventmachine and fibers but I built the library to allow non eventmachine uses too, for
  now the only part where eventmachine is required is the scheduler.
  
  Implementing a scheduler based on a background Thread is possible but before that work
  needs to be done to ensure thread safety, Actually the library is not thread safe.
  
  if someone wants to implements it I am not against it but I prefer it to be added as an
  optional part instead of in the core. There should not be any problem to implements it
  in an includable module not included as default (it may requires some modifications in the core):
  
  ``` ruby
  require 'drone'
  require 'drone/threadsafe'
    
  # [...]
  ```
  
# Development

  Installing the development environment is pretty simple thanks to bundler:
  
    gem install bundler
    bundle
  
## Running specs
  
  The specs are written with bacon, mocha and em-spec, they can be ran with:
  
    rake spec
  
## Build the doc
  You will need the gems: yard and bluecloth and then run:
  
    rake doc