doc: events and gauges

Events and Gauges

-----------------

The basic data type in FnordMetric is called a "gauge". A gauge stores one numerical value,

but has two dimensions: time and value. Each gauge is identified by a uniqe key (for example

"number_of_singups_per_minute"). The value of a gauge is periodically persisted into redis.

A "gauge" in FnordMetric is basically a bucket that stoes a numerical value. It has has two

dimensions: time and value. Each gauge is identified by a uniqe key (for example

"number_of_singups_per_minute"). The value of a gauge is periodically aggregated and persisted

into redis.

Gauges can be used in different modes: They can act as simple counters with an increment and

a decrement operation, but you can also use them to record the mean / average or the max/min

Some events have a special format and meaning (like "increment this counter by 4"

or "add this sample to the average query time gauge"). You don't have to write any

custom code to use these predefined events: Just send them (see [Sending Data](/documentation/classic_sending_data))

and FnordMetric will know what do to with them.

and FnordMetric will know what to do.

<br /><br />

#### Predefined Events: _incr, _decr, _set, _avg, _min, _max

  <tr>

    <th><b>flush_interval</b></i></th>

    <td>

      interval in which the value of this gauge is persisted in seconds. this is

      basically the gauge's resolution. the flush interval controls how much memory

      a gauge uses (smaller flush_intervals use more memory)

      interval in which the value of this gauge is aggregated persisted in seconds.

      this is basically the gauge's granularity / resolution. the flush interval

      controls how much memory a gauge uses (smaller flush_intervals use more memory)

      the default is 10 seconds

    </td>

  </tr>

</table>

<br />

<br /><br />

#### Predefined Events: _set_name, _set_picture

These events allow you the set a picture and display name for a visitor / user. They

require a `_session` key to identify a particular user session (more about that in

Sessions FIXPAUL). The picture and name are displayed e.g. in the "Active Users" Plugin

(FIXPAUL)

require a `_session` key to identify a particular user session (FnordMetric allows

you to track what a specific user is doing, more about that in Sessions FIXPAUL). The

picture and name are displayed e.g. in the "Active Users" Plugin (FIXPAUL)

    { "_type": "_set_name", "_session": "A7697BA0939C02E ", "name:" "Teddy Tester" }

    { "_type": "_set_name", "_session": "A7697BA0939C02E ", "name": "Teddy Tester" }

FIXPAUL: Reference

### Custom Events

You can also send completely custom events and write a piece of ruby code (called

the "event handler") that processes them. 

the "event handler") that tells FnordMetric what to do with them.

In this case the only requirement is that the event has a `_type` key, which is used

to identify the correct event handler. This is useful if you want to perform more than

one action but only want to send one piece of data from your app to FnordMetric.

#### Example: send a "user logged in up" event and increment two gauges

First we need to create a gauge. When using the predefined _incr, _decr, etc.. events

gauges are created on-the-fly, but when writing custom event handlers we need to do

this by hand. We create a gauge that stores the number of logins with a granularity (`flush_interval`)

of 1 minute and a another gauge that stores the number of total conversions per day.

    gauge :logins_per_minute,

      :tick => 1.minute.to_i,

      :title => "Logins per Minute"

    gauge :conversions_per_day,

      :tick => 1.day.to_i,

      :title => "Conversions per day"

The event that we will send to FnordMetric looks like this (the schema can be completely

custom, this is just an example):

    { "_type": "login", "user_id": 1231, "user_name": "Teddy Tester" }

We tell FnordMetric what to do with this event by writing an event handler: (FnordMetric

uses the `_type` key to lookup theevent handler). There a are a few DSL methods like `data`

and `incr` that we can use to access the event data and mofiy gauges. More info about that

in the Reference FIXPAUL.

    event :login do

      puts "user #{data[:user_name]} logged in"

      incr :logins_per_minute, 1

      incr :conversions_per_day, 1

    end

#### Catch-all event handler

In this case the only requirement is that the event has a

`_type` key, which is used to identify the correct event handler. All other fields

can be completely custom. This is useful if you want to perform actions on more

than one gauge but only want to send one piece of data from your app to FnordMetric.

You can register a event handler to the `*` type/key to have it executed for every incoming

event:

_Example: send a "user signed up" event and increment two gauges_

    event :"*" do

      puts "received event: #{data.inspect}"

    end

    fnord...

#### Special Keys

There is a small number of keys which have a special meaning, all of them

are prefixed with an underscore:

### Gauges

FnordMetric also offers an api to create these gauges by hand.

FIXPAUL gauge options reference

### API Reference

#### incr, etcetera

#### Sessions

FnordMetric allows you to track what a specific user is doing

  - storing data in the session

  - end of session callback

  - set_name/picture => above

Widgets

-------

FnordMetric includes a collection of UI widgets to display gauge data. You

can use these widgets with a simple ruby DSL.

FnordMetric includes a collection of UI widgets to display the data /

content of gauges. There is a simple ruby DSL to use these widgets.

_Example: Render a timeseries line chart on dashboard "Sales"_