Apache Flagon UserALE.js (Incubating)
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:
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:
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:
<!--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.--> <!-- application goes here -->
Here is an example of a mapping function that adds customizable labels to events detected on specific DOM elements:
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.