Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. What is sampled, and what is not
  2. Which sessions get a replay
  3. Change the share
  4. Always record a person or an account
  5. The «slow down» signal
  6. What happens at a limit
  7. Send less on purpose
  8. Check what applies to a session
  9. Next

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

SignalSampled?Rule
ErrorsNoEvery 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 eventsNoEvery one is sent.
Performance (LCP, INP, CLS, TTFB)NoEvery page reports its values.
API calls from the browserNoEvery call to your origin and to traceTargets and recordTargets.
Server requests (Node, Next.js)NoEvery request is traced, except static files, OPTIONS and your ignoreRoutes. Sampling of successful requests is Planned.
OpenTelemetry spansBy youSypnia stores what your SDK or Collector sends.
ReplaysYesSee below.
Page snapshots, for click mapsYesHalf 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:

  1. 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.
  2. The session is in the sampled share. A share of all sessions is recorded from their start. The default is 10 %.
  3. 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:

Terminal
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}}}'
You should see
200 and the project, with "sample_rate": 0.25 under settings.replay.
SettingTypeDefaultMeaning
replay.sample_ratenumber, 0 to 10.1The share of sessions recorded from their start. 0 records only sessions where something goes wrong. 1 records every session.
replay.always_recordlist[]Persons and accounts whose sessions are always recorded. See below.
replay.blocked_routeslist of routes[]Routes where nothing is recorded. See Privacy and masking.
replay.mask_all_textbooleanfalseMasks every text in every recording.
snapshots.sample_ratenumber, 0 to 10.5The 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

Terminal
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:

JSON
{
  "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 signalWhat 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: falseIt 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.
untilWhen 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

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
Where limits come fromNowhere, 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 eventsIngest 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 replaysIngest 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 readUsage 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 reduceDo
Server tracesAdd noisy routes to ignoreRoutes in the Node SDK: health checks, polling endpoints.
Browser requestsAdd polling calls to ignoreRequests.
Errors you will never fixAdd them to ignoreErrors, or mark the problem as ignored.
Performance valuescapture: { vitals: false } in the browser SDK.
ReplaysLower replay.sample_rate. Sessions with trouble are still recorded.
Everything from a part of the appignoreRoutes.

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

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