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.
On this page
- The rules
- The batch
- Event types
- From the browser SDK
- From the server SDKs
- Fields of every event
- Fields of every event
- Fields of every browser event
- Fields of every server event
- session_start
- identify
- page_view
- page_leave
- click
- rage_click
- dead_click
- vital
- request
- error
- custom
- form_invalid
- replay_chunk
- replay_gap
- page_snapshot
- server_request
- server_error
- Shared shapes
- Person
- Account
- PersonRef
- AccountRef
- Span
- MaskPolicy
- Replay and snapshot uploads
- ReplayChunk
- PageSnapshot
- 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
| Rule | What it says |
|---|---|
| Version | v 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 fields | A 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 types | An 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 strings | A 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 values | A 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 events | An 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 fields | prj, 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. |
| Privacy | No 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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
batch_id | string | 64 chars | An id the sender chooses for this batch, a UUID. A retry reuses it: a batch that arrives twice is stored once. | |
sent_at | string | When 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. | ||
sdk | object | Which SDK built the batch. | ||
events | list of event | 200 items | yes | The events, in the order they happened. At most 200. An empty list is accepted and stores nothing. |
| Field | Type | Limit | Meaning |
|---|---|---|---|
sdk.name | string | 40 chars | The package name, for example @sypnia/browser. |
sdk.version | string | 20 chars | The package version, for example 1.0.0. |
{
"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
| Type | Event | What it is |
|---|---|---|
session_start | Session start | A session began in this browser. |
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. |
page_view | Page view | A page was shown. |
page_leave | Page leave | The person left a page, or stopped looking at it. |
click | Click | The person clicked something. |
rage_click | Rage click | The person clicked the same spot again and again. |
dead_click | Dead click | The person clicked something that should respond, and nothing happened. |
vital | Vital (performance measurement) | One Web Vital of a page, with the element behind it. |
request | Request | The page called an API. Never the request or response body. |
error | Error | An error in the page. |
custom | Custom event | Something the app chose to report. |
form_invalid | Form-validation failure | The browser blocked a form. Never what was typed. |
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. |
replay_gap | Replay gap marker | The replay has a hole here. The player shows it instead of pretending nothing happened. |
page_snapshot | Page snapshot marker | A snapshot of this route was taken. The snapshot itself travels apart, to POST /v1/ingest/snapshot. |
From the server SDKs
| Type | Event | What it is |
|---|---|---|
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. |
server_error | Server error | A failure on the server. |
Fields of every event
Fields of every event
Carried by every event, from the browser and from the server.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
v | integer | always 1 | Version of this contract. Always 1. Read as 1 when missing. | |
type | string | 40 chars | yes | Which event this is. See the list of types. |
ts | number | > 0 | yes | When it happened: milliseconds since 1970-01-01 UTC, by the sender’s clock. |
env | string | 40 chars | The environment, as the app set it in init. production when missing. | |
ver | string or null | 40 chars | The 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. | |
person | PersonRef or null | Who 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. | ||
account | AccountRef or null | The 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. | ||
prj | string | The project id (prj_…). Written by the engine from the ingest key. A value sent by the app is replaced. | ||
rcv | number | When the engine received the event: milliseconds since 1970-01-01 UTC, by the engine’s clock. A value sent by the app is replaced. | ||
bid | string | 64 chars | The 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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
sid | string | exactly 32 hex chars | yes | Session 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. |
did | string | exactly 32 hex chars | Device 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. | |
url | string | 500 chars | The page’s path. Never the origin, the query or the hash. | |
route | string | 500 chars | The 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 %. | |
dev | string | mobile, tablet, desktop | Device class by viewport width: mobile under 768 px, tablet under 1,024 px, otherwise desktop. | |
vw | number | Viewport width in CSS pixels. | ||
vh | number | Viewport height in CSS pixels. | ||
lang | string or null | 16 chars | The 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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
service | string | 80 chars | The name of the service that sent the event, as set in init, for example shop-api. | |
tid | string or null | exactly 32 hex chars | The trace the event belongs to. Taken from the incoming traceparent header, or created by the SDK. | |
sid | string or null | exactly 32 hex chars | The browser session that made the request, from the x-sypnia-session header. Null when the request did not come from a browser session. | |
method | string | 10 chars | HTTP method of the incoming request, upper case. | |
path | string | 500 chars | Path of the incoming request. Never the query. | |
route | string | 500 chars | The 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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
ua | string | 500 chars | The browser’s user agent string. The engine reads browser and operating system from it. | |
ref | string or null | 500 chars | Where the person came from: origin and path of the referrer. Never its query or hash. Null when there is none. | |
sw | number | Screen width in CSS pixels. | ||
sh | number | Screen height in CSS pixels. | ||
tz | string | 64 chars | The browser’s time zone, as an IANA name. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
person | Person | yes | 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. | |
account | Account or null | The account the person belongs to, with its name if the app sent one. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
nav | string | load, push, replace, traverse | How 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. | |
from | string or null | 500 chars | The route of the page before. Null on a full page load. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
dur | number | Milliseconds on the page since it was shown, or since the tab became visible again. | ||
scroll | number | 0–100 | How far down the person scrolled, as a percentage of the page’s height. 100 when the whole page fits on the screen. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
sel | string | 200 chars | A CSS selector for the clicked control: at most 5 levels, stopping at a data-testid or a stable id. Never contains text. | |
tag | string | 20 chars | The control’s tag name, lower case. | |
txt | string or null | 80 chars | The 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. | |
crole | string | button, link, tab, menuitem, option, checkbox, radio, switch, select, input, textarea, row, cell, heading, image, icon, text, other | What kind of thing was clicked, as a person would name it. Missing when unknown. | |
ctx | string or null | 80 chars | Where 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. | |
href | string or null | 500 chars | For a link, the route it points to. Null for other controls and for mailto:, tel: and non-http links. | |
x | number | Click position from the left of the page, in pixels. | ||
y | number | Click position from the top of the page, in pixels. | ||
rx | number | 0–1 | Click position from the left, as a fraction of the viewport width. Used by click maps. | |
ry | number | Click position from the top of the page, in pixels. Used by click maps. | ||
ex | number | Left edge of the clicked control, in page pixels. | ||
ey | number | Top edge of the clicked control, in page pixels. | ||
ew | number | Width of the clicked control, in pixels. | ||
eh | number | Height of the clicked control, in pixels. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
n | integer | min 3 | yes | How many clicks the burst had. The other fields describe the last click. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
n | integer | always 1000 | yes | How long the SDK waited for a response before calling the click dead, in milliseconds. Always 1,000. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
name | string | LCP, INP, CLS, TTFB, FCP | yes | Which vital. FCP is stored with the raw events; the Performance views show LCP, INP, CLS and TTFB. |
value | number | yes | The value: milliseconds, rounded, for LCP, INP, TTFB and FCP. A score without unit, to 4 decimals, for CLS. | |
rating | string | good, needs-improvement, poor | The 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. | |
sel | string | 200 chars | The 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. | |
kind | string | image, text, pointer, keyboard | For LCP, whether the element is an image or text. For INP, whether the interaction was pointer or keyboard. Missing otherwise. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
method | string | 10 chars | yes | HTTP method, upper case. |
host | string or null | 255 chars | The host that was called, when it is not the page’s own. Null or missing for calls to the page’s own origin. | |
path | string | 500 chars | yes | The route that was called: the path with ids replaced by :id. Never the query. |
status | integer | 0–599 | yes | HTTP status of the answer. 0 when there was no answer. |
dur | number | Milliseconds from the call to the answer. ts is when the call began. | ||
tid | string | exactly 32 hex chars | Trace id: 32 lowercase hex characters, a W3C trace id. Never all zeros. | |
code | string | 40 chars | Only for status 400 and above: the error code from a JSON answer (code, error_code, or error when it looks like a code). | |
msg | string | 160 chars | Only 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
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
name | string | 100 chars | yes | The error’s name, for example TypeError. UnhandledRejection when a promise was rejected with something that is not an Error. |
msg | string | 500 chars | yes | The error’s message, with e-mail addresses replaced by [email]. |
stack | string or null | 4000 chars | The 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. | |
digest | string or null | 100 chars | An id the framework gave the error, when there is one (Next.js gives a digest to errors thrown on the server). Null otherwise. | |
src | string | window, promise, boundary, manual | How 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(). | |
fp | string | exactly 16 hex chars | The 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
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
name | string | 80 chars | yes | The event’s name, chosen by the app. |
props | object | 20 keys | Up 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
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
field | string or null | 80 chars | The field’s readable name: its label or placeholder. Never its value. Null when text is masked. | |
ctx | string or null | 80 chars | Where the field is: the dialog’s title or the nearest heading. Null when text is masked. | |
reason | string or null | valueMissing, typeMismatch, patternMismatch, tooShort, tooLong, rangeUnderflow, rangeOverflow, stepMismatch, badInput, customError | Why the browser refused the field: the first true key of its ValidityState. | |
sel | string | 200 chars | A CSS selector for the field. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
seq | integer | 0–719 | yes | The piece’s number in the session, from 0. |
bytes | integer | The piece’s size before compression, in characters of JSON. | ||
mask | integer | 1–9 | 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). | |
full | boolean | True when the piece holds a full copy of the page, so the player can start from it. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
seq | integer | 0–719 | yes | The number of the piece that is missing. |
reason | string | rejected, failed, overflow, limit | yes | Why: 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. |
mask | integer | 1–9 | 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). |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
bytes | integer | The snapshot’s size before compression, in characters of JSON. | ||
mask | integer | 1–9 | 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). | |
skipped | string | too_big, upload_failed, limit | Present 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
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
tid | string | exactly 32 hex chars | yes | Trace id: 32 lowercase hex characters, a W3C trace id. Never all zeros. |
span | string | exactly 16 hex chars | Span id: 16 lowercase hex characters, a W3C span id. | |
parent | string or null | exactly 16 hex chars | The span id from the incoming traceparent header: the browser’s call, or the calling service’s span. Null when the trace starts here. | |
status | integer or null | 100–599 | The HTTP status that was sent. Null when unknown, as in a partial record. | |
dur | number | Milliseconds from receiving the request to the end of the answer. | ||
spans | list of Span | 200 items | The calls the request made, in the order they began. At most 200 are kept. | |
span_n | integer | How many spans the request had, counting those beyond 200. | ||
span_err | integer | How many of them failed. | ||
db_n | integer | How many database calls (kind db) the request made. | ||
db_ms | number | Milliseconds spent in database calls, added up. | ||
err | string or null | 500 chars | The message of the error that failed the request, when it threw. Null otherwise. | |
fp | string or null | exactly 16 hex chars | The fingerprint of that error, or of the timeout in a partial record. Null otherwise. | |
cold | boolean | True for the first request of a new process (a cold start on serverless). | ||
partial | boolean | True only for the record written while the request was still running. | ||
msg | string | 500 chars | Partial records only: how long the request had been running and the three longest calls still in flight. |
Example
{
"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:
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
name | string | 100 chars | yes | The 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. |
msg | string | 500 chars | yes | The 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. |
stack | string or null | 4000 chars | The stack, when there is an Error behind it. Null otherwise. | |
digest | string or null | 100 chars | An id the framework gave the error, when there is one. The browser’s error for the same failure carries the same digest. | |
src | string | uncaught, span, status, log, manual | How 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(). | |
span | string or null | exactly 16 hex chars | For src span, the id of the span that failed. | |
fp | string | exactly 16 hex chars | The fingerprint: 16 hex characters. Failures with the same fingerprint are one problem. |
Example
{
"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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
id | string | 128 chars | yes | The person’s id in the monitored app. An opaque string. |
name | string or null | 120 chars | The person’s name. Optional. Personal data. | |
email | string or null | 254 chars | The 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().
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
id | string | 128 chars | yes | The account’s id in the monitored app. An opaque string. |
name | string or null | 120 chars | The account’s name. Optional. |
PersonRef
Person (reference)
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
id | string | 128 chars | yes | The person’s id in the monitored app. An opaque string: Sypnia never interprets it. |
AccountRef
Account (reference)
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
id | string | 128 chars | yes | The 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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
id | string | exactly 16 hex chars | yes | Span id: 16 lowercase hex characters, a W3C span id. |
parent | string or null | exactly 16 hex chars | The span that caused this one. Null when the request itself did. | |
name | string | 120 chars | yes | What the step is: SELECT carts, POST /v1/payments. Never a full SQL statement, never a query string. |
kind | string | db, http, internal | yes | db a database call, http a call to another service, internal anything else. |
start | number | yes | Milliseconds from the start of the request (ts) to the start of the span, to 0.1 ms. | |
dur | number | yes | How 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. | |
status | string | ok, error | error when the call got no answer, answered 400, answered 500 or above, or threw. Other answers, such as 401, 404 or 409, are ok. | |
code | string or null | 40 chars | The HTTP status or the database’s error code, as text. 0 when there was no answer. Null when there is none. | |
attrs | object | 64 keys | Up 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. | |
run | boolean | True 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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
sid | string | exactly 32 hex chars | yes | Session 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. |
seq | integer | 0–719 | yes | The piece’s number in the session, from 0. Sending the same number again replaces the piece. |
ts_start | number | Time of the first recorded change in the piece, in milliseconds since 1970-01-01 UTC. | ||
ts_end | number | Time of the last recorded change in the piece. | ||
route | string | 500 chars | The 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 %. | |
url | string | 500 chars | The page’s path when the piece was opened. | |
vw | number | Viewport width when the piece was opened. | ||
vh | number | Viewport height when the piece was opened. | ||
full | boolean | True when the piece holds a full copy of the page. | ||
mask | integer | 1–9 | 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). | |
events | list of object | yes | The recorded changes, in the recorder’s own format (rrweb events). Opaque to the engine. |
{
"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.
| Field | Type | Limit | Required | Meaning |
|---|---|---|---|---|
sid | string | exactly 32 hex chars | yes | Session 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. |
route | string | 500 chars | yes | The 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 %. |
url | string | 500 chars | The page’s path. | |
dev | string | mobile, tablet, desktop | Device class of the browser that took it. | |
vw | number | Viewport width. | ||
vh | number | Viewport height. | ||
ph | number | Full height of the page, in pixels. | ||
ts | number | When it was taken, in milliseconds since 1970-01-01 UTC. | ||
mask | integer | 1–9 | 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). | |
snapshot | object | yes | The page’s tree, in the recorder’s own format (an rrweb snapshot). Opaque to the engine. |
{
"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.
| Area | Constant | Value |
|---|---|---|
batch | events_per_batch | 200 |
batch | browser_batch_chars | 40,800 |
batch | body_bytes_after_decompression | 2,097,152 |
batch | flush_interval_ms | 10,000 |
batch | flush_at_events | 50 |
batch | queue_max_events | 500 |
batch | gzip_above_chars | 2048 |
batch | retry_delays_ms | 1000, 4000, 15,000 |
session | idle_ms | 1,800,000 |
session | id_length_hex | 32 |
errors | per_minute | 20 |
errors | dedupe_ms | 5000 |
clicks | rage_window_ms | 1000 |
clicks | rage_radius_px | 30 |
clicks | rage_min_clicks | 3 |
clicks | dead_wait_ms | 1000 |
clicks | dead_dedupe_ms | 2000 |
forms | invalid_dedupe_ms | 1000 |
requests | unanswered_grace_ms | 1500 |
vitals | max_ms | LCP 120,000, FCP 120,000, TTFB 120,000, INP 60,000 |
vitals | max_cls | 10 |
replay | chunk_interval_ms | 10,000 |
replay | chunk_chars | 200,000 |
replay | buffer_ms | 30,000 |
replay | max_chunks_per_session | 720 |
replay | upload_bytes_after_decompression | 4,000,000 |
replay | snapshots_per_session | 5 |
replay | snapshot_chars | 3,000,000 |
server | spans_per_request | 200 |
server | span_attributes | 64 |
server | span_attribute_chars | 256 |
server | failures_per_request | 5 |
server | log_failures_per_request | 3 |
server | slow_request_ms | 20,000 |