Docs

Sessions and replay

What starts and ends a session, who a session belongs to, which sessions are recorded, and exactly what a replay shows.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Session
  2. When a session starts
  3. When a session ends
  4. Who a session belongs to
  5. Sessions and your server
  6. What a session holds
  7. Replay
  8. Which sessions are recorded
  9. How a recording travels
  10. What a replay shows, and what it never shows
  11. Who can watch a replay
  12. When the replay limit is reached
  13. Example: one of the three sessions

This page is for anyone who wants to know what Sypnia records about a visit. Sessions and replay data work the same in the open-source engine and in Sypnia Cloud. The difference is the player: the engine’s Console has a replay viewer, and the Cloud app has the full player.

Session

A session is one visit by one person, from the first page to the last, with every event in between.

When a session starts

A session starts with the first activity when no session is alive in that browser. Activity is anything a person does:

  • a page view,
  • a click,
  • a key press, a scroll with the wheel, a touch,
  • the tab becoming visible again.

An error, or a custom event sent by your code, also starts a session if none is alive, so neither is lost.

When a session ends

A session ends after 30 minutes without activity in every tab. The next activity starts a new one.

Three rules follow from that:

  • Tabs share a session. Two tabs of your app in the same browser are one session.
  • Background work does not keep a session alive. Requests the page makes on a timer, performance measurements and replay uploads do not count as activity. A tab left open overnight is not a ten-hour session.
  • Another person is another session. If your app identifies a different person in the same browser, or says the person signed out with identify(null), the session ends and the next activity starts a new one. Identifying someone in an anonymous session does not: the session stays the same and becomes theirs.

There is no maximum length. A session lasts as long as the person stays active.

Who a session belongs to

Sessions are anonymous until your app says who the person is, with identify(). See Identifying people.

  • A person has an id that your app chooses. It is an opaque string to Sypnia. A name and an e-mail are stored only if your app sends them.
  • An account is optional: the team, company or club the person belongs to in your app. It has an id and, if your app sends it, a name.

Anonymous sessions are first-class: they are listed, counted and replayable like any other. When Sypnia says «3 people», it counts identified persons, plus one for each device whose sessions were never identified.

Sypnia also shows activity for each person and each account: how many sessions, which pages, and when they were last seen.

Sessions and your server

A session exists only where the browser SDK runs. When the page calls your API, the SDK sends the session’s id along, and the server’s part of that request joins the session’s timeline. A project that sends only server or OpenTelemetry data has problems, traces and performance numbers, and no sessions.

What a session holds

Start, end and durationFrom the first to the last event.
Person and accountIf identified.
DeviceDevice class, browser and operating system, language.
Release and environmentThe version of your app the person was using.
PagesThe routes visited, in order.
CountsPage views, clicks, rage clicks, dead clicks, errors and failed requests.
TroubleA session is marked as having trouble when it has at least one error, rage click, dead click or failed request.
TimelineEvery event of the session, in order.
ReplayWhether the session was recorded.

The session list is complete within 10 minutes of the events.

Replay

A replay is the recording of a session, played back as the person saw it.

Which sessions are recorded

Recording every session would be costly and is rarely needed. By default the browser SDK records:

  1. Every session where something goes wrong. The SDK keeps the last 30 seconds in the browser’s memory and uploads nothing. At the first error, rage click or dead click, it uploads those seconds and keeps recording from there. So the replay shows what led to the trouble.
  2. One in ten of the other sessions, from their start.
  3. Every session of a person or an account you chose to always record, for example a customer you are helping. Such a rule ends by itself: after 14 days unless you say otherwise, and after 90 days at most.

The engine decides once for each session, and the SDK asks for the decision when the session starts, so the answer is the same in every tab. You can change the share, add always-record rules, and switch recording off on any path of your app, all in the project’s settings, without shipping your app again. See Sampling and quotas.

How a recording travels

While recording, the SDK uploads a piece every 10 seconds, or sooner when a piece grows large. A session is recorded for at most 720 pieces, which is 2 hours of recording. After that the session goes on without being recorded.

A piece that cannot be uploaded is tried again. If it is lost for good, the recording keeps a marked gap and continues after it. The player shows the gap and says why.

A replay is watchable once its session has been idle for 2 minutes, or has ended.

What a replay shows, and what it never shows

On the pageIn the replay
TextAs shown, unless you mask it.
What a person typesAlways masked. Each character becomes an asterisk. There is no option to record typed text.
The content of password, card and one-time-code fieldsNever recorded, and impossible to unmask.
Anything you mark with data-sypnia-maskIts text is masked.
Anything you mark with data-sypnia-blockLeft out. A box of the same size takes its place.
Frames and videosLeft out, as a box of the same size.
Canvas drawingsNot recorded.
ImagesNot copied. The player loads them from their own address.
Clicks, scrolls, mouse movement, page changesRecorded.

Masking happens in the browser, before anything is sent. The full rules, including maskAllText to mask every text of every page, are in Masking.

Who can watch a replay

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
PlayerThe replay viewer in the Console.The full player in the app, with the moment it broke marked on the timeline.
Who can watchWhoever holds an API token with the replay scope.The members of your organization.
How many are keptAs many as your storage holds, for as long as you set.Up to your plan's replays a month, for as long as your plan keeps data.

Replay content is served as short-lived links. A token with only the read scope can see that a session has a replay and cannot fetch it.

The agent never reads replay pixels or typed input. It reads the session’s events: what was clicked, which requests failed, which error was thrown.

When the replay limit is reached Cloud

A plan includes a number of replays a month, for the whole organization. One replay is one session that has a recording, however long. When the limit is reached, the SDKs are told to stop recording until the month ends. Sessions are still listed with their full timeline, and each one that would have been recorded says so. See Plans and limits.

Example: one of the three sessions

One of the three customers who could not pay, as the session’s timeline shows it:

TimeWhat happened
0:12Opened checkout
0:27Clicked Pay
0:29Clicked Pay 4 more times (rage click)
0:31Payment rejected: no amount
0:42Left the page

The session was not in the one-in-ten share. It was recorded because of the rage click, reported when the burst ended at 0:31. The SDK had the last 30 seconds in memory, so the replay covers the visit almost from its start. What the customer typed in the card field is not in the recording: the field holds only asterisks.

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