Getting Started

The Apache Flagon project provides a streamlined deployment solution for including behavioral logging capabilities in your project and for monitoring and analyzing your log data in a containerized Elastic backend. Our Docker container includes an Elastic backend, pre-configured, interactive Kibana dashboards. The container also includes prototype applications for exploration, Apache Distill and Apache Tap.

Before you begin, you’ll need NPM and Node.js, Docker and Docker Compose installed before you start.

Building and Deploying UserALE.js

Apache UserALE.js is the Apache Flagon’s thin-client behavioral logging solution. Below, you’ll find short-hand instructions for getting started with UserALE.js. For complete instructions, see our README.

First, download the release or clone our repo on GitHub. Apache UserALE.js is also available as an NPM package.

Next, install Dependencies.

  #intall NPM packages into build directory
  $ npm install

Then, build UserALE.js.

  #produce UserALE.js build artifacts
  $ npm run build

The build process produces a minified version of UserALE.js and a Web Extension package, giving you two options depending on your needs. You can skip the build process if you just want to explore UserALE.js; just use the minified script found in our repo.

Option 1: Include Apache UserALE.js in your project:

  #include userale in your project via script tag 
  <script src="/path/to/userale-2.0.2.min.js" data-url="http://yourLoggingUrl"></script>

Apache UserALE.js allows for configuration via HTML 5 data parameters. For a complete list of options, see the docs or the README. You can also modify Apache UserALE.js using our API. Find examples in our repos.

Option 2: Follow the instructions to install the Apache UserALE.js web extension into your browser.

You can now start generating behavioral log data from your page, or through your browser. To view these logs, you can either utilize our example logging server and log to file, or you can log directly to our Elastic backend. For complete instructions, see the README

Building and Using the Elastic Backend

Apache Flagon utilizes an Elastic stack for transforming, indexing, and storing log data. With Elastic, you’ll not only have the ability to search and query log data, but you’ll also be able to monitor it and visualize it through Kibana.

To build our single-node Elastic instance, first clone our Docker repo. Note that for production-level deployments, you should probably check out our Kubernetes build and our guide for scaling).

Then, start up a virtual machine.

# start virtual machine and requisite network 
$ docker-machine create --virtualbox-memory 3072 --virtualbox-cpu-count 2 flagon
$ docker-machine ssh flagon sudo sysctl -w vm.max_map_count=262144
$ docker network create esnet

Next, start Elastic services.

 #start Elastic services
 $ docker-compose up -d elasticsearch
 $ docker-compuse up -d logstash
 $ docker-compose up -d kibana

Configure UserALE.js to send logs to localhost:8100. This is easy: either modify the script tag for port 8100 or open up the “options” tab of the web extension and enter localhost:8100 as your logging end-point.

Before starting Kibana, generate some logs. Move your mouse around, click around, etc. Do this for a couple minutes to populate the index.

Finally, navigate to localhost:5601 (Kibana), set an index pattern, and load our visualizations and dashboards to see your logs. Find simple instructions in our README.

Subscribe to our dev list and join the conversation!