Telemetry
The rule
- Opt in on the root
ApollionProvider; nested providers never configure telemetry. - Keep the default
sampleRate(0.01): the shared endpoint caps it there. The roll is per browser session. - Pages on
apollion.com.br,localhost,127.x.x.x/::1,0.0.0.0,host.docker.internaland.local/.testhosts never report. LAN addresses do — add them toexcludeHostsif needed. - A telemetry failure never reaches your users: storage, network and callback errors are swallowed.
import { ApollionProvider } from '@apollion-dsi/core/themes';
<ApollionProvider telemetry={{ enabled: true, app: 'orders' }}>
<App />
</ApollionProvider>;How it works
What is measured. Each public component counts its mounts and the time from its first render to its
commit. That time includes the rest of the tree committed with it, so it ranks slow screens and heavy
subtrees, not one component's own cost. Layout primitives that are only styled elements (Box, Flex,
Grid, Paper) and the parts of a compound component (TableRow, TableCell) are not counted; only
the root (Table) is. Mounts made by other Apollion components count too.
Errors. Pass createTelemetryErrorHandler to your React root. Each error counts against the innermost
instrumented component in its component stack (Apollion's, or a name given to useTelemetry): as its own
error when that component threw, as an error within it when code below it threw (your children, or one of its uninstrumented internal parts), or as
unattributed; it works in minified builds. Your callback still runs; without one the handler does what
React does by default. Errors caught by ApollionTelemetryBoundary count once, as own errors under its component.
import { createTelemetryErrorHandler } from '@apollion-dsi/core/themes';
createRoot(container, {
onUncaughtError: createTelemetryErrorHandler(),
onCaughtError: createTelemetryErrorHandler(),
}).render(<App />);Cost to the page. Outside a sampled session each component does one boolean check per render and on
mount. A sampled session keeps counters in memory and sends one small request each time the tab is hidden
or closed, up to maxReportsPerSession, never one per mount.
Loops are flagged, not counted. Crossing a limit flags one apollion_loop event, once per kind and
component per session. Flags are collected for loopFlushMs and sent in one request, or with the report
when the tab hides first. The next onReport batch lists them in loops.
Limit | Default | At the limit |
|---|---|---|
renderLoopThreshold per renderLoopWindowMs | 300 / 1s | render_loop for that instance |
mountLoopThreshold per mountLoopWindowMs | 5000 / 1s | mount_loop, component stops counting |
maxErrorsPerComponent between two reports | 20 | error_loop, component stops counting |
reloadLoopThreshold reloads per reloadLoopWindowMs | 10 / 60s | reload_loop, session goes silent |
maxReportsPerSession | 30 | report_cap, session goes silent |
maxComponents | 96 | further names are ignored |
maxLoopEventsPerSession | 10 | further loop events are dropped |
loopFlushMs | 5000 | collected loop flags go in one request |
Override any of them with limits; values outside TELEMETRY_LIMIT_RANGES are clamped. On the shared
endpoint (any apollion.com.br host) maxComponents, maxReportsPerSession and maxLoopEventsPerSession cannot rise above their
defaults. excludeHosts adds hosts, such as staging, that never report.
Delivery and privacy. Reports go to https://apollion.com.br/_t, which forwards them to Grafana Labs
(Grafana Cloud Frontend Observability). Each report names the page origin (meta.page.url, such as
https://app.example.com: scheme, host and port, never path or query), so apps can be told apart. Like any
request, it reveals the client IP; the reports never contain it. Under a strict Content Security Policy, allow
connect-src https://apollion.com.br/_t. Requests are sent with referrerPolicy: 'strict-origin' — even when the page sets no-referrer — so
the edge sees the origin only, never the path. sessionStorage holds apollion-telemetry-sampled, -sid (a random per-tab id) and
-state; enabled: false removes them.
Local check. endpoint: '' sends nothing, samples on any host (localhost included) and hands each
batch (v, app, c mounts, e own errors, w errors within, t timings, loops) to onReport.
<ApollionProvider telemetry={{ enabled: true, sampleRate: 1, endpoint: '', onReport: console.log }}>
<App />
</ApollionProvider>Your own components. Call useTelemetry('OrderCard') unconditionally as the first statement of a
component and destructure props after it, so errors are attributed in minified builds. Custom names share
maxComponents with Apollion's; use static literals that do not reuse its names. Import useTelemetry
and ApollionTelemetryBoundary from @apollion-dsi/core/themes.
Pitfalls
app,useTelemetrynames and boundarycomponentnames are reported as-is: never put user data in them.ApollionTelemetryBoundaryrendersfallback(defaultnull) after an error; passrethrowto keep your own error boundary in charge.- A custom
endpointmust behttps://or a same-origin path and receives a Grafana Faro JSONPOSTof at most 15 000 characters.