Sampling and quotas
Which sessions are recorded and how to change it, what the SDKs send and hold back, the «slow down» signal, and exactly what happens when a project reaches a limit.
This page is for whoever decides how much Sypnia records and what it costs. The SDKs behave the same with the open-source engine and with Sypnia Cloud. What differs is where limits come from: a plan on Sypnia Cloud, a quota you set yourself (or none) on your own engine.
At the end you will know: which sessions get a replay, how to record more or fewer, and what your app’s SDK does when a limit is reached. Nothing is ever dropped silently.
What is sampled, and what is not
| Signal | Sampled? | Rule |
|---|---|---|
| Errors | No | Every error is sent, within the noise rules: the same error counts once per 5 seconds, and at most 20 errors a minute per page. |
| Page views, clicks, rage and dead clicks, form failures, custom events | No | Every one is sent. |
| Performance (LCP, INP, CLS, TTFB) | No | Every page reports its values. |
| API calls from the browser | No | Every call to your origin and to traceTargets and recordTargets. |
| Server requests (Node, Next.js) | No | Every request is traced, except static files, OPTIONS and your ignoreRoutes. Sampling of successful requests is Planned. |
| OpenTelemetry spans | By you | Sypnia stores what your SDK or Collector sends. |
| Replays | Yes | See below. |
| Page snapshots, for click maps | Yes | Half of the sessions, at most one per route and five per session. |
Which sessions get a replay
The engine decides once per session, and the SDK asks for the decision when the session starts. There are three ways into a recording:
- Something goes wrong. Every session keeps its last 30 to 60 seconds in the browser’s memory and uploads nothing. At the first error, rage click or dead click, the SDK uploads those seconds and records from there on. This needs no setting.
- The session is in the sampled share. A share of all sessions is recorded from their start. The default is 10 %.
- An «always record» rule names the session’s person or account.
The decision is stable: the same session always gets the same answer, in every tab. If the SDK cannot reach the engine to ask, it behaves as in point 1.
A recording ends after 720 pieces, which is two hours of recording. The session goes on without it.
Change the share
The share is a project setting, replay.sample_rate, from 0 to 1. It is not an option in code, so you change it without shipping your app, and it reaches each browser with its next session.
Sypnia Cloud
Change it in the project’s settings in the app, or with the API and an API token that has the admin scope:
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"replay": {"sample_rate": 0.25}}}'Self-hosted
With the API and an API token that has the admin scope, or the root token:
curl -X PATCH "https://sypnia.example.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"replay": {"sample_rate": 0.25}}}'200 and the project, with "sample_rate": 0.25 under settings.replay.| Setting | Type | Default | Meaning |
|---|---|---|---|
replay.sample_rate | number, 0 to 1 | 0.1 | The share of sessions recorded from their start. 0 records only sessions where something goes wrong. 1 records every session. |
replay.always_record | list | [] | Persons and accounts whose sessions are always recorded. See below. |
replay.blocked_routes | list of routes | [] | Routes where nothing is recorded. See Privacy and masking. |
replay.mask_all_text | boolean | false | Masks every text in every recording. |
snapshots.sample_rate | number, 0 to 1 | 0.5 | The share of sessions that take page snapshots for click maps. |
To switch recording off for good in one app, whatever the project says, pass replay: false to init: the recorder is then never loaded.
Always record a person or an account
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"replay": {"always_record": [
{"person": "u_1042", "note": "Reported the checkout bug", "until": "2026-03-26T00:00:00Z"}
]}}}'Each rule names a person or an account by the id your app passes to identify(), and may carry a note and an until date after which it stops. The rule applies from that person’s next session. Within a session that is already running, it applies from the moment the person is identified, if the SDK had not asked before. On a self-hosted engine use your own base URL.
The «slow down» signal
Every answer from ingest says how many events were stored and how many were not, and why. When the project has reached a limit, the answer also carries slow_down:
{
"accepted": 1,
"dropped": 1,
"dropped_reasons": { "limit_reached": 1 },
"slow_down": {
"reason": "events_limit",
"send": "failures",
"replay": false,
"until": "2026-04-01T00:00:00Z"
}
}The SDKs obey it at once and remember it until until, in every tab:
| In the signal | What the SDK does |
|---|---|
send: "failures" | It sends failures only: errors, failed API calls, and on the server the requests that failed with their spans. It also keeps sending what ties a failure to a visit and a person: session starts, page views and identify. It stops sending performance values, successful requests, clicks, form failures and custom events. |
replay: false | It stops recording and uploading. A session that would have been recorded gets a marker saying so (replay_gap, reason limit), so its timeline tells you. |
until | When to go back to normal. The SDK asks again at the start of the next session after that time. |
The same object comes with the per-session settings the SDK reads at the start of each session, so a browser that opens your app after the limit was reached never starts sending what would be refused.
A burst is a different thing. If one address sends too fast with one key, ingest answers 429 with Retry-After. The SDK waits that long, at most 60 seconds, and sends the same batch again once.
What happens at a limit
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Where limits come from | Nowhere, unless you set a quota for a project in the engine's configuration. | Your plan: events a month and replays a month. |
| At 80 % | An alert is recorded, and sent to your webhook if you set one. | The organization's owners get an alert by e-mail and in the app. |
| At 100 % of events | Ingest sends slow_down. Failures are still stored. | Ingest sends slow_down until the month ends. Failures are still stored, so a new problem still appears and still alerts. |
| At 100 % of replays | Ingest tells the SDKs to stop recording. | Ingest tells the SDKs to stop recording until the month ends. Sessions are still listed with their full timeline. |
| What you can read | Usage counters through the API and the CLI. | Usage counters in the app and through the API, with how many events were not stored. |
What counts as an event on Sypnia Cloud is narrow: an error, a trace, or a performance value. Page views, clicks, form failures and custom events are free. The exact rules and the numbers of each plan are in Plans and limits; the quotas of a self-hosted engine are in its configuration.
Send less on purpose
Before a limit is the better time to choose what matters:
| To reduce | Do |
|---|---|
| Server traces | Add noisy routes to ignoreRoutes in the Node SDK: health checks, polling endpoints. |
| Browser requests | Add polling calls to ignoreRequests. |
| Errors you will never fix | Add them to ignoreErrors, or mark the problem as ignored. |
| Performance values | capture: { vitals: false } in the browser SDK. |
| Replays | Lower replay.sample_rate. Sessions with trouble are still recorded. |
| Everything from a part of the app | ignoreRoutes. |
Check what applies to a session
Set debug: true. At the start of a session the SDK prints the decision it received, for example replay: buffer (sample_rate 0.1), and any slow_down in force.
Next
- What each plan includes and how each limit is counted.
- What a replay shows, and what it never shows.
- The answers of ingest, field by field.