Skip to the content

Telemetry

Apollion can report, from a small sample of real sessions, how often each component mounts, how long its first render takes to commit, how often it fails and when it loops. It is off by default and sends nothing without your opt-in. Reports carry the page origin but no cookies, user identifiers, page paths or DOM text.
Guides

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.internal and .local / .test hosts never report. LAN addresses do — add them to excludeHosts if 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
Scrolls sideways inside the table. The page does not.

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, useTelemetry names and boundary component names are reported as-is: never put user data in them.
  • ApollionTelemetryBoundary renders fallback (default null) after an error; pass rethrow to keep your own error boundary in charge.
  • A custom endpoint must be https:// or a same-origin path and receives a Grafana Faro JSON POST of at most 15 000 characters.

See also