❤Noodly Pasta Maker

npm

Sign UpSign In
Publish your own packages to the world's most popular software ecosystem with npm Pro.Get started »

flagon-userale

2.0.2 • Public • Published

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.

Keywords

Install

npm i flagon-userale

DownloadsWeekly Downloads

4

Version

2.0.2

License

Apache-2.0

Unpacked Size

213 kB

Total Files

49

Homepage

flagon.incubator.apache.org

Repository

Gitgit.apache.org/incubator-flagon-useralejs.git

Last publish

Collaborators

  • avatar
Try on RunKit
Report a vulnerability