-
Notifications
You must be signed in to change notification settings - Fork 2
Coding a Driver for DaTtSs
The driver plays a very important role in DaTtSs as it pre-aggregates data to avoid overcharging your network and leverage HTTP reliability. A driver sends the pre-aggregated values it has received periodically, every push-period (by default 5s). These pre-aggregated values are called partial-aggregates. They are sent to DaTtSs through the Agggregation API on the PUT /agg endpoint (see DaTtSs API Documentation) where they are indexed and accesible later on through DaTtSs website or any
other client based on DaTtSs' Access API.
This page describes how a driver works, which interface it should comply to and how it is expected to behave so that you can write your own driver and make DaTtSs available for you favorite language or environment. [Note: A driver creator and active maintener is of course given free and unlimited access to DaTtSs! A simple way for us to thank you for your work :)]
If you make a driver and feel proud about it, we want to hear about it! Feel free to make a pull-request on dattss-sdk so that it can be featured there! Feel free to inspire yourself from the drivers already featured there and don't hesitate to reach out through email team@dattss.com or IRC at #dattss on irc.freenode.org.
First of all a driver should provide a configuration interface so that users can globally configure the following variables:
# DEFAULT CONFIGURATION
DATTSS_AUTH_KEY=DUMMY // Global AUTH_KEY to use (by default DUMMY)
DATTSS_PUSH_PERIOD=5 // Default push period (in s)
DATTSS_PERCENTILE=0.1 // Default percentile value
DATTSS_SERVER_HOST=agg.dattss.com // Default DaTtSs server
DATTSS_SERVER_PORT=80 // Default DaTtSs port
The specific interface you provide for configuration is probably extremely dependent on the environment / language you are working with. Nevertheless, it is not acceptable to ask the user to edit your code to set their AUTH_KEY or servers. The configuration interface should must be programmatic: constructor arguments, shared or specific config files, environment variables, are all viable solutions.
As an example the NodeJS driver, reads these variable from the environment as well as the command-line arguments of the process it is bundled in.
DaTtSs statistics are organised by processes. A process is a logical group of statistics that are displayed together in DaTtSs and accessible as a group through the Access API. A driver should provide a process method taking a process name as single non-optional argument. The process method should accept additional 2 optional arguments: auth and pct. The auth arguments lets the user override the globally configured AUTH_KEY and the pct argument, the globally configured percentile value.
/* types exposed by the driver */
class dattss // the driver type
class process // the process type
/* `process` method signature */
process dattss.process(
string name // the compulsory process name
[,string auth_key] // the optional `AUTH_KEY` for that process
[,float pct] // the optional percentile value to use
)
The process method should follow a singleton pattern, meaning that for a given {name, auth} tuple, the same process object should always be returned. This is important as it prevents the user from generating a number of process objects with the same AUTH_KEY and name that would eventually interfere with each others.
The process object should expose these three public methods which behavior is described in the next sections:
/* `agg` method signature */
void process.agg(
string stat, // the stat name
string value // the stat value string
)
/* `start` method signature */
void process.start()
/* `stop` method signature */
void process.stop()