UI Telemetry
UiTelemetry records which components and features people use, so the app needs no hand-written tracking calls. It reads the same component registry as UiAgent. Each event therefore names its component by kind and stable ref, such as button:save, rather than by a CSS selector that breaks when the markup changes.
import wvlet.uni.ui.telemetry.{UiTelemetry, UiTelemetrySink}
val uiTelemetry = UiTelemetry.install(UiTelemetrySink.relay())Nothing is recorded before install or after uninstall(). If the app needs consent, ask for it first and install afterwards.
Events
| Event | When | Attributes |
|---|---|---|
ui.press | A button or menu item is clicked, or pressed with Enter or Space | ui.kind, ui.ref, ui.source (pointer, keyboard, or agent) |
ui.change | A component commits a change through onChange | ui.kind, ui.ref, ui.key, ui.reason, ui.source (pointer, keyboard, or agent), and ui.value for valueKinds |
ui.open / ui.close | A dialog, menu, or command palette opens or closes | ui.kind, ui.ref, and duration.ms on close |
ui.view | A tab stops being selected, the page is hidden, or telemetry is uninstalled | ui.ref, duration.ms, and the tab's label as ui.value |
command.run | A command palette runs a command | command.id, ui.source |
What gets recorded and how:
- Stable names. Refs come from
UiAgent.ref("name")when the app sets one, else from the kind and label. Commands are named by theirCommandid. - Merged bursts. A pointer drag, or typing into one field, becomes one
ui.changewith the last value. Changes to the same component and key withinmergeWindowMillis(1 second) merge. - Only what people and agents do. Changes the app's own code makes are left out, unless
withProgrammaticChanges(true)is set. - Hidden parts stay hidden. Components inside
UiAgent.hidden,hidden,inert, oraria-hidden="true"are left out, as they are for agents. - No values by default. Values can be what people typed or picked, so only tab labels are recorded.
withValueKinds("tabs", "select")adds more kinds. Fields markedUiAgent.secret, and password fields, are always redacted.
Configuration
import wvlet.uni.ui.telemetry.UiTelemetryConfig
val sampled = UiTelemetryConfig(UiTelemetrySink.relay())
.withSampleRatio(0.25) // a quarter of page sessions record anything
.withValueKinds("tabs", "select")
.withAttribute("app.version", "1.4.0")
.install()How batches are sent:
- Events are batched and sent every 5 seconds (
withFlushIntervalMillis), and right away when the page is hidden or closed. - Each page session gets a random
sessionId, which is sent with each batch. Nothing ties it to a person. uiTelemetry.flush()sends the queue now.
Sinks
A Uni server, then OTLP
UiTelemetrySink.relay() posts batches with fetch and keepalive to /_uni/telemetry/ui on the page's own server. The last batch is delivered even while the page closes. On the server, UiTelemetryRelay passes each event to the service's Telemetry. With withOtlp, the events go to the OTLP /v1/logs endpoint of the Datadog Agent or an OpenTelemetry Collector, next to the server's traces and metrics:
import wvlet.uni.http.{Http, UiTelemetryRelay}
import wvlet.uni.telemetry.Telemetry
import wvlet.uni.telemetry.otlp.OtlpConfig
val telemetry = Telemetry().withServiceName("web").withOtlp(OtlpConfig())
Http.server.withFilter(UiTelemetryRelay(telemetry)).withRxHandler(app).start()The browser can't post OTLP to the Datadog Agent itself: the Agent doesn't accept a page's origin and shouldn't face the internet. The relay is the only endpoint that does.
Anyone who can load the page can reach that endpoint, so the relay accepts only what UiTelemetry sends:
application/jsononly, which a browser sends to another site only after a CORS preflight that the relay doesn't answer.- When the request has an
Originheader, its host must match the request'sHost. - At most 64 KiB and 200 events per request.
UiTelemetrySink.relay()splits its batches to fit. - Event names under
ui.orcommand.. - Lower-case attribute keys, string values cut to 256 characters, and no nested values.
For a public page, put authentication or rate limiting in front of it.
Datadog RUM
If the page already loads the Datadog browser SDK, UiTelemetrySink.datadogRum() reports each event as a RUM custom action. The action is named after the event and its ref, for example ui.press button:save, and the attributes go in its context. RUM's own click tracking names actions from the text on the page; these names come from the component's ref instead.
val rum = UiTelemetry.install(UiTelemetrySink.datadogRum())By default it uses the window.DD_RUM global of the CDN script. If you import the SDK from npm, pass the datadogRum object instead. If the SDK isn't on the page, nothing is sent.
Your own
UiTelemetrySink(batch => ...) hands each batch to any analytics SDK, and UiTelemetrySink.all(a, b) sends to several sinks.
Limits
- Only bound components are seen. That covers uni-ui components that agents can see. A plain
divwith anonclickhandler isn't recorded. - Dock panels report no view time yet. The Dock reports only its maximized panel, not which tab is active.