Events
What your app reports to Sypnia, what every event carries, how events travel, and which ones count towards a plan.
This page is for anyone who wants to know what leaves their app. It applies to the open-source engine and to Sypnia Cloud alike: the SDKs and the event contract are the same. The machine-readable contract is the event schema.
An event is one thing your app reported to Sypnia: an error, a click, a page that loaded, a request and how long it took. Everything Sypnia tells you is built from events.
The events at launch
From the browser SDK
| Event | Sent when | What it carries |
|---|---|---|
| Session start | A session begins. | Browser and operating system, screen size, time zone, and the page the person came from (address and path, without its query). |
| Identify | Your code calls identify(). | The person’s id and the account’s id, and their names and the person’s e-mail if your app sends them. It is the only event that carries a name or an e-mail. See Identifying people. |
| Page view | A page loads, or the app navigates to another page. A change in the query or hash alone is not a page view. | How the person got there (a full load, a navigation or a redirect inside the app, back or forward) and the route of the page before. |
| Page leave | The person navigates away, hides the tab or closes it. | Time spent on the page, and how far down they scrolled, from 0 to 100. |
| Click | Any click. | What was clicked, in words: its label (the control’s accessible name or visible text, up to 80 characters), what kind of control it is (button, link, tab, field…), and where it was (the open dialog’s title or the nearest heading). Never the value of a field. |
| Rage click, dead click | The rules in Rage and dead clicks are met. | The same as a click, plus the number of clicks in the burst. |
| Performance measurement | The browser reports LCP, INP, CLS or TTFB for a page. | The value, its rating, and the element behind it. See Performance. The SDK also sends FCP, which is kept with the raw events and not shown in the performance numbers. |
| Error | An error nobody caught, a promise rejected with no handler, an error caught by your framework’s error screen, or an error you report yourself. | Its name, message (up to 500 characters) and stack (up to 4,000 characters), with e-mail addresses replaced by [email]. |
| Request | The page calls your API, or another address you listed, and gets an answer, or no answer. | Method, route, status, duration and the trace id. For a failed call, the error code and the start of the error message from the answer (up to 40 and 160 characters). Never the request or response body. |
| Form failure | The browser refuses to submit a form because a field is not valid. | The field’s label and the reason (required, wrong format, too long…). Never what was typed. |
| Custom event | Your code calls track(name, props). | The name and the few properties you chose. See Browser. |
From the server SDKs and OpenTelemetry
| Event | Sent when | What it carries |
|---|---|---|
| Server request | Your server finishes handling a request. A request still running after 20 seconds is sent at that moment as a partial record. | Method, route, status, duration, the trace it belongs to, and its spans: up to 200 database calls, calls to other services and internal steps, each with its name, kind, start, duration, status and a limited set of attributes. See Traces. |
| Server error | An exception is thrown while handling a request, a call the request made fails, the request answers 500 or above, or your code writes to console.error during a request. At most 5 for each request. | Name, message, stack, and the trace it belongs to. The message of a failed call is redacted before it leaves your server. |
A backend that reports through OpenTelemetry sends spans, and the engine turns them into the same two things.
What is not an event
- Replay recordings and page snapshots are uploaded apart from events and counted as replays. See Sessions and replay.
- Uptime results are produced by the engine, not by your app. See Uptime.
What every event carries
| Field | Meaning |
|---|---|
| Time | When it happened, by the sender’s clock. |
| Project | Decided by the ingest key, not by the event. |
| Environment | production unless your app says otherwise. |
| Release | The version of your app that sent it, if your app reports one. |
| Session and device | The session’s id, and a random id the SDK keeps in the browser’s storage to tell devices apart. Neither identifies a person. |
| Person and account | Only if your app called identify(): the person’s id, and the id of the account, the team or company the person belongs to in your app. Events carry the two ids and nothing else about the person; names and e-mails travel once, in the identify event. See Identifying people. |
| Page | The path only: no domain, no query, no hash. And the route, which is the path with ids replaced. |
| Screen | Viewport size, and the device class: mobile under 768 pixels wide, tablet under 1,024, otherwise desktop. |
| Language | The page’s language. |
Routes: paths without ids
Sypnia groups pages and API calls by route, so /orders/8841 and /orders/8842 are the same page. A segment of the path becomes :id when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or when it contains %.
/orders/8841/receipt -> /orders/:id/receipt
/api/carts/7f3e2a1c9b4d4e5f8a6b -> /api/carts/:id
/checkout -> /checkoutHow events travel
- The browser SDK queues events in memory and sends a batch every 10 seconds, or as soon as 50 are waiting. A batch holds at most 200 events.
- When the tab is hidden or closed, it sends what is waiting at once, in a way the browser completes even while the page goes away.
- A batch that fails because of the network or a busy server is sent again, after 1, 4 and 15 seconds; the batch carries an id, so a repeated batch is not stored twice.
- Ingest checks each event on its own. An event that is not valid, or that is more than 7 days old, is dropped and counted in the answer; the rest of the batch is stored. Strings that are too long are cut, not refused.
- Ingest answers once the events are safely written, which takes up to 2 seconds. The answer says how many events were stored.
The server SDKs do not wait for a batch: they send a request’s record when the request ends.
Delivery is best effort. The queue lives in memory, holds at most 500 events and is not kept between page loads. When it overflows, the oldest clicks go first and errors go last. A browser that crashes or loses its connection for good can lose its last seconds.
Raw events keep fields the engine does not know. A newer SDK never breaks an older engine.
Noise the SDK never sends
The browser SDK leaves out errors that are not your app’s:
- Errors thrown by browser extensions, and errors whose stack lies entirely in scripts from other sites.
Script error.with no detail, which browsers report for scripts from other sites.- The browser’s
ResizeObserver loopnotice. - The same error again within 5 seconds: it counts once.
- More than 20 errors in one minute from one page.
Which events count towards a plan Cloud
On Sypnia Cloud a plan includes a number of events a month, for the whole organization. Three kinds of event count:
| Counts as one event | Precisely |
|---|---|
| An error | Each error stored, from the browser or the server. |
| A trace | Each trace, once, however many spans it has. A request seen by the browser and by your server is one trace. |
| A performance sample | A page view with its measurements. The LCP, INP, CLS and TTFB of one page view are one sample. |
Everything else is free and does not count: session starts, page views, page leaves, clicks, rage and dead clicks, form failures and custom events. Replays are counted apart, as replays a month.
Every project has usage counters you can read at any time, in the app and through the API. What happens when a limit is reached is in Plans and limits. A self-hosted engine has no limits set by us; you can set your own quotas in its configuration.
Example: one failed payment, as events
A customer of the shop opens the checkout and clicks Pay five times. The payment is rejected. In order, the browser SDK sends:
| # | Event | Detail |
|---|---|---|
| 1 | Page view | route /checkout |
| 2 | Performance measurement | LCP 1,240 ms, good, element: the order summary |
| 3 | Click | button «Pay $64.00», in «Your order» |
| 4 | Request | POST /api/checkout, status 400, 412 ms |
| 5 | Rage click | button «Pay $64.00», 5 clicks |
| 6 | Page leave | 30 seconds, scrolled 100 |
The API server sends the spans of the same trace, including the rejected call to the payment service. Of these, two count towards the plan: the trace, and the page view with its measurement. Together they become one occurrence of the problem «3 people tried to pay today and could not».