Apache Flagon UserALE.js is the client-side instrumentation library for DOM and JavaScript applications. It automatically attaches event handlers, is configurable through HTML5 data-* attributes or a JavaScript/TypeScript API, and logs user interactions across web pages and single-page applications (SPAs) with zero runtime dependencies.
Install flagon-userale from npm:
npm install flagon-userale
# or
pnpm add flagon-userale
ESM)import * as userale from 'flagon-userale';
userale.options({
url: 'http://localhost:8000',
toolName: 'my-web-app',
toolVersion: '1.0.0',
logDetails: true,
});
IIFE)<script
src="./node_modules/flagon-userale/build/main.global.js"
data-url="http://localhost:8000/"
data-tool="my-web-app"
data-version="1.0.0"
></script>
OTLP/JSON)UserALE.js natively exports OpenTelemetry Logs (ExportLogsServiceRequest over HTTP/JSON) without requiring @opentelemetry/* packages:
<script
src="./node_modules/flagon-userale/build/main.global.js"
data-exporter="otlp"
data-otlp-endpoint="http://localhost:4318/v1/logs"
data-tool="checkout-web"
></script>
Try the full-stack OpenTelemetry + Grafana + Loki + Tempo Demo with docker compose up -d!
All options can be configured via HTML data-* attributes on the <script> tag or programmatically via userale.options({...}):
| JS Option | Script data-* Attribute |
Description | Default |
|---|---|---|---|
url |
data-url |
Logging endpoint URL (http://, https://, ws://, wss://) |
'http://localhost:8000' |
autostart |
data-autostart |
Start capturing and sending logs automatically on load | true |
transmitInterval |
data-interval |
Interval between batch transmit checks (ms) | 5000 |
logCountThreshold |
data-threshold |
Minimum queued logs required before interval send | 5 |
userId |
data-user |
User identifier | null |
sessionId |
data-session |
Session identifier | Auto-generated |
toolName |
data-tool |
Application / tool name (service.name in OTLP) |
null |
toolVersion / version |
data-version |
Application semantic version (service.version in OTLP) |
null |
logDetails |
data-log-details |
Include detailed event payloads (e.g. key codes, input values; password inputs are automatically masked) | false |
resolution |
data-resolution |
Aggregation interval for high-frequency events (mouseover, scroll, etc.) in ms |
500 |
userFromParams |
data-user-from-params |
URL query parameter to extract userId from |
null |
authHeader |
data-auth |
Authorization header string or callback |
null |
apiKey |
data-api-key |
Value sent in the x-api-key HTTP header |
null |
exporterType / exporterFormat |
data-exporter |
Wire format: 'http-json' (default), 'otlp' ('otlp-json'), 'proto-json', or 'websocket' |
'http-json' |
otlpEndpoint |
data-otlp-endpoint |
OpenTelemetry Collector HTTP logs endpoint (automatically appends /v1/logs if given a base origin) |
null |
headers |
data-headers |
Custom HTTP headers Record<string, string> (or JSON string in data-headers) merged into every request |
null |
observeMutations |
data-observe-mutations |
Enable throttled MutationObserver structural DOM telemetry (#104) |
false |
exporter |
— | Custom LogExporter instance implementing export(logs, options) |
null |
traceContext |
— | Optional () => ({ traceId, spanId }) callback for W3C TraceContext correlation |
null |
See the UserALE.js API Reference for full method, session replay, and exporter documentation.
The UserALE Browser Extension is a Manifest V3 extension built with Plasmo that injects UserALE.js into pages matching a configurable URL allowlist.
products/userale:
pnpm install
pnpm build
chrome://extensions/, enable Developer mode, click Load unpacked, and select products/userale/packages/flagon-userale-ext/build/chrome-mv3-prod/ (or chrome-mv3-dev/ when running pnpm dev).about:debugging, select This Firefox, click Load Temporary Add-on, and select manifest.json in products/userale/packages/flagon-userale-ext/build/firefox-mv3-prod/.UserALE JSON, OpenTelemetry (OTLP/JSON), or Protobuf v1 JSON), URL Allowlist, Excluded Event Types / Log Types, and Authentication (OAuth PKCE or API Key).Contributions are welcome! See our Contributing Guide or open an issue on GitHub.
