Docs

How it works

The path from a click in your app to a sentence in your inbox, the parts involved, and how fresh each kind of information is.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The five steps
  2. 1. Your app reports what happens
  3. 2. Ingest receives and checks
  4. 3. Storage keeps raw data cheap
  5. 4. The engine turns events into answers
  6. 5. The agent writes the sentence, and you are told
  7. How fresh is each thing
  8. The same story, step by step
  9. Next

This page is for anyone who wants to know what Sypnia does with their app’s data before installing it. The path is the same in the open-source engine and in Sypnia Cloud, because the Cloud runs the same engine. The differences are at the two ends: who gets in, and how the result reaches you.

Figure. From your app to you and to your coding agent. Everything inside the box is the open-source engine.

The five steps

1. Your app reports what happens

You install an SDK, or point an OpenTelemetry exporter at Sypnia. From then on your app sends events: an error, a click, a page that loaded, a request to your API and how long it took. The browser SDK also records the session so it can be replayed, with typed input and sensitive fields masked before anything leaves the browser.

The browser SDK sends events in small batches, every 10 seconds or as soon as 50 are waiting, and when the page is hidden or closed. Your app identifies itself with an ingest key, which starts with spk_. It is public and can only write.

Read more: Events, What is collected.

2. Ingest receives and checks

Ingest is the door. It checks that the ingest key belongs to a project, that each event has a valid shape and size, and that the project is within its quota. Then it writes the events to storage, and only then answers: the answer waits up to 2 seconds, so that events from several browsers are written together as one object. It does no analysis, which keeps it cheap.

If ingest refuses something, it answers with the reason, and Sypnia counts what it refused so you can see it later. Nothing is dropped silently. See Plans and limits.

3. Storage keeps raw data cheap

Raw events, replay recordings, page snapshots and source maps go to an S3-compatible bucket. Results go to one Postgres database: hourly and daily numbers, the index of sessions, problems and configuration. Raw events never go into Postgres. No other service is required.

Every row and every object carries its project. Nothing is shared between projects.

4. The engine turns events into answers

The engine reads what arrived and does four things. It needs no other query service: it reads the raw objects itself.

  1. Groups failures into problems. Failures with the same cause become one problem, with the people it hit. This is the fast path: it reads what is new every 30 seconds and looks only for failures, so a new problem appears within 2 minutes of its first event.
  2. Puts each session together: its pages, clicks, errors and requests, in order, with its replay.
  3. Translates stack traces back to your source code, using the source maps you uploaded.
  4. Updates the numbers: page speed, API speed and failures, clicks, people and accounts. This slower pass, the roll-up, runs every 5 minutes. The numbers are complete within 10 minutes, and are then kept as hourly and daily totals so long periods stay cheap to read.

Processing the same data twice gives the same result, so a step that failed is run again without counting anything twice.

Read more: Problems, Performance, Releases and source maps.

5. The agent writes the sentence, and you are told

When a problem is new, comes back or grows, the agent reads it: the grouped failure, the stack with source lines, what the person did just before, the trace, the release and what changed, and how many people and sessions it hit. It writes one sentence in plain words, who it hit, since when, the likely cause with its evidence, what to do, a confidence level, and a prompt for your coding agent.

The agent never reads replay pixels or typed input, and never merges code. How the analysis works lists everything it reads and writes.

Then the problem reaches you and your coding agent:

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
You are toldThe alert is recorded, shown in the Console, available through the API and MCP, and sent to a webhook if you set one.An e-mail and an alert inside the app. Everything else waits for the daily summary e-mail.
You read itThe Console (problems list and replay viewer), the API, the CLI, or your coding agent through MCP.The full app, plus the API and the remote MCP server.
Your coding agent getsThe prompt and the MCP server.The prompt, the MCP server, and a pull request opened by the Sypnia GitHub App.
The model behind the agentYour own key, through OpenRouter or any OpenAI-compatible endpoint. Off until you set one.Included. Sypnia Cloud reaches models through OpenRouter.

Which model is used, and exactly what is sent to it, is in Models and what is sent. To send alert e-mails from your own engine, see Sending alert e-mails from a self-hosted engine.

How fresh is each thing

This table is a promise the engine must meet, on your own infrastructure and on Sypnia Cloud.

WhatWhen you see it
Ingest received your eventsWithin about 2 seconds of sending them. The answer comes once the events are written to storage, and says how many were stored.
A new problemWithin 2 minutes of its first event.
The alert for a new problemWithin the same 2 minutes. It carries the sentence in plain words if the agent has finished, and the technical title if not.
The sentence in plain wordsWhen the agent finishes, usually within the same 2 minutes. Never, if the agent is off.
Counts, performance numbers and the session listComplete within 10 minutes.
A replayWatchable once its session has been idle for 2 minutes, or has ended.
An uptime alertAfter two failed checks in a row. See Uptime.
The daily summary CloudOnce a day, in the morning, about the day before.

The same story, step by step

  1. A customer clicks Pay in your shop. The browser SDK records the click and the request POST /api/checkout, and passes a trace id to your API.
  2. Your API calls createPayment() without an amount, and the payment service answers 400. The server SDK records that call inside the same trace.
  3. The customer clicks Pay four more times. The browser SDK records a rage click, and starts uploading the replay, beginning 30 seconds before.
  4. Ingest stores all of it in the bucket.
  5. Within 2 minutes of the first failed payment, the engine opens one problem. When the second and third customers fail in the same call with the same answer, they join that problem instead of opening new ones. The engine notes that the first failure came after the release deployed yesterday at 18:40.
  6. The agent reads the problem and writes: «3 people tried to pay today and could not. The Pay button does nothing since yesterday’s change.»
  7. You get the alert, minutes after the first customer failed. Your coding agent gets the prompt and can read the problem through MCP. On Sypnia Cloud, the fix can also arrive as a pull request.

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