statsd/docs/backend_interface.md

Network daemon for the collection and aggregation of realtime application metrics

# Backend Interface

Backend modules are Node.js [modules][nodemods] that listen for a
number of events emitted from StatsD. Each backend module should
export the following initialization function:

* `init(startup_time, config, events, logger)`: This method is invoked
  from StatsD to initialize the backend module. It accepts four
  parameters: `startup_time` is the startup time of StatsD in epoch
  seconds, `config` is the parsed config file hash, `events` is the
  event emitter that backends can use to listen for events and
  `logger` is StatsD's configured logger for backends to use.

  The backend module should return `true` from init() to indicate
  success. A return of `false` indicates a failure to load the module
  (missing configuration?) and will cause StatsD to exit.

Backends can listen for the following events emitted by StatsD from
the `events` object:

* Event: **'flush'**

  Parameters: `(time_stamp, metrics)`

  Emitted on each flush interval so that backends can push aggregate
  metrics to their respective backend services. The event is passed
  two parameters: `time_stamp` is the current time in epoch seconds
  and `metrics` is a hash representing the StatsD statistics:

  ```
  metrics: {
    counters: counters,
    gauges: gauges,
    timers: timers,
    sets: sets,
    counter_rates: counter_rates,
    timer_data: timer_data,
    statsd_metrics: statsd_metrics,
    pctThreshold: pctThreshold
  }
  ```

  The counter_rates and timer_data are precalculated statistics to simplify
  the creation of backends, the statsd_metrics hash contains metrics generated
  by StatsD itself. Each backend module is passed the same set of
  statistics, so a backend module should treat the metrics as immutable
  structures. StatsD will reset timers and counters after each
  listener has handled the event.

* Event: **'status'**

  Parameters: `(writeCb)`

  Emitted when a user invokes a *stats* command on the management
  server port. It allows each backend module to dump backend-specific
  status statistics to the management port.

  The `writeCb` callback function has a signature of `f(error,
  backend_name, stat_name, stat_value)`. The backend module should
  invoke this method with each stat_name and stat_value that should be
  sent to the management port. StatsD will prefix each stat name with
  the `backend_name`. The backend should set `error` to *null*, or, in
  the case of a failure, an appropriate error.

* Event: **'packet'**

  Parameters: `(packet, rinfo)`

  This is emitted for every incoming packet. The `packet` parameter contains
  the raw received message string and the `rinfo` parameter contains remote
  address information from the UDP socket.