Configure recording rules

Every sampled session records the basics: page views, Web Vitals, errors, failed requests and frustration signals. Recording rules decide which sessions record more:

Analyze: full activity, meaning every click and form action, successful requests, resource timings, console entries and long animation frames.
Replay: a session replay. A Replay rule also turns on Analyze.

This is the main cost control: capture every user lightly, and only the interesting sessions in full.

Manage rules in the dashboard on the application’s Recording rules page (Observe → RUM, then open the application), or through the API under /rum/{app_id}/rules. The SDK evaluates them in the browser; see rule evaluation.

The API examples on this page use an API key exported as SITEQWALITY_API_KEY and the application’s ID as APP_ID.

The rules a new application starts with

Name	Capture	Sample	Conditions	Gates
Errored sessions	Replay	100%	`error`	none
Sample	Replay	Auto	none (every session)	3 s minimum, one user interaction
Sample	Analyze	10%	none (every session)	none

Edit or delete these like any other rule.

How rules decide

A rule matches when all its conditions hold. A rule with no conditions matches every session.
Rules combine with any: one matching Replay rule records a replay, one matching rule of either kind records Analyze.
Sampling is per session and per rule, and deterministic: every tab and page load of a session gets the same answer. A rule at 10% matches in about one session in ten.
Gates delay upload, not the match. A sampled-in session uploads its replay only once it is min_duration_ms old and, with require_interaction, after the user clicked, tapped or pressed a key. Scrolling does not count. Bounces and bots then cost nothing. A rule with an error condition ignores both gates.

Every rule field, default and range is in the RUM reference. An application holds at most 50 rules, and a rule at most 20 conditions.

Conditions

`kind`	Fields	Holds when
`url`	`op` (`contains`, `starts_with`, `regex`), `value`	A page URL of the session matches.
`event`	`name`	`addAction` was called with this name.
`error`	optional `error_type`, `message_contains`, `unhandled_only`	The session sent an error. Filtered browser noise never counts.
`network_error`	`status_class` (`4xx`, `5xx`, `network`), optional `url_contains`	A request failed with that class.
`frustration`	`type` (`rage_click`, `dead_click`, `error_click`)	The user produced that signal.
`vital`	`metric` (`lcp`, `inp`, `cls`), `gt`	The final value exceeds `gt`: milliseconds for LCP and INP (up to 600,000), unitless for CLS (up to 10).
`identified`	none	`setUser` was called with an id.
`attribute`	`key`, `value`	A global attribute or user trait equals the value.
`device`	`class` (`desktop`, `mobile`)	The device class. Tablets count as mobile.
`release`	`op` (`eq`, `starts_with`), `value`	The `version` passed to `init`.
`env`	`value`	The `env` passed to `init`.

Text values are trimmed and hold up to 256 characters.

A url regex must mean the same in the browser and on the server, so it is limited to the syntax both share: groups other than (?:, backreferences, \A, \z, \p{…} and [[:class:]] are refused. So are nested repeats such as (a+)+ or (a?)+, which can freeze a page.

Auto sampling

An Auto rule’s rate is recomputed every hour so that replays spread over the billing period within your replay quota, after what errored sessions are expected to use. Errored sessions always win over sampled ones; when they alone would use more than the budget, the error rules are slowed too, so errored sessions are spread over the period.

The budget is shared across your applications by their traffic. An application with replay_monthly_target set (see PATCH /rum/{app_id}) takes what keeps it on that target first. The rate never goes above the rule’s sample_rate or below 0.01%, and a new Auto rule records at 0.01% until its first hourly run. The rate in force is the rule’s effective_sample_rate.

Estimate a rule before saving

In the dashboard, the rule builder shows this estimate when you click Preview rule, which it requires before Save rule. Through the API, POST /rum/{app_id}/rules/preview takes a rule body (name optional) and estimates what it would record from the last 7 days of sessions. Read access is enough.

curl -X POST "https://api.siteqwality.com/rum/$APP_ID/rules/preview" \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capture": "replay", "sample_rate": 0.5,
        "conditions": [{ "kind": "url", "op": "starts_with", "value": "/checkout" }] }'

{
  "data": {
    "window_days": 7,
    "sessions_in_window": 41200,
    "matching_sessions_in_window": 3100,
    "sample_rate": 0.5,
    "estimated_sessions_per_month": 6643,
    "quota_product": "session_replay",
    "monthly_quota": 10000,
    "quota_share": 0.6643,
    "approximate": false,
    "not_evaluated": []
  }
}

The estimate is the matching sessions times the sample rate, scaled to 30 days; an Auto rule uses its current Auto rate. Conditions the stored sessions cannot answer (event, and url_contains on network_error) count as matching and are listed in not_evaluated, with approximate: true. So is require_interaction when no session recorded activity.

Examples

Each example is a rule you can build in the dashboard. Open the application’s Recording rules page and click New recording rule. Give it a Rule name, choose Replay or Analyze under What to capture, add conditions under Sessions to match, set the Sample rate, then click Preview rule and Save rule. The API calls below create the same rules.

Replay sessions that reach checkout, half of them

In the builder: Replay, a Page URL condition that starts with /checkout, and a Sample rate of 50%.

curl -X POST "https://api.siteqwality.com/rum/$APP_ID/rules" \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout",
    "capture": "replay",
    "sample_rate": 0.5,
    "conditions": [{ "kind": "url", "op": "starts_with", "value": "/checkout" }]
  }'

Analyze every session with a failed API call

In the builder: Analyze, and a Failed request condition for Server error (5xx) with /api/ in the request URL.

curl -X POST "https://api.siteqwality.com/rum/$APP_ID/rules" \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API 5xx",
    "capture": "analyze",
    "conditions": [{ "kind": "network_error", "status_class": "5xx", "url_contains": "/api/" }]
  }'

Pause a rule, then delete it

In the dashboard, turn off the rule’s Enabled switch to pause it, and choose Delete from its actions menu, then Delete rule, to remove it.

Through the API, PUT /rum/{app_id}/rules/{rule_id} changes only the fields you send, and validates the result as a whole. Set RULE_ID to the rule’s id, returned when it is created and by GET /rum/{app_id}/rules:

curl -X PUT "https://api.siteqwality.com/rum/$APP_ID/rules/$RULE_ID" \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

curl -X DELETE "https://api.siteqwality.com/rum/$APP_ID/rules/$RULE_ID" \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY"

Changing a rule’s capture, Auto or conditions clears its effective rate until the next hourly run.

When changes apply

The SDK picks up a rule change on new page loads within 6 minutes; see how long changes take. Rule changes are recorded in the audit log.