Learn
Remote SDK Config (Beta)
Settings reference

Settings reference (Beta)

⚠️
Beta. The 2.x browser SDK, with remote SDK config (OpAMP), the on-device ring buffer and triggers, is in beta. Install it with the beta tag: npm install @tracewayapp/frontend@beta (or react@beta, vue@beta, svelte@beta, jquery@beta). A plain npm install still installs the stable 1.x SDK, which does not poll for remote settings. Options, defaults and the settings document can change before 2.0 is stable.

Every field of the settings document a rule can set, the attributes rules can target, the trigger language, and the protocol and API behind them. For what these do together, see Remote SDK Config; for a walkthrough, Set up remote config.

The settings document

A rule stores a partial document: only what it changes. The server merges the matching rules in order and sends the browser that overlay; the SDK lays it over its built-in defaults. Unknown fields are rejected when you save a rule (422), and the browser ignores fields it does not know, so a newer server can add settings without breaking older SDKs.

{
  "schemaVersion": 1,
  "enabled": true,
  "signals": {
    "errors":   { "mode": "stream", "sampleRate": 1 },
    "network":  { "mode": "buffer", "sampleRate": 0.5 },
    "console":  { "mode": "buffer", "minSeverity": "warn" }
  },
  "sessions": { "enabled": true, "baselineSampleRate": 0 },
  "replay":   { "mode": "buffer", "sessionSampleRate": 1, "maskAllInputs": true },
  "buffer":   { "maxBytes": 2097152, "maxAgeSeconds": 600, "replayMaxBytes": 8388608, "persist": true },
  "triggers": [ { "id": "default-exception", "enabled": true } ]
}
FieldTypeMeaning
schemaVersion1Defaults to 1 when omitted
enabledbooleanfalse is the kill switch: the SDK sends nothing, captures included
signalsobjectOne entry per signal, see below
sessions.enabledbooleanSession start and end events
sessions.baselineSampleRate0 to 1Stable healthy-session breadcrumb/request sample; default 0. Does not stream replay or override off signals
replayobjectSee Replay
bufferobjectSee Buffer
triggersarraySee Triggers
captures, limitsWritten by the server only; a rule that contains them is rejected

Signals

errors, messages, network, console, navigation, userActions, webVitals, resourceTiming, custom, each with:

FieldValuesMeaning
modeoff, buffer, streamWhat happens to a record of this signal
sampleRate0 to 1Share of records kept; the rest are dropped before the mode applies
minSeveritytrace, debug, info, warn, error, fatalConsole only: lines below it are dropped

Replay

FieldValuesMeaning
modeoff, buffer, streamBuffered segments upload with a trigger's flush or a capture; streamed ones as they complete
sessionSampleRate0 to 1Share of sessions that may stream replay, decided per session id, so a session is all or nothing
maskAllInputsbooleanMask every input field in the recording (default true)

Buffer

FieldDefaultLimitsMeaning
maxBytes2 MiB1 B to 64 MiBSize of the on-device buffer for log records and spans
maxAgeSeconds6001 to 86400Records older than this are dropped from the buffer
replayMaxBytes8 MiB1 B to 64 MiBSize of the buffered replay segments
persisttrueKeep telemetry in IndexedDB, with a sessionStorage navigation checkpoint; does not persist rrweb replay

Persistence is best effort when browser storage is unavailable or full. Restored and new telemetry share maxBytes and maxAgeSeconds; the byte budget accounts for complete serialized records. The SDK checkpoints after activity, on hidden/pagehide, and on flush(). IndexedDB writes alone may not finish during unload, so the current tab also keeps a synchronous sessionStorage checkpoint. Replay stays in memory and does not survive a full page navigation.

Failed OTLP batches retry in the current page with increasing delays, on online, on visibility changes, and after startup. The outbox prunes batches after 8 attempts or 24 hours and keeps the newest 200 on a drain. buffer.persist: false stops durable retries and removes stored telemetry and navigation checkpoints for this project token. It does not disable collection or the configuration cache.

Changing input masking restarts rrweb and discards incompatible buffered or queued replay. Newly restricted signals are purged from the ring and checked again before queued and persisted exports. Requests already in flight cannot be recalled.

Defaults

What the 2.x SDK does with no rules.

SignalDefaultWith recordAllSessions: true
errors, messagesstreamstream
network, console, navigation, userActions, custombufferstream
webVitalsstreamstream
resourceTimingoffoff
replaybufferstream
sessionsonon

Production defaults keep session lifecycle metadata and web vitals on, with healthy breadcrumbs and replay buffered locally. An accepted exception uploads up to 10 minutes of buffered breadcrumbs and a 30-second replay clip; no full-session replay is uploaded by default. Error clips have a 5-second cooldown and a limit of 20 per session.

Errors are not sampled by default. Duplicate exceptions (same type, message and stack) within 1 second are suppressed, and each running client accepts at most 60 errors in a rolling minute. The next accepted error carries the aggregate traceway.error.suppressed_count. Configure errorLimits: { maxPerMinute: 60, duplicateWindowMs: 1000 } to tune these limits; they reset when the SDK is recreated.

For an optional stable sample of healthy-session breadcrumbs and request spans, use baselineSampleRate: 0.01 (1%). The default is 0. Selection uses the session ID and persists across page reloads within that session. It does not enable replay or override explicitly disabled signals, signal filters, or exporter limits. Web vitals remain enabled independently, so performance diagnosis is not restricted to sessions with errors.

Set sessions.baselineSampleRate: 0.01 in a rule (or use Use 1% baseline in the rule editor) to enable that sample remotely. Targeted captures remain separate: duration is limited to 24 hours, lookback to 24 hours of locally retained data, and each project can have at most 20 active captures. Local buffers default to 2 MiB of telemetry and 8 MiB of replay; collection also respects developer ceilings and plan limits. These bounds are not a total upload-byte budget.

Console's minSeverity defaults to info. One trigger is built in:

{ "id": "default-exception", "name": "Error clip", "maxPerSession": 20, "cooldownSeconds": 5,
  "steps": [{ "match": { "key": "event.name", "op": "eq", "value": "exception" } }],
  "actions": [{ "type": "flush", "lookbackSeconds": 600, "signals": ["*"], "replay": false }, { "type": "flush", "lookbackSeconds": 30, "signals": [], "replay": true }] }

A rule can change it by id, or turn it off with { "id": "default-exception", "enabled": false }.

Triggers

FieldValuesMeaning
id1-64 of A-Z a-z 0-9 . _ -Rules merge triggers by id: a later rule with the same id replaces fields of an earlier one
nametextShown in the dashboard and on traceway.trigger.fired
enabledbooleanfalse removes the trigger
sampleRate0 to 1Share of completed matches that fire
cooldownSeconds0 to 86400Minimum time between two fires in a session
maxPerSession≥ 0Fires allowed per session
steps1 to 5Matched in order
actions1 to 5Run when the last step matches

A trigger with neither steps nor actions only patches the fields it sets on a trigger an earlier rule or the SDK defined. Steps and actions always come together.

Steps

FieldValuesMeaning
matchmatcherRequired
withinSeconds1 to 86400Time allowed since the previous step; a later match starts the trigger over
count1 to 1000Matching records the step needs
periodSeconds1 to 86400Sliding window for count; needs count

Matchers

A matcher is a condition, { "key": "...", "op": "...", "value": ... } (or "values": [...] for in and not_in), or exactly one of { "all": [matchers] }, { "any": [matchers] } and { "not": matcher }. A step's matcher may nest 8 levels and hold 50 conditions; values are strings, numbers or booleans, at most 256 characters, and at most 100 per condition.

Keys a step can test:

KeyOnValue
event.namelogsThe event name: exception, traceway.message, browser.console, browser.navigation, browser.user_action.click, browser.web_vital, or a track() name
signallogs, spanserrors, messages, console, navigation, userActions, webVitals, resourceTiming, custom; network for spans
severitylogsSeverity number: 1 trace, 5 debug, 9 info, 13 warn, 17 error, 21 fatal
severity.textlogsSeverity text as recorded
bodylogsThe log body, for example the console line
span.name, span.kind, span.statusspansKind internal, server, client, producer, consumer; status unset, ok, error
duration_msspansSpan duration in milliseconds
attributes.<key>logs, spansAn attribute of the record, e.g. attributes.http.response.status_code
resource.<key>logs, spansA resource attribute, e.g. resource.service.version
global.<key>logs, spansA global attribute the app set, e.g. global.user.id
session.idlogs, spansThe current session

Operators, also used by targeting conditions:

OperatorMatches when the value
eq, neqequals, or does not equal, value (numbers compare as numbers)
in, not_inis, or is not, one of values
contains, icontainscontains value, case-sensitive or not
starts_withstarts with value
globmatches value with * (any run) and ? (one character), ignoring case
exists, not_existsis set and not empty, or is not
gt, gte, lt, ltecompares as a number; in targeting conditions value must be a number (a numeric string is saved as the number)
versionsatisfies a version range such as >=2.4 <3: comparators separated by spaces or commas, dotted numbers compared part by part, so 1.10 > 1.9

Text operators look at the first 4 KB of a value. There is no regular expression operator; glob runs in linear time.

Actions

typeFieldsWhat it does
flushlookbackSeconds (required), signals, replayUploads the buffered records of the last lookbackSeconds for the listed signals, and the replay clip when replay is true
streamdurationSeconds (required), signals, replayStreams the listed signals for a while, on this page. "*" covers the signals that are buffered; a signal named explicitly is turned on even if it is off
startReplaydurationSeconds (required)Streams replay for a while
emiteventName (required, ≤ 128 characters), attributesRecords an event you can search, or trigger on
capturedurationSeconds (required), lookbackSeconds (default 60), signals, replayStarts a capture on this device. See below

signals lists signal names or "*" (the default when omitted). An explicit [] selects no telemetry signals; replay is controlled separately. Durations are at most 86400 seconds.

A capture action uploads its lookback, sends the record that fired it, and streams for durationSeconds. Its "*" also brings back signals a rule switched off: every signal the defaults collect; resourceTiming only if named. It is stored in localStorage (traceway:local-captures:<token>), so later pages keep streaming until it ends; the same trigger firing again extends it instead of uploading again. Each start emits traceway.capture.started with traceway.capture.source: trigger.

Targeting

A rule's conditions are checked against the attributes the browser sends with every poll:

AttributeSource
service.name, service.version, deployment.environment.nameserviceName, version, environment in init()
service.instance.idA UUID per browser profile and project token, kept in localStorage; getInstanceId() returns it
browser.name, browser.version, browser.language, browser.mobile, browser.platform, os.name, user_agent.originalDetected from the browser
session.idThe current session
user.id, tenant.id, ...Global attributes from setAttribute and the attributes option, up to 64

The server reads up to 128 attributes per poll, identifying ones first, and ignores a value over 1024 bytes. An array attribute is matched as the JSON text of its string, number and boolean items.

{
  "all": [
    { "key": "service.version", "op": "version", "value": ">=2.4 <2.5" },
    { "key": "deployment.environment.name", "op": "eq", "value": "production" }
  ],
  "rollout": { "percent": 25 }
}

All conditions must hold; no conditions match every client. A rule has at most 20. rollout.percent (0 to 100) keeps the rule to a share of the matching clients. The bucket is a hash of the rule id and the browser's instance id, so a client stays in or out while the percentage only grows, and different rules pick different clients. rollout.by buckets by another attribute instead, for example "by": "user.id" to keep all of a user's browsers together; a client without that attribute is out.

Captures from the dashboard

The New Capture dialog in the Data Collection tab: a Target kind and its Value, For (how long the capture lasts), Include (how much of what the device holds to upload first) and a Record session replay checkbox
FieldIn the dialogValues
TargetTarget, ValueA device (service.instance.id), a user (user.id), a session (session.id), or any attribute and value
DurationFor1 minute to 24 hours (the dialog offers 15 minutes, 1 hour, 4 hours and 24 hours)
LookbackInclude0 to 86400 seconds, default 600 (the dialog offers nothing earlier, the last minute, the last 10 minutes and the last hour)
ReplayRecord session replayOn by default

At most 20 captures are active per project. A capture reaches the browsers it matches in their settings document; each tab runs its lookback upload once, even across pages, and streams until the capture ends, with the same rules as the capture action. A browser under a capture polls every 60 seconds. Expired captures drop out of the document by themselves. Cancellation takes effect when the next successful poll removes the capture; the SDK immediately removes that capture’s streaming override. Other active captures or stream rules still apply. A zero lookback requests no earlier telemetry.

Plan limits

When the organization's plan does not include exceptions, replay or other data, the server switches those signals off in every document and adds them to limits:

{ "limits": { "signals": { "errors": "off", "messages": "off" }, "replay": "off" } }

The SDK treats limits like its init() ceilings: no rule, trigger or capture turns those signals back on, so browsers stop sending data that would be dropped on arrival.

Events the SDK reports

These stream unless the kill switch is on; session events additionally respect sessions.enabled:

EventAttributes
traceway.config.appliedtraceway.config.hash: the hash of the applied document
traceway.trigger.firedtraceway.trigger.id, traceway.trigger.name
traceway.capture.startedtraceway.capture.id; for a trigger's capture also traceway.capture.source: trigger, traceway.trigger.id, traceway.capture.until
session.start, traceway.session.update, session.endsession.id, traceway.session.started_at and the session's attributes

The OpAMP endpoint

POST /api/otel/v1/opamp speaks the plain-HTTP transport of OpAMP (opens in a new tab), with protobuf bodies (AgentToServer up, ServerToAgent down).

  • Auth: Authorization: Bearer <project token>. The OpAMP-Instance-UID header must match the message's instance_uid.
  • State: none on the server. The SDK sends its full description in every poll; a poll without one is answered with ReportFullState.
  • Answer: remote_config.config_map["traceway"] (application/json) with a SHA-256 config_hash, only when the hash differs from remote_config_status.last_remote_config_hash; and connection_settings.opamp.heartbeat_interval_seconds.
  • Client capabilities: ReportsStatus, AcceptsRemoteConfig, ReportsRemoteConfig, ReportsHeartbeat, and the custom capabilities io.traceway.sdk.buffer/v1 and io.traceway.sdk.capture/v1.
StatusWhenThe SDK
200Normal answerApplies the document, reports APPLIED (or FAILED and keeps the last good one)
400Malformed message, or the uid header does not matchBacks off
401Unknown project tokenStops polling
403The token belongs to a project that is not a browser project (React, Vue, Svelte or jQuery)Stops polling
413Body over 64 KB, raw or decompressedDoes not retry that message
415Not application/x-protobufBacks off
503Too many polls at once, or the rules could not load; Retry-After setWaits as told, keeps its settings

Errors back off from 30 seconds to 30 minutes. The heartbeat is never shorter than 30 seconds.

The endpoint uses the protobuf types of opamp-go (opens in a new tab) and is tested against opamp-go's own HTTP client, so other OpAMP clients can poll it too.

Dashboard API

The Data Collection tab uses these routes. They need dashboard authentication, or an agent credential for the rule and preview routes (see Agent Write Access), and write access on the project for changes. The /api/sdk-config routes answer 403 for a project that is not a browser project.

MethodEndpointPurpose
GET/api/sdk-config/rulesRules in order, plus the poll interval
POST/api/sdk-config/rulesCreate a rule: {name, enabled, conditions, settings}; at most 50 per project
PUT/api/sdk-config/rules/reorder{ids}, every rule once
PUT, DELETE/api/sdk-config/rules/:idUpdate (the same body, plus an optional expectedUpdatedAt that answers 409 when the rule changed since that read; required for agent credentials), delete
POST/api/sdk-config/preview{attributes, instanceUid?} → the document such a client gets, its hash, and the rules and captures it matched
GET, POST/api/sdk-config/capturesUp to 50 captures: the active ones, then the most recent expired and cancelled ones, newest first in each group, each with active and a status (see Capture status) / start one: {target: {kind, key?, value}, durationMinutes, lookbackSeconds?, replay?} with kind instance, user, session or attribute
DELETE/api/sdk-config/captures/:idCancel a capture
GET/api/sessions/:id/timeline?from=&to=A session's breadcrumbs from its log records and spans, for a window of at most 3 hours

Limits

WhatLimit
Settings stored in one rule16 KiB (the merged response can be larger)
Rules per project50
Conditions per rule20
Triggers per rule20
Steps per trigger, actions per trigger5 each
Active captures per project20
Capture duration24 hours
OpAMP poll body64 KB

Why did this client collect this data?

Evaluate settings in this order:

  1. SDK defaults establish buffering, streaming and error clips.
  2. Matching remote rules apply in displayed order; later fields override earlier fields.
  3. Developer-disabled signals and plan limits remain hard ceilings.
  4. Temporary captures and trigger overrides can increase allowed collection until expiry.
  5. Signal filtering/sampling, replay cooldowns and clip limits, the error limiter, bounded local buffers, and the shared diagnostic upload budget still apply.

Preview shows the server overlay for the attributes you entered, not proof of the settings a live browser is running. It does not know the client's initialization options, buffer contents, remaining budget, or whether the browser has polled. Inspect session counters and capture acknowledgement status as well.

Capture status

  • Waiting for client: no matching v2 browser has received this capture.
  • Delivered · awaiting acknowledgement: a poll offered the configuration; receipt does not prove application.
  • Applied · awaiting data: a matching browser acknowledged the current configuration hash as applied.
  • Collecting: tagged log/span data has reached Traceway.
  • Expired · no data received: the capture ended without tagged data reaching Traceway.
  • Completed: the capture ended after tagged data reached Traceway.
  • Cancelled: someone cancelled the capture.

Expired and cancelled captures stay in the list after the active ones, which shows up to 50 captures in all.

These statuses reflect at least one matching browser, not every member of a cohort. They survive server restarts and work across instances sharing the main database. The dashboard refreshes status every 15 seconds while visible. A suspended or closed browser cannot acknowledge; clients already under capture poll every minute. External-only logs/spans cannot be confirmed by Traceway, so “no data received” does not prove the external platform received nothing.

Diagnostic samples and averages

Error-triggered and targeted requests are diagnostic samples, biased toward problematic visits. Randomly discarding some exception-related samples afterwards cannot recover the missing healthy visits and does not correct that bias.

Traceway keeps browser diagnostic spans out of endpoint/task/AI performance aggregates, while retaining them in trace exploration and session timelines. Browser SDK resources are identified explicitly so accidentally sending them to a backend project does not turn them into endpoint measurements. The SDK marks spans with traceway.collection.source and traceway.collection.baseline_rate. A stable optional healthy-session baseline is independent of error occurrence, but a changing or targeted sampling rule is not a universal estimate of production traffic.

Use independently collected web vitals and backend request measurements for normal performance. Custom queries over raw browser spans must account for their collection policy; the backend does not fabricate population averages or apply guessed inverse weights. The session overview includes a tooltip explaining this distinction.