Docs

Your first problem

Break something on purpose and follow it through Sypnia, from the failure to the session, the replay, the sentence and the fix.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Add a button that fails
  2. Click it three times, fast
  3. Wait two minutes
  4. Open the problem
  5. Watch what happened
  6. Hand it to your coding agent
  7. Remove the button and resolve the problem
  8. What you just saw, with a real problem
  9. Next

This page is for anyone who has finished a quickstart and wants to see the whole loop once, with a failure they control. It works on Sypnia Cloud and on a self-hosted engine; the steps that differ are marked.

At the end you will have: one problem in Sypnia that you caused yourself, the session where it happened, its replay, and the prompt that hands the fix to your coding agent.

Before you start: Sypnia must already receive events from your app. If it does not, do one of the quickstarts first: Sypnia Cloud or self-host.

  1. Add a button that fails

    Add a button to any page of your app. When clicked, it throws an error, the way the shop’s checkout would if the cart’s total were missing.

    HTML

    any-page.html
    <button id="sypnia-test">Test Sypnia</button>
    <script>
      document.getElementById('sypnia-test').addEventListener('click', () => {
        throw new Error('Sypnia test: the cart total is missing');
      });
    </script>

    You do not need to call Sypnia in this code. The browser SDK reports errors that nobody caught on its own.

    You should see
    A button «Test Sypnia» on the page. Clicking it shows nothing on screen, and an error in the browser’s console.
  2. Click it three times, fast

    Open the page and click the button three times within one second. Then stay on the page for about 15 seconds, so the browser SDK has time to send what it recorded.

    Three things happened, and Sypnia saw each of them:

    • An error. You caused it three times, but the SDK counts the same error once within 5 seconds, so Sypnia records one occurrence.
    • A rage click: three clicks or more on the same spot within one second.
    • A dead click: a click on a button after which nothing changed on the page.

    Because the session had an error, the SDK also started uploading its replay, beginning 30 to 60 seconds before the first error, or at the start of the session if it is younger than that.

    You should see
    In the Network tab of your browser’s developer tools, requests to your ingest address that are answered with a success status.
  3. Wait two minutes

    A new problem appears within 2 minutes of its first event. The session list is complete within 10 minutes, and a replay is watchable once its session has been idle for 2 minutes or has ended. So leave the page alone for a moment.

    You should see
    After 2 minutes, a new problem in the development environment. A little later, your session in the sessions list, marked as having an error, a rage click and a replay.
  4. Open the problem

    Open the problems list and choose the development environment. On Sypnia Cloud that is the app at app.sypnia.com. On a self-hosted engine it is the Console, or the API, the CLI or your coding agent through MCP.

    There is one new problem. Before the agent has analysed it, or if the agent is off, its title is the technical one:

    Text
    Error: Sypnia test: the cart total is missing

    Once the agent has run, the title is a sentence in plain words, such as «Clicking Test Sypnia fails every time: the page throws a test error.» Under it you find:

    • Who it hit: 1 person, 1 session.
    • Since when: the time of your first click, and the release if your app reports one.
    • Where: the file and line of the throw, in your own source code if you uploaded source maps. Without them you see the built file and its line. See Releases and source maps.
    • The sessions where it happened.

    Click the button again tomorrow and the problem’s count goes up; no second problem appears. Problems explains what makes two failures the same problem.

    You should see
    One problem, marked «new», with 1 person and 1 occurrence.
  5. Watch what happened

    Open the session from the problem. The timeline lists what you did: the page you opened, the three clicks, the rage click, the dead click and the error. The replay starts shortly before the first error and shows the page as you saw it.

    You should see
    The replay plays your three clicks, with the moment of the error marked.
  6. Hand it to your coding agent

    Every problem comes ready for your coding agent.

    • The prompt. Copy it from the problem and paste it into your coding agent. It says what happens, where, why, what to do and how to check the fix. See The prompt.
    • MCP. If your coding agent is connected to Sypnia, ask it «what is failing in my development environment?». See Connect.
    • A pull request. Cloud If you installed the Sypnia GitHub App, Sypnia can open a pull request with the change and a test. See Pull requests.

    For this test the fix is to delete the button.

    You should see
    Your coding agent proposes removing the throw, or the test button.
  7. Remove the button and resolve the problem

    Delete the test button from your app. Then mark the problem as resolved.

    If the same error ever happens again, Sypnia opens the problem again and marks it «came back».

    You should see
    The problem leaves the open list and shows as resolved.

What you just saw, with a real problem

In the shop’s story the path is the same, with real customers. Three people click Pay, the payment is rejected because the checkout still reads cart.total, and Sypnia tells you:

3 people tried to pay today and could not. The Pay button does nothing since yesterday’s change.

The difference is that you did not have to be there, and that in production Sypnia sends you an alert.

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