README for statsd2ws
====================

statsd2ws provides a realtime websocket stream connection to a statsd service 
and a simple web UI for viewing instrument readings in realtime.


Building From Source
--------------------

statsd2ws is a Maven project, and building the deployable .war file should
be as simple as checking out the source and running::

  mvn package

The executable .war will be created in the target folder.


Installation
------------

statsd2ws is installed on statsd.dataone.org under /opt/statsd2ws

It is a self contained Jetty application packaged in a .war file.

It is started by an init.d script, /etc/init.d/statsd2ws

If a new version of the .war file is created, then it is necessary to adjust
the init.d script to ensure it points to the correct .war file name.

The service listens on port 6780, and once started can be connected directly
by a web browser at:

  http://statsd.dataone.org:6780/
  
The static .js and .html components of the app are also made available through
apache at:

  https://statsd.dataone.org/statsd2ws/
 
Apache loads the static content from /opt/statsd2ws/webapp. The webapp folder
needs to be manually created. To do so, recursively copy the /tmp/xxx/webapp 
folder generated by Jetty after starting the app to /opt/statsd2ws 

This whole process could be streamlined, but it's easier to document it...


Operation
---------

Once running, statsd2ws listens for statsd datagram messages relayed by the 
statsd service. It translated the datagram message into a JSON message, and
forwards it over the websocket connection, effectively broadcasting the 
instrument reading to whatever is listening on that channel.

The UI is entirely in Javascript and a little HTML. The instrument values are
plotted in realtime charts (by Smoothie Charts). The charts are generated 
dynamically when a new instrument is detected (i.e. an instrument name shows up
that was not seen before).

Since the number of instruments can be a bit overwhelming, a filter may be 
specified in the URL using the "f" query parameter. The filter is a regular 
expression that instrument names must match to be displayed. A couple of 
examples:

Display all instruments as they appear::

  https://statsd.dataone.org/statsd2ws/

Display instruments only starting with "cn-sandbox"::

  https://statsd.dataone.org/statsd2ws/?f=cn-sandbox.*
  
Display instruments only starting with "cn-sandbox" and ending with "bps"::

  https://statsd.dataone.org/statsd2ws/?f=cn-sandbox.*bps

  
The realtime chart shows a timeline of 10 minutes. Longer periods may be 
displayed by clicking on the word "Show" in the "Last 6 Hours" column. These 
charts are static images that are retrieved from the Graphite service, also
running on statsd.dataone.org under /graphite. The charts may be refreshed
by clicking on the word "refresh" in the table header.

The duration of the static history charts may be specified by the "h" URL query
parameter, which should be an integer indicating the number of minutes of 
history to be displayed. The default value is "360", providing six hours of
history in the chart. To display one hour for example:: 

  https://statsd.dataone.org/statsd2ws/?h=60

The "h" and "f" parameters may be combined, for example::

  https://statsd.dataone.org/statsd2ws/?f=cn-sandbox.*bps&h=60