Integration of the Boomerang Library into OpenACS
=================================================

Boomerang is a JavaScript library to measure the performance of your
website from your end user’s point of view. It has the ability to send
performance data measured at the client back to the server via a
beacon URL further analysis.  The boomerang library implements Real
User Measurement (RUM) to measure the performance experience of real
users by collecting quality indicators from the clients.

The boomerang library is released under the BSD license.

Details:
    https://soasta.github.io/boomerang/doc/

This package integrates boomerang with OpenACS, in particular with
OpenACS subsites.


FEATURES:
=========

- Obtain client site timings to measures the performance of your
  website from your end user's point of view.

- Support sampling (e.g. just obtain metrics from every nth request)

- Output performance data in a format suitable for feeding into
  Elasticsearch/Logstash (see below for example config files)

- Configure the appearance of the boomerang per subsite with
  the following parameters:
     BoomerangEnabled    0|1
     BoomerangSample     1
     BoomerangBeaconUrl  /boomerang_handler

  The parameter BoomerangSample can be used for busy sites
  to sample not every request (when the value is 1), but e.g.
  every 5th request (setting BoomerangSample to 5).
  
- Support for host-node-mapped subsites

- Site-wide admin support for compressing .js file

- Performance: include boomerang in the template costs about 0.3ms,
  processing of the beacon call takes about 1ms (filter times).


INSTALLATON:
============
 1) Install this package via the OpenACS Package Manager

 2) Add this package to the templating system

    - OpenACS 5.10.0d2 or newer:
      The boomerang plugin uses the "subsite::page_plugin"
      callback, so no changes on templates are necessary.

      Make sure to update as well the acs-bootstrap-installer to
      5.10.0d2 or newer to obtain the updated blank-master.

    - OpenACS 5.9.1:
      Add to the top of your blank-master.tcl the following snippet:

      ================================================================
      if {[info commands ::boomerang::initialize_widget] ne ""} {
	  ::boomerang::initialize_widget
      }
      ================================================================

 3) Configure in the parameters of the subsite (e.g. the main subsite)
    the section "Boomerang Plugin"


USAGE:
======
  For the explanation of the parameters, see:
     https://soasta.github.io/boomerang/doc/howtos/howto-0.html
     https://soasta.github.io/boomerang/doc/api/RT.html
     https://soasta.github.io/boomerang/doc/api/navtiming.html     


PREREQUIREMENTS:
================

The implementation uses nx from the next-scripting framework.

    https://next-scripting.org/xowiki/

which is automatically installed for XOTcl2 via
https://openacs.org/xowiki/naviserver-openacs

It works best with OpenACS 5.10.0d2 or newer, but works as well
with 5.9.1 (see INSTALLATION section above) or earlier versions
supporting Content Security Policy (CSP), and probably with  
earlier versions as well, when CSP code is commented out.


OPTIONAL: DEFINE A CUSTOM BOOMERANG PLUGIN
==========================================

 1) Clone boomerang repository
 
 2) Install npm, grunt if necessary

 3) Follow step 2 in https://github.com/SOASTA/boomerang
    which means
      ... configure plugins
      ... grunt clean build

 4) The result is in the build directory. The generated
    files have the a build-time stamp in seconds included.
    You might which to rename these with a custom name.
    
 5) Copy the *.min.js and *.min.js.gz files to
    the boomerang/www/resouces directory, which might be
    
      cp  build/boomerang-1.0.*.min.js build/boomerang-1.0.*.min.js.gz ..

    and adapt the version number in the boomerang parameters
    (on /acs-subsite)



OPTIONAL: FEED DATA INTO AN ELASTICSEARCH CLUSTER
=================================================

When boomerang is enabled, the results of the beacon are placed into
the OpenACS log directory with a name boomerang-*.log (containing the date).

Below are sample-snippets from OpenACS.org the log-files into elasticsearch,
such that it can be analyzed later with kibana or grafana.

Example filebeat  entry for the data feed:
------------------------------------------------------------
    -
      paths:
        - /var/www/openacs.org/log/boomerang-*.log
      input_type: log
      fields:
          log_type: boomerang-log
------------------------------------------------------------


Example logststash entry (input filter for transforming the data from filebeat
and to feed it into easticsearch)
------------------------------------------------------------
  if [fields][log_type] == "boomerang-log" {
    json {
       source => "message"
       remove_field => [ "restiming" ]
    }
    grok {
       match => [ "source", "/var/www/%{GREEDYDATA:server}/log/boomerang-" ]
    }    
    geoip { source => "clientip" }
  }
------------------------------------------------------------