| 1 | # Backend Interface
|
| 2 |
|
| 3 | Backend modules are Node.js [modules][nodemods] that listen for a
|
| 4 | number of events emitted from StatsD. Each backend module should
|
| 5 | export the following initialization function:
|
| 6 |
|
| 7 | * `init(startup_time, config, events, logger)`: This method is invoked
|
| 8 | from StatsD to initialize the backend module. It accepts four
|
| 9 | parameters: `startup_time` is the startup time of StatsD in epoch
|
| 10 | seconds, `config` is the parsed config file hash, `events` is the
|
| 11 | event emitter that backends can use to listen for events and
|
| 12 | `logger` is StatsD's configured logger for backends to use.
|
| 13 |
|
| 14 | The backend module should return `true` from init() to indicate
|
| 15 | success. A return of `false` indicates a failure to load the module
|
| 16 | (missing configuration?) and will cause StatsD to exit.
|
| 17 |
|
| 18 | Backends can listen for the following events emitted by StatsD from
|
| 19 | the `events` object:
|
| 20 |
|
| 21 | * Event: **'flush'**
|
| 22 |
|
| 23 | Parameters: `(time_stamp, metrics)`
|
| 24 |
|
| 25 | Emitted on each flush interval so that backends can push aggregate
|
| 26 | metrics to their respective backend services. The event is passed
|
| 27 | two parameters: `time_stamp` is the current time in epoch seconds
|
| 28 | and `metrics` is a hash representing the StatsD statistics:
|
| 29 |
|
| 30 | ```
|
| 31 | metrics: {
|
| 32 | counters: counters,
|
| 33 | gauges: gauges,
|
| 34 | timers: timers,
|
| 35 | sets: sets,
|
| 36 | counter_rates: counter_rates,
|
| 37 | timer_data: timer_data,
|
| 38 | statsd_metrics: statsd_metrics,
|
| 39 | pctThreshold: pctThreshold
|
| 40 | }
|
| 41 | ```
|
| 42 |
|
| 43 | The counter_rates and timer_data are precalculated statistics to simplify
|
| 44 | the creation of backends, the statsd_metrics hash contains metrics generated
|
| 45 | by statsd itself. Each backend module is passed the same set of
|
| 46 | statistics, so a backend module should treat the metrics as immutable
|
| 47 | structures. StatsD will reset timers and counters after each
|
| 48 | listener has handled the event.
|
| 49 |
|
| 50 | * Event: **'status'**
|
| 51 |
|
| 52 | Parameters: `(writeCb)`
|
| 53 |
|
| 54 | Emitted when a user invokes a *stats* command on the management
|
| 55 | server port. It allows each backend module to dump backend-specific
|
| 56 | status statistics to the management port.
|
| 57 |
|
| 58 | The `writeCb` callback function has a signature of `f(error,
|
| 59 | backend_name, stat_name, stat_value)`. The backend module should
|
| 60 | invoke this method with each stat_name and stat_value that should be
|
| 61 | sent to the management port. StatsD will prefix each stat name with
|
| 62 | the `backend_name`. The backend should set `error` to *null*, or, in
|
| 63 | the case of a failure, an appropriate error.
|
| 64 |
|
| 65 | * Event: **'packet'**
|
| 66 |
|
| 67 | Parameters: `(packet, rinfo)`
|
| 68 |
|
| 69 | This is emitted for every incoming packet. The `packet` parameter contains
|
| 70 | the raw received message string and the `rinfo` parameter contains remote
|
| 71 | address information from the UDP socket.
|
| 72 | |
| \ | No newline at end of file |