Docs

How the analysis works

What triggers Sypnia's analysis of a problem, what it reads, the steps it takes, what it writes, what it never does, and how it shows that it does not know.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. When it runs
  2. What it reads
  3. The steps
  4. Collect
  5. Redact
  6. Ask
  7. Check
  8. Write
  9. What it writes
  10. Confidence
  11. What it never does
  12. When it does not know
  13. Weekly suggestions
  14. Turn it off

Engine Cloud This page is for anyone who wants to know what stands behind the sentence «3 people tried to pay today and could not». It is the same on Sypnia Cloud and on a self-hosted engine with a model configured. Without a model the agent is off and everything else in Sypnia still works.

When it runs

TriggerWhen exactly
A problem is newRight after the engine creates the problem, within 2 minutes of the first failure
A problem growsWhen it reaches twice the people it had at its last analysis, and when it is first seen in a newer release
A problem comes backWhen a resolved problem happens again
You askThe «Analyse again» button, or POST /v1/problems/{problem}/analyze. Useful after you upload source maps or register the release

It does not run for ignored problems, for projects that switched the agent off, or beyond the limits: at most 3 times a day for one problem.

What it reads

Everything the agent reads is collected by the engine with fixed rules, before any model is involved. It is exactly what GET /v1/problems/{problem}/context returns.

InputWhat it isWhere it comes from
The grouped failureThe error’s name and message, or the call that failed and howThe events of the problem
The stack, with source linesThe frames in your own files and a few lines of code around eachThe error’s stack, translated with the release’s source maps
BreadcrumbsWhat the person did before: pages opened, things clicked by their label, calls made. Up to 30The session of one occurrence
The traceThe failing request followed from the browser to the API to the calls behind itThe trace of that occurrence
The release and what changedThe version the failure was first seen in, when it went live, its commits, changed files and, if you send them, the diffsReleases
The impactHow many people, sessions and occurrences; how many tried again; when the same page last workedThe engine’s counts

Any of these can be missing. No source maps means a minified stack; no registered release means no «what changed». The agent works with what there is and its confidence drops accordingly.

The steps

  1. Collect

    The engine picks one occurrence to study: the latest one that has both a trace and a session. It builds the context above. No model yet.

  2. Redact

    The engine removes what must not leave, by rule: people become «person 1», «person 2»; ids, names and e-mails are dropped; labels of list rows and of free text are replaced by their kind («a row»); values that look like tokens or keys are cut out of messages and URLs. With SYPNIA_AI_SEND_SOURCE=false the source lines and diffs are dropped too. The exact list is on Models and what is sent.

  3. Ask

    One call to the model, with fixed instructions and the redacted context as JSON. The model must answer in a fixed JSON shape, and every claim about the cause must name the piece of context it rests on. The agent has no tools and makes no other request: it cannot browse, run code or read anything it was not given.

  4. Check

    The engine checks the answer against the context, by rule:

    • The place it blames must be a frame of the stack or a file the release changed.
    • Each piece of evidence must point at something that exists in the context.
    • Numbers are not taken from the model. «3 people», «today», «18:40» are filled in by the engine from its own counts.

    An answer that fails is asked for once more. If it fails again, the cause is dropped and the analysis becomes not_enough_evidence.

  5. Write

    The engine stores the analysis on the problem, builds the prompt from it with a fixed template, gives the problem its readable slug, and sends the problem.analyzed webhook.

What it writes

The analysis of a problem, in the API, the MCP server, the app and the Console:

FieldWhat it isExample
sentenceWhat happened, in one or two plain sentences«3 people tried to pay today and could not. The Pay button does nothing since yesterday’s change.»
whoWho it hit«3 people. Two of them tried again and gave up.»
doingWhat they were trying to do«Paying for an order, at the last step of checkout.»
sinceSince when, and whether it worked before«Yesterday’s change, deployed at 18:40. It worked before.»
cause.textThe likely cause«Release 4f2a91c renamed the cart’s total from cart.total to cart.totalCents. The checkout still reads cart.total…»
cause.evidenceOne to six facts, each pointing at something you can openrelease_change 4f2a91c:src/cart/cart.ts; stack_frame src/checkout/checkout.tsx:142
what_to_doThe change to make«Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.»
confidenceHow well the evidence supports the causehigh
The promptThe same, as a brief for a coding agentSee The prompt

Confidence

Confidence is set by rule from the evidence, not by how sure the model sounds.

LevelRule
highAt least two kinds of evidence agree, and one of them is a change in the release that touches the code where it fails
mediumThe cause is supported by the stack or the trace alone, with source lines
lowThe cause fits the facts and nothing confirms it: a minified stack, or no release information

On Sypnia Cloud a pull request is only offered for high and medium.

What it never does

  • It never sees replay recordings, page snapshots or screenshots. It reads events as text.
  • It never reads what a person typed. That is never collected.
  • It never receives anything inside a masked element, nor names, e-mails or ids of people.
  • It never reads your repository on a self-hosted engine. It sees only the source lines in your source maps and the diffs you chose to send. On Sypnia Cloud the repository is read only to write a pull request you asked for.
  • It never changes your code, never merges, never resolves or ignores a problem.
  • It never calls a model before you configure one, on a self-hosted engine.

When it does not know

A wrong cause, stated with confidence, costs more than no cause. So every way the analysis can fall short has its own status, shown as it is.

analysis.statusWhat happenedWhat you see
readyA cause was found and passed the checksThe full analysis
not_enough_evidenceThe agent could describe what happened and could not support a causeThe sentence, who, doing, since. In place of the cause: «Not enough evidence to name a cause», with what is missing (for example «no source maps for release 4f2a91c»)
pendingIt is runningThe technical title, and «analysing». Usually under a minute
failedThe model call failed or timed out three timesThe technical title, and «the analysis failed; it will be tried again when the problem grows»
limit_reachedThe project used its analyses for todayThe technical title, and when the count resets
offNo model is configured, or the project switched the agent offThe technical title. Nothing was sent anywhere

In every one of these the problem itself is complete: counts, sessions, replays, the trace and the stack are there, and the prompt still carries the evidence.

Weekly suggestions

Once a week, on Monday at 07:00 UTC, the agent looks at the week that ended and proposes improvements to performance and to how the app is used. See GET /v1/suggestions.

It works in two parts. First, fixed rules over the numbers, with no model: a page whose INP at the 75th percentile is above 500 ms, more than 3 rage clicks per 100 views, an API route above 2 % of failures, a form field people keep failing. These run on every engine. Second, one model call per page that has findings, to say in plain words what to change. That part needs a model and sends only counts, routes, selectors and stable labels: never people, sessions or ids.

Turn it off

WhereHow
One projectSet settings.agent.enabled to false: PATCH /v1/projects/{project_ref}, or the project’s settings in the app
A whole self-hosted engineSet SYPNIA_AI_PROVIDER=none, which is the default
Only the weekly model callsSYPNIA_AI_WEEKLY_SUGGESTIONS=false

With the agent off, problems keep their technical title, alerts carry that title, and nothing is sent to any model provider.

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