Apache Flagon UserALE.js is a comprehensive, thin-client behavioral logging tool

Clone this repo:
  1. 0bb7a9a [flagon-userale 45] fixes typos in readme by poorejc · 5 weeks ago master test
  2. 51d4455 fixes userale version typos in readme by Gedd Johnson · 5 weeks ago
  3. 73155e4 merging PR 69 rollup build refactor by poorejc · 6 weeks ago
  4. 7a56eb5 adding PR 69 and build artifacts from integration testing by poorejc · 6 weeks ago
  5. 4b4c7e0 merging PR 69 rollup refactor by poorejc · 6 weeks ago

Apache Flagon UserALE.js (Incubating)

Node.js CI Snyk Vulnerabilities for npm package Maintenance npm License

Apache UserALE.js is part of the Apache Flagon Project. It is a client side instrumentation library written in JavaScript designed for easy deployment and lightweight configuration in gathering logs from your web applications for user behavioral analytics.

Once included in your project, Apache UserALE.js provides a comprehensive behavioral logging capability, capturing every event on every element rendered in your DOM.

Additional documentation and a demonstration can be found at the Apache Flagon website.

Quickstart Guide

  1. Include UserALE.js in your project as either a module or script tag
  2. Set up a logging end-point. Try our example server utility or try out our Elasticsearch (ELK) stack example.
  3. Configure UserALE.js settings using our API, including where to POST logs to (port:8000 for UserALE example or port:8100 of ELK/Logstash)
  4. Further explore the UserALE.js API to customize your log feed, add filters, custom logs, and modify logs themselves. Explore a few examples here and a wider set in our example utility.
  5. Visualize and analyze your logs. See our sample kibana dahsboards for behavioral analytics.

Table of Contents

What's New
Installation
Configure
Usage
Examples
Indexing, Storing, and Visualizing Logs
Modifying Source
Contributing
License

What's New in Version 2.1.1?

  • Fixes bug in SessionID creation at initial PageLoad
  • Update to Node.js/NPM Engine support (tested 12.x, 13.x, 14.x, 15.x)
  • Minor updates to resolve extant vulnerabilities in dependency tree
  • Minor updates to update deprecated downstream dev dependencies
  • Minor updates to build pipelines to accommodate dependency updates
  • Minor changes to documentation
  • Minor QOL upgrades to UserALE.js repository (CI, Dependabot)

See our CHANGELOG for a complete list of changes.

Installation

Either through cloning our source repo or by using npm:

npm install flagon-userale

To include UserALE.js as an object in your project, include as a module:

import * as userale from 'flagon-userale';

or

const userale = require('flagon-userale');

Our webpack example illustrates this use-case.

You can also include UserALE.js as a script-tag. A pre-built version of the userale script is included in our package and repositories:

<script src="./node_modules/flagon-userale/build/userale-2.1.1.min.js"></script>

Our script tag example illustrates this use-case

If you include UserALE.js as a script-tag, consider installing via npm as a development dependency:

npm install --save-dev flagon-userale

We also support a WebExtension that can be added to your browser in developer mode. Follow the link for instructions.

Configure

Some configuration is necessary. At minimum you will need to provide UserALE.js an end-point to ship logs to; default behavior is to ship logs to localhost:8000.

NOTE: In order to facilitate testing configuration and usage of UserALE.js, we have included an example logging server in our example directory. This is a very helpful utility that works with both included module examples and script-tag examples. We strongly recommend experimenting with it.

Configuration details follow:

If you have included UserALE.js in your project as a module, you will need to use our ‘userale.options’ function, which exposes library configuration options through our API:

const changeMe = "me";
userale.options({
    "userId": changeMe,
    "url": "http://localhost:8000/",
    "version": "next",
    "logDetails": false,
    "sessionID": "this one"
});

The complete list of configurable parameters that can be configured via ‘userale.options’ is:

ParamDescriptionDefault
urlLogging URLhttp://localhost:8000
autostartShould UserALE.js start on page loadtrue
transmitIntervalDelay between transmit checks5000 (ms)
logCountThresholdMinimum number of logs to send5
userIdUser identifiernull
sessionIDSession identifiernull
versionApplication version identifiernull
logDetailsToggle detailed logs (keys pressed and input/change values)false
resolutionDelay between instances of high frequency logs (mouseover, scroll, etc.)500 (ms)
userFromParamsQuery param in the page URL to fetch userId fromnull
toolNameName of tool being loggednull
authHeaderAuthorization header to be passed to logging endpointnull

If you have included UserALE.js as a script-tag in your project, you can use HTML data parameters to pass configuration options to the library through the script tag. For example:

  <script
          src="./node_modules/flagon-userale/build/userale-2.1.1.min.js"
          data-url="http://localhost:8000/"
          data-user="example-user"
          data-version="2.1.1"
          data-tool="Apache UserALE.js Example"
  ></script>

You have access to the same parameters listed above, however, naming conventions vary slightly for use in HTML:

ParamDescriptionDefault
data-urlLogging URLhttp://localhost:8000
data-autostartShould UserALE.js start on page loadtrue
data-intervalDelay between transmit checks5000 (ms)
data-thresholdMinimum number of logs to send5
data-userUser identifiernull
data-versionApplication version identifiernull
data-log-detailsToggle detailed logs (keys pressed and input/change values)false
data-resolutionDelay between instances of high frequency logs (mouseover, scroll, etc.)500 (ms)
data-user-from-paramsQuery param in the page URL to fetch userId fromnull
data-toolName of tool being loggednull
data-authAuthorization header to be passed to logging endpointnull

If you are using our WebExtension, you can modify some of these parameters via the extensions' ‘options’ page.

Usage

Including UserALE.js in your project as a module attaches the UserALE.js script as an object to the page.

We have exposed a number of functions that assist you in modifying, filtering, and customizing logs

A complete list of available functions are as follows:

FunctionDescriptionNotes
userale.optionsmodify userale's configuration optionsee top level README for complete list of options
userale.filterfilters out logs from logging queue by keys or valuesfilters are callbacks with global scope
userale.mapmodify/add log keys or valuesmappings are callbacks with global scope
userale.logappends a custom log to the log queuethe custom log object is an object key:value pairs
userale.packageLogtransforms the provided event into a log and appends it to the log queuedesigned for HTML events
userale.packageCustomLogpackages the provided customLog to include standard meta data and appends it to the log queuedesigned for non HTML events
userale.detailsdefines the way information is extracted from various eventssupports packageLog/packageCustomLog ‘details’
userale.getSelectorbuilds a string CSS selector from the provided HTML element idpopulates ‘target’ field in packaged logs
userale.buildPathbuilds an array of elements from the provided event target, to the root element (DOM path)populates the ‘path’ field in packaged logs
userale.startused to start the logging process ifunecessary if ‘autostart’ is set to true in initial setting (default)
userale.stophalts the logging process. Logs will no longer be sentwill need to invoke userale.start to restart logging

Including UserALE.js as a script-tag provides you access to the same functions listed above. However, UserALE.js essentially becomes a property of the DOM. As such, you'll need to call functions as a window property:

userale.options = window.userale.options

Examples

We provide a number of examples to illustrate how the functions above can be used with sample webpages and logging servers. These are tailored for module examples and script-tag examples. Select examples are below:

Filter your logs with userale.filter:

userale.filter(function (log) {
    var type_array = ['mouseup', 'mouseover', 'mousedown', 'keydown', 'dblclick', 'blur', 'focus', 'input', 'wheel'];
    var logType_array = ['interval'];
    return !type_array.includes(log.type) && !logType_array.includes(log.logType);
});

Modify (add/remove) log fields with surgical precision using userale.map:

userale.map(function (log) {
        var targetsForLabels = ["button#test_button"];
        if (targetsForLabels.includes(log.target)) {
            return Object.assign({}, log, { CustomLabel: "Click me!" });
        } else {
            return log;  
        } 
      });

Generate custom logs with userale.log:

document.addEventListener('change', function(e) {
    if (e.target.value === 'log') {
        userale.log({
            target: userale.getSelector(e.target),
            path: userale.buildPath(e),
            type: e.type,
            logType: 'custom',
            userAction: false,
            details: 'I can make this log look like anything I want',
            customField1: 'foo',
            customField2: 'bar',
            userId: userale.options().userId,
            toolVersion: userale.options().version,
            toolName: userale.options().toolName,
            useraleVersion: userale.options().useraleVersion,
            sessionID: userale.options().sessionID,
            customLabel: "(custom) Log Example"
        });
    }
});

User our own log packaging pipeline to streamline custom HTML event logging with userale.packageLog:

document.addEventListener('change', function(e){
    if (e.target.value === 'packageLog') {
        /**You can then use the 'Mapping' API function to modify custom logs created with the packageLog function*/
        userale.map(function (log) {
            var targetsForLabels = ['change'];
            if (targetsForLabels.includes(log.type)) {
                return Object.assign({}, log, { logType: 'custom', customLabel: 'packageLog Example' });
            } else {
                return log;
            }
        });
        /**You can also use the details function to package additional log meta data, or add custom details*/
        userale.packageLog(e, userale.details(userale.options(),'change'));
    } else {
        return false
    }
});

Again, see Usage for differences in invoking these functions with module and script-tag includes.

You can find additional examples on our website.

Indexing, Storing and Visualizing Logs

We recommend Elastic products, specifically an ELK cluster, for indexing and storing logs in productions.

You can find a ‘sand-box’ ELK build, configuration files, and visualization/dashboards tailored for UserALE.js in the Apache Flagon parent repository.

We also provide some documentation about stack-considerations on our project website.

Modifying Source

You may wish to modify UserALE.js to suite your needs. After making modification to UserALE.js src, you will need to rebuild the UserALE.js script (and run tests).

To (re)build UserALE.js:

npm run build

To run UserALE.js unit tests:

npm run test

We use gulp-mocha for unit tests. The results will print to your terminal:

...
    attachHandlers
    ✓ attaches all the event handlers without duplicates
    ✓ debounces bufferedEvents (505ms)
    defineDetails
      - configures high detail events correctly
...

  45 passing (954ms)
  1 pending

Any failing tests will also be logged in the terminal. If there are failing tests, please consider submitting an issue report.

For more guidance on modifying Flagon UserALE src code, check out the guide on our website.

Contributing

Contributions are welcome! Simply submit an issue. Pull requests are welcome. The core team will review it and work with you to incorporate it into UserALE.js. If you want to become a contributor to the project, see our contribution guide.

Join the conversation: tell us your needs, wishes, and interests by joining our mailing list!

License

Apache Flagon UserALE.js is provided under Apache License version 2.0. See LICENSE and NOTICE files at MASTER for more details.

Disclaimer

Apache Flagon is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator project. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

A copy of this disclaimer can also be found in UserALE's source repository.