Docs

Events

What your app reports to Sypnia, what every event carries, how events travel, and which ones count towards a plan.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The events at launch
  2. From the browser SDK
  3. From the server SDKs and OpenTelemetry
  4. What is not an event
  5. What every event carries
  6. Routes: paths without ids
  7. How events travel
  8. Noise the SDK never sends
  9. Which events count towards a plan
  10. Example: one failed payment, as events

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

EventSent whenWhat it carries
Session startA session begins.Browser and operating system, screen size, time zone, and the page the person came from (address and path, without its query).
IdentifyYour 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 viewA 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 leaveThe person navigates away, hides the tab or closes it.Time spent on the page, and how far down they scrolled, from 0 to 100.
ClickAny 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 clickThe rules in Rage and dead clicks are met.The same as a click, plus the number of clicks in the burst.
Performance measurementThe 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.
ErrorAn 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].
RequestThe 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 failureThe 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 eventYour code calls track(name, props).The name and the few properties you chose. See Browser.

From the server SDKs and OpenTelemetry

EventSent whenWhat it carries
Server requestYour 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 errorAn 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

FieldMeaning
TimeWhen it happened, by the sender’s clock.
ProjectDecided by the ingest key, not by the event.
Environmentproduction unless your app says otherwise.
ReleaseThe version of your app that sent it, if your app reports one.
Session and deviceThe 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 accountOnly 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.
PageThe path only: no domain, no query, no hash. And the route, which is the path with ids replaced.
ScreenViewport size, and the device class: mobile under 768 pixels wide, tablet under 1,024, otherwise desktop.
LanguageThe 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 %.

Text
/orders/8841/receipt              ->  /orders/:id/receipt
/api/carts/7f3e2a1c9b4d4e5f8a6b   ->  /api/carts/:id
/checkout                         ->  /checkout

How events travel

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 loop notice.
  • 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 eventPrecisely
An errorEach error stored, from the browser or the server.
A traceEach trace, once, however many spans it has. A request seen by the browser and by your server is one trace.
A performance sampleA 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:

#EventDetail
1Page viewroute /checkout
2Performance measurementLCP 1,240 ms, good, element: the order summary
3Clickbutton «Pay $64.00», in «Your order»
4RequestPOST /api/checkout, status 400, 412 ms
5Rage clickbutton «Pay $64.00», 5 clicks
6Page leave30 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».

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close