OTLP and other changes

[Jyyjy]

UserALE Changes

1. OTLP-specific changes

Output format migrated to OTLP/HTTP JSON

UserALE no longer posts logs as a proprietary JSON array. All telemetry is now emitted as OTLP/HTTP JSON to POST /v1/logs on the configured endpoint. This makes UserALE compatible with any OpenTelemetry-compliant collector (Jaeger, Grafana, Honeycomb, etc.) out of the box.

• DOM events and custom logs are emitted as LogRecords
• UserALE-specific fields are mapped to userale.* resource attributes
• Browser context (URL, user agent, session IDs) maps to OTel semantic conventions (browser.url, user_agent.original, etc.)

Endpoint configuration

The url option (previously pointing at a custom UserALE backend) now points directly at an OTLP/HTTP collector. The default is http://localhost:4318, which matches the standard OTLP gRPC/HTTP port.

The script-tag attribute is data-url; the JS API is userale.options({ url: '...' }).

Shared local collector

A docker-compose.yml at the repository root provides a Jaeger all-in-one container as a zero-config local collector:

pnpm collector:up    # OTLP on :4318, Jaeger UI on :16686
pnpm collector:down

---

2. Other end-user facing changes

Three distinct deployment packages

UserALE is now distributed as three separate packages with clear use-case boundaries:

Package	npm name	When to use
core-sdk/	flagon-userale	Bundled apps, ESM imports, programmatic API
iife/	flagon-userale-iife	Plain HTML pages with a <script> tag and no build step
extension/	flagon-userale-ext	Instrument any site without touching its source code

IIFE build is configuration-only

The IIFE (flagon-userale-iife) is a drop-in that reads data-* attributes from the <script> tag and starts automatically. It does not expose a window.userale JavaScript API.

Applications that need runtime control (addCallbacks, stop, options, etc.) should use flagon-userale (the core SDK) directly in their build.

New programmatic API surface (core SDK)

The core SDK exposes a class-based API:

import { UserALE, Configuration } from 'flagon-userale';

const userale = new UserALE(Configuration.getInstance({ url: '...', userId: '...' }));

userale.start();
userale.stop();
userale.options({ url: 'https://new-endpoint' });
userale.addCallbacks({ filter(log) { ... }, map(log) { ... } });
userale.removeCallbacks(['filter']);
userale.log({ type: 'custom', ... });
userale.packageCustomLog({ type: 'click', label: 'Save' }, () => ({}), true);
await userale.flush();

Browser extension: options take effect immediately

Changing the logging endpoint or URL allowlist in the extension options page now takes effect immediately in the running background service worker — no extension reload required.

Browser extension: tab events logged

The extension captures browser tab lifecycle events (activate, create, update, remove, zoom, etc.) as custom UserALE logs alongside DOM events from the instrumented page.

---

3. Internal architecture and development changes

Package folder rename

The workspace package directories were renamed to match their function:

Old name	New name	npm publish name (unchanged)
packages/flagon-userale/	packages/core-sdk/	flagon-userale
packages/flagon-userale-iife/	packages/iife/	flagon-userale-iife
packages/flagon-userale-ext/	packages/extension/	flagon-userale-ext

npm publish names are unchanged; downstream consumers are unaffected.

Monorepo workspace dependencies

The extension package dependency on the core SDK was changed from a hardcoded file: path to a pnpm workspace:* reference, ensuring correct version resolution across the workspace.

Test architecture: per-distribution Playwright specs

Integration tests are now split across three spec files, each targeting one distribution:

Spec	Distribution	Browsers
01-iife.spec.ts	IIFE script-tag	Chromium, Firefox
02-esm.spec.ts	ESM core SDK	Chromium
03-extension.spec.ts	Browser extension	Chromium

Each spec uses a dedicated Playwright fixture (page.fixture.ts for iife/esm, extension.fixture.ts for extension) to avoid context contamination. Previously all tests shared a single spec and the extension fixture caused wrong-browser launches for non-extension tests.

Test server: three example pages

example-server/ now serves three pages, one per distribution:

Route	File	Purpose
/iife	iife.html	IIFE script-tag demo
/esm	esm.html + esm.js	ESM API demo with callbacks, stop/start
/no-logging	no-logging.html	Blank page for extension tests

Extension: replaced Plasmo messaging with raw chrome.runtime

The background/messages/config_change.ts Plasmo message handler was replaced with a raw chrome.runtime.onMessage listener in background/index.ts. Plasmo's generated messaging glue unconditionally returned true from its onMessage listener, causing a Chrome warning ("A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received") for every message that wasn't config_change. The raw listener returns false after each handled message type, eliminating the warning.

sendToBackground in utils/storage.ts was replaced with chrome.runtime.sendMessage for the same reason.

Extension: MV3 migration (Plasmo)

The extension was migrated from Manifest V2 to Manifest V3 using Plasmo. The background page became a service worker; persistent background state is managed via the background/index.ts entrypoint rather than a long-lived page.

TypeScript project references

A root tsconfig.json was added with project references to core-sdk and extension, enabling incremental compilation across the workspace.

Unit test isolation: getInitialSettings

The getInitialSettings unit tests were migrated from loading the IIFE bundle via jsdom to calling the function directly with injected DOM <script> elements. This removes the dependency on a built artifact from the test suite.