backend_interface.md

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.