Docs

Event schema

Every event the SDKs send, field by field, with types, limits and an example of each, and the rules the engine applies to them.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The rules
  2. The batch
  3. Event types
  4. From the browser SDK
  5. From the server SDKs
  6. Fields of every event
  7. Fields of every event
  8. Fields of every browser event
  9. Fields of every server event
  10. session_start
  11. identify
  12. page_view
  13. page_leave
  14. click
  15. rage_click
  16. dead_click
  17. vital
  18. request
  19. error
  20. custom
  21. form_invalid
  22. replay_chunk
  23. replay_gap
  24. page_snapshot
  25. server_request
  26. server_error
  27. Shared shapes
  28. Person
  29. Account
  30. PersonRef
  31. AccountRef
  32. Span
  33. MaskPolicy
  34. Replay and snapshot uploads
  35. ReplayChunk
  36. PageSnapshot
  37. Limits and constants

This page is the event contract in a form you can read. It is for anyone who wants to know exactly what leaves an app, and for anyone who writes their own client. It is the same for the open-source engine and for Sypnia Cloud: the SDKs are MIT and identical for both.

It is generated from spec/events.schema.json in the docs repository, a JSON Schema (2020-12). When this page and the schema disagree, the schema is right. The SDKs build these events for you; see Browser, Node and Next.js. How a batch is sent, authenticated and answered is in the API reference.

The rules

RuleWhat it says
Versionv is the version of this contract. It is 1. Inside version 1 fields and event types are only added, never renamed or removed. An event without v is read as version 1.
Unknown fieldsA field this schema does not list is kept as it was sent and stored with the event. It is never a reason to reject an event. A newer SDK never breaks an older engine.
Unknown typesAn event whose type this schema does not list is stored with the raw events and ignored by the parts of the engine that do not know it. It is never rejected.
Long stringsA string longer than its limit is cut to the limit. It is never a reason to reject an event. The SDKs cut to the same limits before sending.
Wrong valuesA listed field with the wrong type, or a value outside its list of allowed values, is removed from the event (set to null when the field allows null). The event is kept.
Dropped eventsAn event is dropped only when a field marked as required for its type is missing or unusable (for example no type, a ts that is not a positive number, a browser event without sid, a vital outside its plausible range). Dropped events are counted in the answer of the ingest, with the reason. The rest of the batch is stored.
Stamped fieldsprj, rcv and bid are written by the engine when the event arrives. Whatever the sender puts there is replaced. env is production when the sender leaves it out.
PrivacyNo event carries a typed value, a request or response body, a cookie, a header, a query string or a URL hash. url is a path. Replay content travels apart from events, already masked in the browser.

The batch

The body of POST /v1/ingest/events. The ingest key travels outside the body: in the Authorization: Bearer spk_… header, or in the key query parameter when the browser sends with navigator.sendBeacon, which cannot set headers. The body may be gzipped.

FieldTypeLimitRequiredMeaning
batch_idstring64 charsAn id the sender chooses for this batch, a UUID. A retry reuses it: a batch that arrives twice is stored once.
sent_atstringWhen the batch left, by the sender’s clock, ISO 8601 in UTC. The engine compares it with its own clock to notice a device whose clock is wrong.
sdkobjectWhich SDK built the batch.
eventslist of event200 itemsyesThe events, in the order they happened. At most 200. An empty list is accepted and stores nothing.
FieldTypeLimitMeaning
sdk.namestring40 charsThe package name, for example @sypnia/browser.
sdk.versionstring20 charsThe package version, for example 1.0.0.
JSON
{
  "batch_id": "0b9f6c3e-2a41-4d7e-9c1b-6f2e8a4d7c10",
  "sent_at": "2026-03-12T10:31:48Z",
  "sdk": {
    "name": "@sypnia/browser",
    "version": "1.0.0"
  },
  "events": [
    {
      "v": 1,
      "type": "click",
      "ts": 1773311503000,
      "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
      "env": "production",
      "ver": "4f2a91c",
      "person": {
        "id": "u_1042"
      },
      "account": null,
      "url": "/checkout",
      "route": "/checkout",
      "dev": "desktop",
      "vw": 1440,
      "vh": 900,
      "lang": "en",
      "sel": "#pay-button",
      "tag": "button",
      "txt": "Pay $64.00",
      "crole": "button",
      "ctx": "Your order",
      "href": null,
      "x": 912,
      "y": 640,
      "rx": 0.633,
      "ry": 640,
      "ex": 820,
      "ey": 618,
      "ew": 184,
      "eh": 44
    }
  ]
}

Event types

From the browser SDK

TypeEventWhat it is
session_startSession startA session began in this browser.
identifyIdentifyThe app said who the person is. This is the only event that carries a name or an e-mail. Every other event carries only the ids.
page_viewPage viewA page was shown.
page_leavePage leaveThe person left a page, or stopped looking at it.
clickClickThe person clicked something.
rage_clickRage clickThe person clicked the same spot again and again.
dead_clickDead clickThe person clicked something that should respond, and nothing happened.
vitalVital (performance measurement)One Web Vital of a page, with the element behind it.
requestRequestThe page called an API. Never the request or response body.
errorErrorAn error in the page.
customCustom eventSomething the app chose to report.
form_invalidForm-validation failureThe browser blocked a form. Never what was typed.
replay_chunkReplay chunk markerA piece of the replay was uploaded. This marker is how a session’s timeline knows it has a replay, and where.
replay_gapReplay gap markerThe replay has a hole here. The player shows it instead of pretending nothing happened.
page_snapshotPage snapshot markerA snapshot of this route was taken. The snapshot itself travels apart, to POST /v1/ingest/snapshot.

From the server SDKs

TypeEventWhat it is
server_requestServer requestOne request your server received, with the calls it made. It is the root of the server’s part of a trace.
server_errorServer errorA failure on the server.

Fields of every event

Fields of every event

Carried by every event, from the browser and from the server.

FieldTypeLimitRequiredMeaning
vintegeralways 1Version of this contract. Always 1. Read as 1 when missing.
typestring40 charsyesWhich event this is. See the list of types.
tsnumber> 0yesWhen it happened: milliseconds since 1970-01-01 UTC, by the sender’s clock.
envstring40 charsThe environment, as the app set it in init. production when missing.
verstring or null40 charsThe release: the version of the app that sent the event, as set in init. Use the short git commit. Null or missing when the app reports none.
personPersonRef or nullWho the event belongs to: the id given to identify(). Null or missing for an anonymous event. Only identify events carry the name and e-mail.
accountAccountRef or nullThe account the person belongs to in the monitored app (a team, a company, a club): the id given to identify(). Null or missing when the app sends none.
prjstringThe project id (prj_…). Written by the engine from the ingest key. A value sent by the app is replaced.
rcvnumberWhen the engine received the event: milliseconds since 1970-01-01 UTC, by the engine’s clock. A value sent by the app is replaced.
bidstring64 charsThe id of the batch the event arrived in: the batch’s batch_id, or a hash of the batch’s body when the sender gave none. Written by the engine on every stored event. It is how a batch that arrives twice is counted once. A value sent by the app is replaced.

Fields of every browser event

Carried by every event the browser SDK sends, on top of the fields of every event.

FieldTypeLimitRequiredMeaning
sidstringexactly 32 hex charsyesSession id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (localStorage, key sypnia:session). A new one after 30 minutes without activity, or when another person is identified.
didstringexactly 32 hex charsDevice id: 32 random hex characters the SDK keeps in the browser’s storage (localStorage, key sypnia:device). It tells devices apart across sessions. It identifies nobody.
urlstring500 charsThe page’s path. Never the origin, the query or the hash.
routestring500 charsThe path with ids replaced by :id, so /orders/8841 and /orders/8842 are one route. A segment becomes :id when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains %.
devstringmobile, tablet, desktopDevice class by viewport width: mobile under 768 px, tablet under 1,024 px, otherwise desktop.
vwnumberViewport width in CSS pixels.
vhnumberViewport height in CSS pixels.
langstring or null16 charsThe page’s language: the lang attribute of <html>, else the browser’s language.

Fields of every server event

Carried by every event the server SDKs send, on top of the fields of every event. A server event has no device, viewport or page.

FieldTypeLimitRequiredMeaning
servicestring80 charsThe name of the service that sent the event, as set in init, for example shop-api.
tidstring or nullexactly 32 hex charsThe trace the event belongs to. Taken from the incoming traceparent header, or created by the SDK.
sidstring or nullexactly 32 hex charsThe browser session that made the request, from the x-sypnia-session header. Null when the request did not come from a browser session.
methodstring10 charsHTTP method of the incoming request, upper case.
pathstring500 charsPath of the incoming request. Never the query.
routestring500 charsThe path with ids replaced by :id, so /orders/8841 and /orders/8842 are one route. A segment becomes :id when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains %.

session_start

Session start. A session began in this browser.

Sent: Once for each session id a page uses: on the first event of a new session, after 30 minutes without activity, when another tab started a new session, or when another person is identified. It is queued before the event that caused it.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
uastring500 charsThe browser’s user agent string. The engine reads browser and operating system from it.
refstring or null500 charsWhere the person came from: origin and path of the referrer. Never its query or hash. Null when there is none.
swnumberScreen width in CSS pixels.
shnumberScreen height in CSS pixels.
tzstring64 charsThe browser’s time zone, as an IANA name.

Example

JSON
{
  "v": 1,
  "type": "session_start",
  "ts": 1773311476000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": null,
  "account": null,
  "url": "/cart",
  "route": "/cart",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
  "ref": "https://www.google.com/",
  "sw": 1728,
  "sh": 1117,
  "tz": "Europe/Madrid"
}

identify

Identify. The app said who the person is. This is the only event that carries a name or an e-mail. Every other event carries only the ids.

Sent: When the app calls identify() with a person, and once more at the start of each later session of that person. Not sent when the same person and account were already sent in this session with the same name and e-mail.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
personPersonyesA person as the app described them in identify(). Name and e-mail are personal data: they are stored only when the app sends them.
accountAccount or nullThe account the person belongs to, with its name if the app sent one.

Example

JSON
{
  "v": 1,
  "type": "identify",
  "ts": 1773311481000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "url": "/cart",
  "route": "/cart",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "person": {
    "id": "u_1042",
    "name": "Ada Park",
    "email": "ada@example.com"
  },
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  }
}

page_view

Page view. A page was shown.

Sent: When a page loads and each time the app navigates to another path. A change of query or hash alone is not a page view.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
navstringload, push, replace, traverseHow the person got here: load a full page load, push a navigation inside the app, replace a redirect inside the app, traverse back or forward.
fromstring or null500 charsThe route of the page before. Null on a full page load.

Example

JSON
{
  "v": 1,
  "type": "page_view",
  "ts": 1773311488000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "nav": "push",
  "from": "/cart"
}

page_leave

Page leave. The person left a page, or stopped looking at it.

Sent: When the app navigates away, the tab is hidden, or the page is closed. A page that is hidden and shown again can send several.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
durnumberMilliseconds on the page since it was shown, or since the tab became visible again.
scrollnumber0–100How far down the person scrolled, as a percentage of the page’s height. 100 when the whole page fits on the screen.

Example

JSON
{
  "v": 1,
  "type": "page_leave",
  "ts": 1773311518000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "dur": 30000,
  "scroll": 100
}

click

Click. The person clicked something.

Sent: On every click in the page. A click that a <label> passes on to its field counts once.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
selstring200 charsA CSS selector for the clicked control: at most 5 levels, stopping at a data-testid or a stable id. Never contains text.
tagstring20 charsThe control’s tag name, lower case.
txtstring or null80 charsThe control’s readable name: its accessible name, its label or its visible text. For a field, the label or the placeholder, never the value. Null when there is none, when the element is masked, or when maskAllText is on.
crolestringbutton, link, tab, menuitem, option, checkbox, radio, switch, select, input, textarea, row, cell, heading, image, icon, text, otherWhat kind of thing was clicked, as a person would name it. Missing when unknown.
ctxstring or null80 charsWhere the control is: the title of the open dialog or menu, else the nearest heading before it. Null when there is none or when text is masked.
hrefstring or null500 charsFor a link, the route it points to. Null for other controls and for mailto:, tel: and non-http links.
xnumberClick position from the left of the page, in pixels.
ynumberClick position from the top of the page, in pixels.
rxnumber0–1Click position from the left, as a fraction of the viewport width. Used by click maps.
rynumberClick position from the top of the page, in pixels. Used by click maps.
exnumberLeft edge of the clicked control, in page pixels.
eynumberTop edge of the clicked control, in page pixels.
ewnumberWidth of the clicked control, in pixels.
ehnumberHeight of the clicked control, in pixels.

Example

JSON
{
  "v": 1,
  "type": "click",
  "ts": 1773311503000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 912,
  "y": 640,
  "rx": 0.633,
  "ry": 640,
  "ex": 820,
  "ey": 618,
  "ew": 184,
  "eh": 44
}

rage_click

Rage click. The person clicked the same spot again and again.

Sent: Detected in the browser: 3 or more clicks within 30 px of the first, each at most 1,000 ms after the one before. Sent once, when the burst ends. Not for text fields, and not when the clicks selected text. It also starts the upload of the session’s replay.

Its own fields, on top of the common ones:

Every field of click, plus:

FieldTypeLimitRequiredMeaning
nintegermin 3yesHow many clicks the burst had. The other fields describe the last click.

Example

JSON
{
  "v": 1,
  "type": "rage_click",
  "ts": 1773311506000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 915,
  "y": 642,
  "rx": 0.635,
  "ry": 642,
  "ex": 820,
  "ey": 618,
  "ew": 184,
  "eh": 44,
  "n": 5
}

dead_click

Dead click. The person clicked something that should respond, and nothing happened.

Sent: Detected in the browser: a click on something that looks clickable, after which nothing happened for 1,000 ms: no change in the page, no request, no navigation, no scroll, no dialog, download or new tab. The same control again within 2,000 ms counts once. It also starts the upload of the session’s replay.

Its own fields, on top of the common ones:

Every field of click, plus:

FieldTypeLimitRequiredMeaning
nintegeralways 1000yesHow long the SDK waited for a response before calling the click dead, in milliseconds. Always 1,000.

Example

JSON
{
  "v": 1,
  "type": "dead_click",
  "ts": 1773311503000,
  "sid": "5b1d9e3f7a2c4e6081b3d5f7a9c1e3b5",
  "did": "9c4e2a6f8b0d1e3f5a7c9b1d3e5f7a90",
  "env": "production",
  "ver": "4f2a91c",
  "person": null,
  "account": null,
  "url": "/checkout",
  "route": "/checkout",
  "dev": "mobile",
  "vw": 390,
  "vh": 844,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 195,
  "y": 1210,
  "rx": 0.5,
  "ry": 1210,
  "ex": 16,
  "ey": 1188,
  "ew": 358,
  "eh": 48,
  "n": 1000
}

vital

Vital (performance measurement). One Web Vital of a page, with the element behind it.

Sent: LCP, FCP and TTFB once for the page that was loaded. INP and CLS once per page, when the person leaves it. A value that is not a finite number, is negative, or is above the plausible maximum (LCP, FCP, TTFB 120,000 ms; INP 60,000 ms; CLS 10) is not sent.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
namestringLCP, INP, CLS, TTFB, FCPyesWhich vital. FCP is stored with the raw events; the Performance views show LCP, INP, CLS and TTFB.
valuenumberyesThe value: milliseconds, rounded, for LCP, INP, TTFB and FCP. A score without unit, to 4 decimals, for CLS.
ratingstringgood, needs-improvement, poorThe rating by the Web Vitals thresholds: LCP 2,500 and 4,000 ms; INP 200 and 500 ms; CLS 0.1 and 0.25; TTFB 800 and 1,800 ms; FCP 1,800 and 3,000 ms.
selstring200 charsThe element behind the value, as a CSS selector: the largest element painted (LCP), the element the person interacted with (INP), the element that moved most (CLS). Never text. Missing for TTFB and FCP.
kindstringimage, text, pointer, keyboardFor LCP, whether the element is an image or text. For INP, whether the interaction was pointer or keyboard. Missing otherwise.

Example

JSON
{
  "v": 1,
  "type": "vital",
  "ts": 1773311489240,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "LCP",
  "value": 1240,
  "rating": "good",
  "sel": "#order-summary",
  "kind": "text"
}

request

Request. The page called an API. Never the request or response body.

Sent: When a fetch or XMLHttpRequest call from the page to your own origin, or to an address listed in traceTargets or recordTargets, gets an answer or fails. Not when the tab was hidden or the session idle as the call began, and not for a call your code aborted. A call that gets no answer is recorded 1,500 ms later with status 0, unless the page was being closed.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
methodstring10 charsyesHTTP method, upper case.
hoststring or null255 charsThe host that was called, when it is not the page’s own. Null or missing for calls to the page’s own origin.
pathstring500 charsyesThe route that was called: the path with ids replaced by :id. Never the query.
statusinteger0–599yesHTTP status of the answer. 0 when there was no answer.
durnumberMilliseconds from the call to the answer. ts is when the call began.
tidstringexactly 32 hex charsTrace id: 32 lowercase hex characters, a W3C trace id. Never all zeros.
codestring40 charsOnly for status 400 and above: the error code from a JSON answer (code, error_code, or error when it looks like a code).
msgstring160 charsOnly for status 400 and above: the start of the error message from a JSON answer (error, else message), with white space collapsed and e-mail addresses replaced by [email].

Example

JSON
{
  "v": 1,
  "type": "request",
  "ts": 1773311503100,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "method": "POST",
  "host": null,
  "path": "/api/checkout",
  "status": 400,
  "dur": 412,
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "code": "amount_required",
  "msg": "The payment has no amount."
}

error

Error. An error in the page.

Sent: When an error reaches the window uncaught, a promise is rejected with no handler, or the app calls reportError(). Not sent: errors of browser extensions and of scripts from other origins, Script error. without detail, the ResizeObserver loop notice, the same fingerprint again within 5,000 ms, and more than 20 errors in 60 seconds. It also starts the upload of the session’s replay.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
namestring100 charsyesThe error’s name, for example TypeError. UnhandledRejection when a promise was rejected with something that is not an Error.
msgstring500 charsyesThe error’s message, with e-mail addresses replaced by [email].
stackstring or null4000 charsThe stack as the browser wrote it, not parsed, with e-mail addresses replaced by [email]. Null when the browser gave none. The engine translates it with the release’s source maps.
digeststring or null100 charsAn id the framework gave the error, when there is one (Next.js gives a digest to errors thrown on the server). Null otherwise.
srcstringwindow, promise, boundary, manualHow the SDK learned of it: window an uncaught error, promise an unhandled rejection, boundary an error boundary of the framework, manual a call to reportError().
fpstringexactly 16 hex charsThe fingerprint: 16 hex characters computed by the SDK from the name, the message with its variable parts removed, and the first frame of the app’s own code. Errors with the same fingerprint are one problem.

Example

JSON
{
  "v": 1,
  "type": "error",
  "ts": 1773311507000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "ApiError",
  "msg": "POST /api/checkout failed with 400 (amount_required)",
  "stack": "ApiError: POST /api/checkout failed with 400 (amount_required)\n    at o (https://shop.example/assets/checkout-3f9c.js:1:48211)\n    at async HTMLButtonElement.<anonymous> (https://shop.example/assets/checkout-3f9c.js:1:49002)",
  "digest": null,
  "src": "promise",
  "fp": "1522805793228d19"
}

custom

Custom event. Something the app chose to report.

Sent: When the app calls track(name, props).

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
namestring80 charsyesThe event’s name, chosen by the app.
propsobject20 keysUp to 20 properties. A name has at most 40 characters. A value is a string of at most 200 characters, a finite number, a boolean or null. Anything else (objects, lists) is removed.

Example

JSON
{
  "v": 1,
  "type": "custom",
  "ts": 1773311495000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "coupon_applied",
  "props": {
    "code": "SPRING10",
    "discount_cents": 640,
    "first_order": false
  }
}

form_invalid

Form-validation failure. The browser blocked a form. Never what was typed.

Sent: When the browser refuses to submit a form because a field is not valid (the native invalid event). At most one per 1,000 ms.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
fieldstring or null80 charsThe field’s readable name: its label or placeholder. Never its value. Null when text is masked.
ctxstring or null80 charsWhere the field is: the dialog’s title or the nearest heading. Null when text is masked.
reasonstring or nullvalueMissing, typeMismatch, patternMismatch, tooShort, tooLong, rangeUnderflow, rangeOverflow, stepMismatch, badInput, customErrorWhy the browser refused the field: the first true key of its ValidityState.
selstring200 charsA CSS selector for the field.

Example

JSON
{
  "v": 1,
  "type": "form_invalid",
  "ts": 1773311499000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "field": "Postal code",
  "ctx": "Shipping address",
  "reason": "patternMismatch",
  "sel": "#postal-code"
}

replay_chunk

Replay chunk marker. A piece of the replay was uploaded. This marker is how a session’s timeline knows it has a replay, and where.

Sent: After the engine accepted one piece of the session’s recording. The recording itself travels apart, to POST /v1/ingest/replay.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
seqinteger0–719yesThe piece’s number in the session, from 0.
bytesintegerThe piece’s size before compression, in characters of JSON.
maskinteger1–9Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).
fullbooleanTrue when the piece holds a full copy of the page, so the player can start from it.

Example

JSON
{
  "v": 1,
  "type": "replay_chunk",
  "ts": 1773311507400,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "seq": 0,
  "bytes": 148220,
  "mask": 1,
  "full": true
}

replay_gap

Replay gap marker. The replay has a hole here. The player shows it instead of pretending nothing happened.

Sent: When a piece of the recording is lost for good.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
seqinteger0–719yesThe number of the piece that is missing.
reasonstringrejected, failed, overflow, limityesWhy: rejected the engine refused the piece, failed every retry failed, overflow too much was waiting in memory and the oldest piece was let go, limit the project reached its replays limit and the engine told the SDK to stop recording.
maskinteger1–9Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).

Example

JSON
{
  "v": 1,
  "type": "replay_gap",
  "ts": 1773311530000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "seq": 3,
  "reason": "failed",
  "mask": 1
}

page_snapshot

Page snapshot marker. A snapshot of this route was taken. The snapshot itself travels apart, to POST /v1/ingest/snapshot.

Sent: When a page snapshot (the picture behind a click map) was uploaded, or could not be.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
bytesintegerThe snapshot’s size before compression, in characters of JSON.
maskinteger1–9Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).
skippedstringtoo_big, upload_failed, limitPresent when the snapshot was not stored: too_big above 3,000,000 characters, upload_failed the upload failed (it is not retried), limit the project reached a limit.

Example

JSON
{
  "v": 1,
  "type": "page_snapshot",
  "ts": 1773311490600,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "bytes": 412880,
  "mask": 1
}

server_request

Server request. One request your server received, with the calls it made. It is the root of the server’s part of a trace.

Sent: Once for every request the server handled, when the answer has been sent. A request still running after 20,000 ms is sent at that moment as a partial record; the full record replaces it if the request finishes.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
tidstringexactly 32 hex charsyesTrace id: 32 lowercase hex characters, a W3C trace id. Never all zeros.
spanstringexactly 16 hex charsSpan id: 16 lowercase hex characters, a W3C span id.
parentstring or nullexactly 16 hex charsThe span id from the incoming traceparent header: the browser’s call, or the calling service’s span. Null when the trace starts here.
statusinteger or null100–599The HTTP status that was sent. Null when unknown, as in a partial record.
durnumberMilliseconds from receiving the request to the end of the answer.
spanslist of Span200 itemsThe calls the request made, in the order they began. At most 200 are kept.
span_nintegerHow many spans the request had, counting those beyond 200.
span_errintegerHow many of them failed.
db_nintegerHow many database calls (kind db) the request made.
db_msnumberMilliseconds spent in database calls, added up.
errstring or null500 charsThe message of the error that failed the request, when it threw. Null otherwise.
fpstring or nullexactly 16 hex charsThe fingerprint of that error, or of the timeout in a partial record. Null otherwise.
coldbooleanTrue for the first request of a new process (a cold start on serverless).
partialbooleanTrue only for the record written while the request was still running.
msgstring500 charsPartial records only: how long the request had been running and the three longest calls still in flight.

Example

JSON
{
  "v": 1,
  "type": "server_request",
  "ts": 1773311503130,
  "service": "shop-api",
  "env": "production",
  "ver": "4f2a91c",
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "span": "a1b2c3d4e5f60718",
  "parent": "0f1e2d3c4b5a6978",
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "method": "POST",
  "path": "/api/checkout",
  "route": "/api/checkout",
  "status": 400,
  "dur": 398.2,
  "spans": [
    {
      "id": "1a2b3c4d5e6f7081",
      "parent": null,
      "name": "SELECT carts",
      "kind": "db",
      "start": 6.1,
      "dur": 18,
      "status": "ok",
      "code": null,
      "attrs": {
        "db.system.name": "postgresql",
        "db.collection.name": "carts",
        "db.operation.name": "SELECT"
      }
    },
    {
      "id": "2b3c4d5e6f708192",
      "parent": null,
      "name": "SELECT cart_items",
      "kind": "db",
      "start": 25.3,
      "dur": 22.1,
      "status": "ok",
      "code": null,
      "attrs": {
        "db.system.name": "postgresql",
        "db.collection.name": "cart_items",
        "db.operation.name": "SELECT"
      }
    },
    {
      "id": "3c4d5e6f708192a3",
      "parent": null,
      "name": "POST /v1/payments",
      "kind": "http",
      "start": 49,
      "dur": 340.2,
      "status": "error",
      "code": "400",
      "attrs": {
        "http.request.method": "POST",
        "server.address": "payments.internal",
        "url.path": "/v1/payments",
        "http.response.status_code": 400
      }
    }
  ],
  "span_n": 3,
  "span_err": 1,
  "db_n": 2,
  "db_ms": 40.1,
  "err": null,
  "fp": null,
  "cold": false,
  "partial": false
}

server_error

Server error. A failure on the server.

Sent: When an error is thrown and not caught while handling a request, when a call the request made fails, when a request answers 500 or above with no other failure, when the code writes to console.error during a request, or when the app calls reportError(). At most 5 per request, 3 of them from console.error, one per fingerprint.

Its own fields, on top of the common ones:

FieldTypeLimitRequiredMeaning
namestring100 charsyesThe error’s name. For a failed call, the kind and its code, for example HTTP 400 or DB 23505. For a 5xx answer with no other failure, HTTP 500.
msgstring500 charsyesThe message. For a failed call it is redacted before it leaves the server: e-mail addresses, URLs, UUIDs, quoted values, long tokens and every run of digits are replaced, and it is followed by the call and the route, for example duplicate key value violates unique constraint (INSERT orders) in POST /api/checkout.
stackstring or null4000 charsThe stack, when there is an Error behind it. Null otherwise.
digeststring or null100 charsAn id the framework gave the error, when there is one. The browser’s error for the same failure carries the same digest.
srcstringuncaught, span, status, log, manualHow the SDK learned of it: uncaught an error nobody caught, span a call that failed, status an answer of 500 or above with no other failure, log a console.error during a request, manual a call to reportError().
spanstring or nullexactly 16 hex charsFor src span, the id of the span that failed.
fpstringexactly 16 hex charsThe fingerprint: 16 hex characters. Failures with the same fingerprint are one problem.

Example

JSON
{
  "v": 1,
  "type": "server_error",
  "ts": 1773311503519,
  "service": "shop-api",
  "env": "production",
  "ver": "4f2a91c",
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "method": "POST",
  "path": "/api/checkout",
  "route": "/api/checkout",
  "name": "HTTP 400",
  "msg": "amount is required (POST /v1/payments) in POST /api/checkout",
  "stack": null,
  "digest": null,
  "src": "span",
  "span": "3c4d5e6f708192a3",
  "fp": "88a44b15205cb153"
}

Shared shapes

Person

A person as the app described them in identify(). Name and e-mail are personal data: they are stored only when the app sends them.

FieldTypeLimitRequiredMeaning
idstring128 charsyesThe person’s id in the monitored app. An opaque string.
namestring or null120 charsThe person’s name. Optional. Personal data.
emailstring or null254 charsThe person’s e-mail address. Optional. Personal data.

Account

The account a person belongs to in the monitored app, as the app described it in identify().

FieldTypeLimitRequiredMeaning
idstring128 charsyesThe account’s id in the monitored app. An opaque string.
namestring or null120 charsThe account’s name. Optional.

PersonRef

Person (reference)

FieldTypeLimitRequiredMeaning
idstring128 charsyesThe person’s id in the monitored app. An opaque string: Sypnia never interprets it.

AccountRef

Account (reference)

FieldTypeLimitRequiredMeaning
idstring128 charsyesThe account’s id in the monitored app. An opaque string.

Span

One step inside a server request: a database call, a call to another service, or an internal step. The shape is compatible with OpenTelemetry.

FieldTypeLimitRequiredMeaning
idstringexactly 16 hex charsyesSpan id: 16 lowercase hex characters, a W3C span id.
parentstring or nullexactly 16 hex charsThe span that caused this one. Null when the request itself did.
namestring120 charsyesWhat the step is: SELECT carts, POST /v1/payments. Never a full SQL statement, never a query string.
kindstringdb, http, internalyesdb a database call, http a call to another service, internal anything else.
startnumberyesMilliseconds from the start of the request (ts) to the start of the span, to 0.1 ms.
durnumberyesHow long the span took, in milliseconds, to 0.1 ms. For a span still running in a partial record, how long it had been running.
statusstringok, errorerror when the call got no answer, answered 400, answered 500 or above, or threw. Other answers, such as 401, 404 or 409, are ok.
codestring or null40 charsThe HTTP status or the database’s error code, as text. 0 when there was no answer. Null when there is none.
attrsobject64 keysUp to 64 details, named as OpenTelemetry names them (http.request.method, server.address, db.system.name…). A value is a string of at most 256 characters, a number or a boolean. Attributes whose name contains authorization, cookie, password, secret or token are removed at ingest.
runbooleanTrue when the span was still running as the record was written. Only in partial records.

MaskPolicy

Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).

Replay and snapshot uploads

These two bodies are not events. They travel to their own endpoints and are counted as replays.

ReplayChunk

The body of POST /v1/ingest/replay: one piece of a session’s recording. Not an event. The engine stores events as sent and never looks inside: masking happens in the browser.

FieldTypeLimitRequiredMeaning
sidstringexactly 32 hex charsyesSession id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (localStorage, key sypnia:session). A new one after 30 minutes without activity, or when another person is identified.
seqinteger0–719yesThe piece’s number in the session, from 0. Sending the same number again replaces the piece.
ts_startnumberTime of the first recorded change in the piece, in milliseconds since 1970-01-01 UTC.
ts_endnumberTime of the last recorded change in the piece.
routestring500 charsThe path with ids replaced by :id, so /orders/8841 and /orders/8842 are one route. A segment becomes :id when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains %.
urlstring500 charsThe page’s path when the piece was opened.
vwnumberViewport width when the piece was opened.
vhnumberViewport height when the piece was opened.
fullbooleanTrue when the piece holds a full copy of the page.
maskinteger1–9Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).
eventslist of objectyesThe recorded changes, in the recorder’s own format (rrweb events). Opaque to the engine.
JSON
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "seq": 3,
  "ts_start": 1773311497000,
  "ts_end": 1773311507000,
  "route": "/checkout",
  "url": "/checkout",
  "vw": 1440,
  "vh": 900,
  "full": false,
  "mask": 1,
  "events": [
    {
      "type": 3,
      "timestamp": 1773311503000,
      "data": {
        "source": 2,
        "type": 2,
        "id": 418,
        "x": 912,
        "y": 640
      }
    }
  ]
}

PageSnapshot

The body of POST /v1/ingest/snapshot: one page as it looked, with the same masking as a replay. Click maps are drawn over it. Not an event.

FieldTypeLimitRequiredMeaning
sidstringexactly 32 hex charsyesSession id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (localStorage, key sypnia:session). A new one after 30 minutes without activity, or when another person is identified.
routestring500 charsyesThe path with ids replaced by :id, so /orders/8841 and /orders/8842 are one route. A segment becomes :id when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains %.
urlstring500 charsThe page’s path.
devstringmobile, tablet, desktopDevice class of the browser that took it.
vwnumberViewport width.
vhnumberViewport height.
phnumberFull height of the page, in pixels.
tsnumberWhen it was taken, in milliseconds since 1970-01-01 UTC.
maskinteger1–9Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 maskAllText (also every text of the page).
snapshotobjectyesThe page’s tree, in the recorder’s own format (an rrweb snapshot). Opaque to the engine.
JSON
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "route": "/checkout",
  "url": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "ph": 1630,
  "ts": 1773311490000,
  "mask": 1,
  "snapshot": {
    "type": 0,
    "childNodes": [],
    "id": 1
  }
}

Limits and constants

The numbers the SDKs and the engine use. They are part of the contract: the code implements these values.

AreaConstantValue
batchevents_per_batch200
batchbrowser_batch_chars40,800
batchbody_bytes_after_decompression2,097,152
batchflush_interval_ms10,000
batchflush_at_events50
batchqueue_max_events500
batchgzip_above_chars2048
batchretry_delays_ms1000, 4000, 15,000
sessionidle_ms1,800,000
sessionid_length_hex32
errorsper_minute20
errorsdedupe_ms5000
clicksrage_window_ms1000
clicksrage_radius_px30
clicksrage_min_clicks3
clicksdead_wait_ms1000
clicksdead_dedupe_ms2000
formsinvalid_dedupe_ms1000
requestsunanswered_grace_ms1500
vitalsmax_msLCP 120,000, FCP 120,000, TTFB 120,000, INP 60,000
vitalsmax_cls10
replaychunk_interval_ms10,000
replaychunk_chars200,000
replaybuffer_ms30,000
replaymax_chunks_per_session720
replayupload_bytes_after_decompression4,000,000
replaysnapshots_per_session5
replaysnapshot_chars3,000,000
serverspans_per_request200
serverspan_attributes64
serverspan_attribute_chars256
serverfailures_per_request5
serverlog_failures_per_request3
serverslow_request_ms20,000

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