Sentiero

Configuration

Sentiero is configured through Sentiero.configure, which yields a single Sentiero::Configuration object. Set options in an initializer (Rails) or once at boot (Roda/Sinatra/plain Rack):

Sentiero.configure do |config|
  config.store = Sentiero::Stores::Redis.new
  config.capture_metadata = true
  config.retention_period = 90 * 24 * 60 * 60 # 90 days
end

This page is the authoritative reference for every option, grouped by area. Defaults match lib/sentiero/configuration.rb. Rails apps also have a separate Sentiero::Rails.configure object; see the Rails section below.

Password masking is always enforced. Regardless of any masking setting below (including mask_all_inputs = false or anything you pass via mask_input_options / recorder_options), password inputs are always masked. Configuration::ENFORCED_PRIVACY merges { maskInputOptions: { password: true } } into every effective config and the frontend re-applies it independently. See Privacy & Masking.

Core / Store

Option Type Default Description
store Store instance nil The backend that persists sessions and events (Memory, File, SQLite, Redis, Rails AR, or a custom store). Required: reading Sentiero.store with this unset raises Sentiero::Error. The Rails engine auto-sets Sentiero::Rails::Store.new if you leave it nil.
cors_origins Array of String [] Allowed origins for the public events endpoint. Empty means no cross-origin requests are permitted.
auth_callback Proc / nil nil Proc called with the Rack env to authorize dashboard and analytics requests. Returns truthy to allow; a falsy return yields 403. nil means no callback-based auth (protect via route-level auth instead).
basic_auth Hash / nil nil When set to { user: "...", password: "..." }, enables the built-in Sentiero::Web::BasicAuth middleware, which performs constant-time HTTP Basic authentication before any dashboard route. nil disables it (use auth_callback or route-level auth instead). Assumes TLS terminated upstream.
ingest_keys Hash {} Maps ingest secret keys to project names (e.g. { "secret123" => "myapp" }). Used by Sentiero::Web::IngestApp to authenticate server-side error ingestion requests. Empty hash means no key-authenticated ingest is accepted.

Frontend Flush & Limits

Option Type Default Description
flush_interval_ms Integer 10_000 Milliseconds between time-based flushes from the browser to the server.
flush_event_threshold Integer 50 Buffer size that triggers an immediate flush, whichever comes first with the interval.
max_events_per_page Integer 1_000 Pagination cap for events returned by the dashboard events API per page.
max_events_per_request Integer / nil nil Optional ceiling on events accepted in a single ingest request. nil = no extra cap (the server payload size limit still applies).
max_sessions Integer / nil nil LRU cap on total stored sessions. nil = unlimited. When exceeded, the oldest sessions (by updated_at) are evicted.
max_events_per_session Integer / nil nil LRU cap on events kept per session. nil = unlimited. When exceeded, the oldest events (by timestamp) are evicted.
cross_tab_sessions Boolean true true stores the session ID in localStorage (shared across tabs); false uses sessionStorage (per-tab). See Privacy & Masking.
session_idle_timeout Integer 21_600 (6 hours) Inactivity gap in seconds after which a returning visitor gets a fresh session ID. Bounds a “journey” without splitting it on short breaks.
session_max_age Integer 604_800 (7 days) Absolute lifetime cap in seconds for one session ID, even for continuously active tabs — keeps the identifier from becoming permanent and lets retention purge age data out.

Capture Toggles

Option Type Default Description
capture_metadata Boolean false Capture page URL, referrer, user agent, and viewport with the session.
capture_errors Boolean false Capture JS errors and unhandled promise rejections as timeline custom events.
capture_web_vitals Boolean false Capture Core Web Vitals (LCP, CLS, INP, etc.) and surface them as badges in replay.
capture_clicks Boolean false Record click positions for the click overlay in replay and the analytics click heatmaps.
track_navigation Boolean false Log outbound link clicks as navigation custom events.
track_custom_events Boolean false Enable declarative data-sentiero-track-* attribute tracking. See Custom Events.
track_forms Boolean false Capture real form submits as __form_submit custom events (form name/id attributes + page URL, never values) for the form analytics view.

Recorder / Privacy Masking

These map to rrweb recorder options, converted from snake_case to camelCase automatically. See The Recorder and Privacy & Masking for behavior detail.

Option Type Default Description
mask_all_inputs Boolean true Mask all form input values. Passwords stay masked even when this is false.
mask_input_options Hash {} Per-input-type masking (e.g. { email: true }). { password: true } is always merged in and cannot be overridden.
block_selector String "[data-rr-block]" CSS selector for elements excluded from recording entirely.
mask_text_selector String "[data-rr-mask]" CSS selector for elements whose text content is masked.
ignore_selector String "[data-rr-ignore]" CSS selector for elements whose DOM mutations are ignored.
sampling Hash { scroll: 150, input: "last" } rrweb throttling: scroll interval in ms and input sampling strategy.
inline_stylesheet Boolean / nil nil Forwarded to rrweb as inlineStylesheet only when set; omitted when nil.
checkout_every_n_ms Integer / nil nil Forwarded to rrweb as checkoutEveryNms only when set; omitted when nil. Forces a full snapshot on the given interval.
recorder_options Hash {} Escape hatch: a raw camelCase hash passed through to rrweb verbatim. First-class options above take precedence on overlapping keys.

Error Tracking / Resource Limits

These options cap stored error-tracking data. All default to the values shown; set them lower for resource-constrained deployments.

Option Type Default Description
max_problems Integer / nil 5_000 LRU cap on stored problems (grouped error fingerprints). When exceeded, problems with the oldest last_seen are evicted along with their occurrences.
max_server_events Integer / nil 50_000 LRU cap on stored server events. When exceeded, the oldest events (by timestamp) are evicted.

Analytics

Option Type Default Description
analytics_max_scan_sessions Integer 5000 Cap on how many sessions a single compute-on-read analytics scan (or bulk erase/purge batch) reads. Bounds memory and request time at scale.

Sharing

Option Type Default Description
shareable_replays Boolean false Enables the standalone-HTML export and play-from-JSON import routes. Off by default because a share file is a full session dump that leaves your infrastructure; the routes 404 until enabled.

Privacy & Compliance

See Privacy & Masking for the full guide.

Option Type Default Description
user_opt_out Boolean false Honor an end-user opt-out cookie. When true, requests carrying the opt-out cookie are not recorded.
opt_out_cookie_name String "sentiero_optout" Name of the cookie that signals end-user opt-out.
respect_gpc Boolean true Honor the browser’s Global Privacy Control signal (navigator.globalPrivacyControl) as an opt-out. Enforced client-side; no POST is sent when the signal is set.
retention_period Integer (seconds) / nil nil Drives Sentiero.purge_expired!. nil keeps data forever; set a value (in seconds) and run the purge from a scheduler / rake sentiero:purge. Purge is destructive and irreversible.
redaction Config object (see below) Side-channel redaction engine: URL stripping/filtering, free-text pattern redaction, and opt-in DOM text backstop. See config.redaction below.
anonymize_ip Boolean true Truncate client IPs before they reach the store or logs (IPv4 /24, IPv6 /48) via Sentiero::IpAnonymizer.
audit_log Proc / nil nil Hook invoked for auditable dashboard/analytics actions (session listing/viewing, export, etc.). A no-op when unset; a raising callback is caught and logged.

config.redaction

Configures the side-channel redaction engine. All settings are optional; the defaults are secure out of the box. See Side-channel redaction for the full reference.

Setting Type Default Description
url_mode Symbol :strip :strip keeps path, drops query and fragment. :keep_filtered filters params. :keep_all is verbatim.
url_param_allowlist Array of String [] Params kept verbatim in :keep_filtered mode (e.g. %w[utm_source gclid]).
url_param_denylist Array of String [] Extra params to drop in :keep_filtered mode. Augments the built-in sensitive-name list.
disabled_patterns Array of Symbol [] Built-in free-text patterns to skip. Choices: :email, :url, :jwt, :long_hex, :card.
custom_patterns Array of Regexp [] Additional patterns. Applied to side-channel text and, when set, to DOM text.
dom_patterns Array of Symbol [] Built-in patterns to apply to rrweb DOM text/data fields (opt-in server-side backstop).
server_proc Proc / nil nil Ruby-only hook run on ingest after the declarative engine. Fail-closed: a raising proc drops the event.

Minimal example:

Sentiero.configure do |config|
  config.redaction.url_mode            = :keep_filtered
  config.redaction.url_param_allowlist = %w[utm_source utm_medium gclid]
  config.redaction.custom_patterns     = [/\bACCT-\d{6}\b/]
end

Rails Configuration

Rails apps have a second, separate configuration object, Sentiero::Rails.configuration (set via Sentiero::Rails.configure). It is distinct from Sentiero.configuration above. Source: lib/sentiero/rails/configuration.rb.

Option Type Default Description
events_url String "/sentiero/events" Default ingest endpoint the sentiero_script_tag view helper points the recorder at. Passing events_url: directly to the helper overrides it.
reporter_middleware Boolean true When true, the engine auto-inserts Sentiero::Reporter::Middleware into the Rails middleware stack (mirrors Sentry/Honeybadger auto-install). The middleware only activates if the reporter is also configured and active. Set to false to opt out of automatic insertion and manage the middleware manually. 
Sentiero::Rails.configure do |config|
  config.events_url = "/sentiero/events" # default
  config.reporter_middleware = true       # default; set false to opt out
end

See Rails for the full Rails integration guide.