Skip to content
Apache Flagon User Ale JS (Incubating)
JavaScript HTML
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build [FLAGON-433] Fix NPM package issue, npm dependency update, documentat… Aug 6, 2019
example [FLAGON-433] minor fix to readme, updated changelog Aug 6, 2019
src [FLAGON-433] Fix NPM package issue, npm dependency update, documentat… Aug 6, 2019
test
.babelrc
.eslintrc.json initial release May 25, 2016
.gitignore
CHANGELOG.md
DISCLAIMER
KEYS [FLAGON-399>FLAGON-403] Adding missing license headers, updating vers… Jun 14, 2019
LICENSE [FLAGON-416] Updated UserALE.js License appendix to cannon Jul 4, 2019
NOTICE
README.md [FLAGON-433] Fix NPM package issue, npm dependency update, documentat… Aug 6, 2019
doap-userale.js.rdf
gulpfile.js [FLAGON-407] found foldername discrepancy] Jun 16, 2019
package-lock.json
package.json [FLAGON-433] Fix NPM package issue, npm dependency update, documentat… Aug 6, 2019

README.md

Apache Flagon UserALE.js (Incubating)

Build Status License

The official JavaScript client for Apache Flagon UserALE.

UserALE.js is a client side instrumentation library written in JavaScript. It is designed to be an easy-to-use, lightweight, and dependency-free way to quickly gather logs from your web applications.

Additional documentation can be found at our project website.

What's New in Version 2.0.2?

  • Updates to package.json and package-lock.json to resolve downstream Prototype Pollution vulnerabilities in dev dependencies
  • Updates to package.json and package-lock.json to modernize deprecated npm modules
  • Minor updates to README documentation for UserALE.js' Example Test Utilities.

See our CHANGELOG for a complete list of changes.

Prerequsites

To build UserALE.js, you will need to download our source (here), our release distributions or include in your project via the flagon-userale NPM module.

UserALE.js utilizes NPM for package and dependency management. Execute the following to install dependencies.

#install required packages
npm install

#review major dependencies
npm ls --depth=0

Pre-tested and pre-built UserALE.js script are included in the /build dir in our repositories, release artifiacts, and our NPM module. However, you can modify and build your own versions of these scripts with the following steps:

Build

To build UserALE.js:

#Build UserALE.js
npm run build

Test

To test UserALE.js:

#Run UserALE.js unit tests
npm run test

... you'll see something like:

...
    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 logging an issue in JIRA.

Use and Configure

To start logging with UserALE.js, you can either include our script in the web application to be logged, or use our WebExtension to gather logs across any page a user visits.

To collect logs from a specific project, simply include this script tag on the page:

<script src="/path/to/userale-2.0.2.min.js"></script>

UserALE.js is designed to be easily configured to fit your use case. We use HTML data parameters to pass configuration options to the library. For example, to set the logging URL:

<script src="/path/to/userale-2.0.2.min.js" data-url="http://yourLoggingUrl"></script>

The complete list of configurable options is:

Param Description Default
data-url Logging URL http://localhost:8000
data-autostart Should UserALE.js start on page load true
data-interval Delay between transmit checks 5000 (ms)
data-threshold Minimum number of logs to send 5
data-user User identifier null
data-version Application version identifier null
data-log-details Toggle detailed logs (keys pressed and input/change values) false
data-resolution Delay between instances of high frequency logs (mouseover, scroll, etc.) 500 (ms)
data-user-from-params Query param in the page URL to fetch userId from null
data-tool Name of tool being logged null

If you're interested in using our WebExtension to log user activity across all pages they visit, check out our browser specific instructions here.

You can also test out UserALE.js behavior with different script tag parameters using our 'example' test utility.

Customizing your logs

For some applications, it may be desirable to filter logs based on some runtime parameters or to enhance the logs with information available to the app. To support this use-case, there is an API exposed against the global UserALE object.

The flagon-useralejs NPM module exposes UserALE.js functions for use in the NPM environment. However, this API is a cleaner, more intuitive way of modifying UserALE.js behavior to suite your needs.

The two functions exposed are the setLogFilter and setLogMapper functions. These allow dynamic modifications to the logs at runtime, but before they are shipped to the server.

Here is an example of a filter that bounces out unwanted log and event types from your logging stream:

<html>
  <head>
    <script src="/path/to/userale-2.0.2.min.js" data-url="http://yourLoggingUrl"></script>
<!--
Modify the array page-by-page to curate your log stream:
by adding unwanted event 'types' in type_array;
by adding unwanted log classes to eliminate 'raw' or 'interval' logs from your stream.
-->
  <script type="text/javascript">
    var type_array = ['mouseup', 'mouseover', 'dblclick', 'blur', 'focus']
    var logType_array = ['interval']
    window.userale.filter(function (log) {
      return !type_array.includes(log.type) && !logType_array.includes(log.logType);
    });
  </script>
  <body>
    <div id="app">
      <!-- application goes here -->
    </div>
  </body>
</html>

Here is an example of a mapping function that adds customizable labels to events detected on specific DOM elements:

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

Even with this small API, it is possible to compose very powerful logging capabilities and progressively append additionally app-specific logic to your logs.

You can experiment with these functions in our example test utility.

Contributing

Contributions are welcome! Simply submit an issue report for problems you encounter or a pull request for your feature or bug fix. 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.

You can’t perform that action at this time.