@newtalaria/browser

Official browser SDK for Talaria — capture exceptions and application logs, and record session replay (rrweb event streams, not video) so your team can see what users did before an issue.

Docs: JavaScript SDK guide · Dashboard: one.newtalaria.com

Install

npm install @newtalaria/browser

Script tag (no bundler)

Load the IIFE build from a CDN or your own static host, then call Talaria.init:

<script src="https://cdn.jsdelivr.net/npm/@newtalaria/browser/dist/talaria.browser.iife.js"></script>
<script>
  Talaria.init({
    dsn: 'https://api.newtalaria.com',
    apiKey: 'tal_live_…',
    environment: 'production',
    minLevel: 'warning',
  });
</script>

Pin a version in production (for example @newtalaria/[email protected]) instead of floating on latest.

Initialize (best practices)

Create a client key under Project settings → Client keys (tal_live_…). Use your project’s API base URL as dsn (Talaria Cloud: https://api.newtalaria.com).

import { Talaria } from '@newtalaria/browser';

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production', // staging | development also accepted
  release: '1.4.2',          // deploy version — first-class field, not a tag
  commitSha: process.env.TALARIA_COMMIT_SHA, // optional; enables GitHub source
  minLevel: 'warning',       // production: drop info/debug noise
  tags: {
    service: 'storefront',
    platform: 'web',
  },
  // Cheapest useful replay profile (also the defaults):
  replaysSessionSampleRate: 0,   // no continuous upload
  replaysOnErrorSampleRate: 1,   // clip around errors
  replaysErrorAfterMs: 15_000,   // ~15s after the error
  maskAllInputs: true,
});

Recommendations

| Concern | Production default | | --- | --- | | Log volume | minLevel: 'warning' (use 'info' / 'debug' only when you intentionally want noisier capture) | | Replay cost | Keep replaysSessionSampleRate low or 0; rely on on-error clips | | Identity | Set userId when you know the signed-in user | | Product dims | Put stable filters in init tags (service, platform) | | Privacy | Leave maskAllInputs: true; mark sensitive DOM with data-talaria-mask | | Invalid key | The SDK stops sending events, spans, and replay for this page after a permanent ingest error (retry: false). Quota and 5xx keep sending. |

Talaria.init installs window.onerror / unhandledrejection handlers unless you pass disableDefaultIntegrations: true. Opaque cross-origin "Script error." events, browser-extension stacks, and Sentry-class unactionable messages (_AutofillCallbackHandler, ResizeObserver loop, CEFSharp simulateEvent, …) are ignored by default. Override with ignoreErrors / ignoreUrls. Gate order: built-in noise → ignoreErrors → ignoreUrls → minLevel → sampleRate → beforeSend. Dropping an error does not stop session replay.

environment must resolve to production | staging | development. Common aliases work (prod / live → production, test / uat → staging, dev / local → development). Invalid values throw at init.

Logging

Prefer a scoped logger for application code. Level methods wrap captureMessage; use captureException for throwables.

const logger = Talaria.logger({
  tags: { feature: 'checkout', operation: 'pay' },
});

await logger.info('Checkout opened');           // filtered if minLevel is warning
await logger.warn('Payment method missing');

try {
  await charge();
} catch (error) {
  await logger.captureException(error, {
    tags: { component: 'stripe' },
    extra: { cart_id: 'abc123' },
  });
  throw error;
}

| Method | Severity sent | | --- | --- | | debug / info / warning / error / fatal | same name | | warn | warning | | log(level, message, context?) | level | | captureException(error, context?) | error |

Also available on the root Talaria facade (Talaria.warn(…), etc.).
Talaria.withTags({ … }) is shorthand for Talaria.logger({ tags: { … } }).
Low-level captureMessage(message, level?, context?) remains supported.

Filtering

Gates run in order. Filtered calls still resolve successfully (no throw).

1. minLevel (default 'debug') — default/root severity. Direct client captures and unset scopes use this. Scoped loggers may override below it unless enforceDefaultLevel is true.
2. sampleRate (default 1) — fraction of eligible events to send. Independent of replay sample rates.
3. beforeSend(event, hint) — return null to drop, or a mutated event. Not called when earlier gates already dropped the capture.

Scoped loggers inherit the client default and can assign a higher or lower floor (Logback-style). PHP docs (same contract): logging-levels.md in the PHP SDK.

// warning globally, info for one area
Talaria.init({
  /* … */
  minLevel: 'warning',
  enforceDefaultLevel: false,
  loggers: {
    businessDirectory: {
      minLevel: 'info',
      tags: { area: 'businessDirectory' },
    },
  },
});

const directory = Talaria.logger('businessDirectory');
await directory.info('Listing loaded'); // sent

const payments = logger.child({
  tags: { component: 'payments' },
  minLevel: 'error', // quieter than default
});

if (logger.isLevelEnabled('info')) {
  // build expensive context only when it would send
}

Browser console.* hooks add replay breadcrumbs only. They are not gated by minLevel and do not create Talaria events.

Good patterns

Feature-scoped logger per flow

function createCheckoutLogger(step: string) {
  return Talaria.logger({
    tags: { feature: 'checkout', operation: step },
  });
}

const logger = createCheckoutLogger('review');
await logger.warn('Address validation failed', {
  extra: { field: 'postcode' },
});

Tags vs extra

| Use | For | Examples | | --- | --- | --- | | tags | Low-cardinality dimensions you filter/group on | feature, operation, component, service | | extra | High-cardinality diagnostics | cart_id, payloads, counts, free-form detail |

await logger.error('Charge declined', {
  tags: { component: 'stripe', operation: 'charge' },
  extra: { cart_id: 'cart_01H…', decline_code: 'insufficient_funds' },
});

Child logger that only sends errors

const analytics = Talaria.logger({ tags: { feature: 'analytics' } }).withMinLevel(
  'error',
);
await analytics.info('page_view'); // no-op when floor is error
await analytics.captureException(err);

Redact before send

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production',
  minLevel: 'warning',
  beforeSend(event) {
    if (event.message.toLowerCase().includes('password')) return null;
    if (event.extra && 'rawCard' in event.extra) {
      const { rawCard: _, ...extra } = event.extra;
      return { ...event, extra };
    }
    return event;
  },
});

Severity guidance

• warn / error / fatal — user-impacting or actionable problems (default production traffic when minLevel: 'warning').
• info — intentional product signals (funnel steps, “empty state”) when you lower minLevel or run in staging.
• debug — local diagnosis only; leave filtered out in production.

Tags

Preferred conventions (optional, but useful in the dashboard):

service, platform, feature, operation, component, runtime, runtime_version

Merge order (later wins): automatic browser tags → init tags → logger / withTags scope → per-call context.tags.

Limits: max 20 tags per event, key ≤64 ([a-z0-9_.-]), value ≤128, ~2KB total. Invalid keys are dropped. In non-production, high-cardinality-looking keys/values log a console warning.

Do not put environment or release in tags — use the first-class init fields. Do not put user ids, emails, order ids, or URLs in tags — use userId / extra.

Every event also gets automatic browser triage tags such as browser.name, os.name, and device.

Session replay

You pay for uploaded + retained replay data, not for local buffering. Prefer on-error clips in production.

| Traffic | replaysSessionSampleRate | replaysOnErrorSampleRate | replaysErrorAfterMs | | --- | --- | --- | --- | | High | 0.01 | 1.0 | 15000 (default) | | Medium | 0.1 | 1.0 | 15000 | | Low | 0.25 | 1.0 | 15000 | | Marketing / docs | 0 | 1.0 | 15000 | | Richer post-error context | 0 | 1.0 | 0 (continue until session cap) |

Defaults (session=0, onError=1, errorAfterMs=15000) are the cheapest useful profile: quiet traffic uploads nothing; each sampled error keeps ~60s before + ~15s after.

| Mode | What happens | | --- | --- | | Session sample hit | Continuous upload for the page session (until unload or max duration) | | Session sample miss | Record into a local ring buffer; nothing uploaded until an error sample hits | | Error sample | Upload the buffer in one replays/ingestSegmentBatch plus a short trailing window, attach replayId when segments land, then return to buffer mode |

When an error clip cannot be uploaded, the error event may include:

| Tag | Meaning | | --- | --- | | replay.capture | ok | failed | skipped | | replay.capture_reason | Why a clip failed or was skipped (e.g. not_sampled, upload_failed) |

Failed captures do not set replayId (avoids linking an empty player).

Privacy

• maskAllInputs: true by default (password fields masked).
• Block sensitive nodes with data-talaria-mask or blockSelector.
• For login-protected admin CSS, set inlineStylesheet: true so same-origin styles are embedded while the user is logged in. Public sites usually leave this false.

Heatmaps

With analytics consent on (enableAnalytics: true or Talaria.analytics.optIn()), each pageview records element clicks and scroll depth and sends them to POST /heatmaps/ingestBatch (same analyticsWrite scope). Set heatmaps: false to keep analytics without heatmaps; the project can also turn them off in settings.

• Clicks are placed by element: a stable CSS selector plus the offset inside the element, so maps stay accurate across widths. Clicks inside a button or link count toward the control; clicks inside a blocked node count toward the blocked node.
• Rage: 3+ clicks within 1s and 30px. Dead: no DOM change, URL change, scroll, or focus change within 1s (form fields and text selection excluded). Error: an error captured by the SDK within 2s.
• Scroll depth is scrollY + innerHeight on document scrolling, against the tallest document height seen.
• Element text and input values are never sent. Selectors prefer data-talaria-heatmap, then data-testid, then a stable id, and skip generated / state classes and anything with an email or long number.
• When the server asks for a page backdrop, the SDK sends one masked DOM snapshot (maskAllInputs, blockSelector, data-talaria-mask; readable stylesheets inlined). rrweb-snapshot loads only at that point.

<button data-talaria-heatmap="checkout-cta">Checkout</button>

Failed HTTP / network requests

All instrumented fetch / XHR calls are recorded as replay breadcrumbs except Talaria ingest/replay/span traffic. Error events are promoted only for first-party (same-origin) or allowlisted origins — so analytics, ads, and widgets do not spam Issues.

| Request | HTTP 5xx | Transport failure / timeout | Abort | | --- | --- | --- | --- | | Same-origin | Error event | Error event | Breadcrumb only | | Allowlisted (networkErrorOrigins) | Error event | Error event | Breadcrumb only | | Other third-party | Breadcrumb only | Breadcrumb only | Breadcrumb only |

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production',
  minLevel: 'warning',
  captureFailedRequests: true,
  captureNetworkErrors: true,
  networkErrorOrigins: ['https://api.stripe.com'],
  captureRequestQueryParameters: false, // default — strip ?query from network URLs
  failedRequestStatusCodes: [[500, 599]], // CMS admin often uses [[400, 599]]
  failedRequestIgnoreUrls: ['/health'],
});

Query strings are stripped from network telemetry by default. Bodies and auth headers are never captured. AbortError is never promoted.

Tracing (performance)

Turn tracing on in the project (tracingEnabled), then set enableTracing: true or tracesSampleRate > 0. Spans are a parallel ingest path (POST /spans/ingestBatch) — they are never mixed into events/ingest. Browser keys need the spansWrite scope; auth is the same X-API-Key header. Sampled root transactions are included on the plan — there is no Performance add-on.

Sampling is head-based: successful pageload transactions use tracesSampleRate (default 10% once tracing is on). Transactions that contain an error are always kept.

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production',
  minLevel: 'warning',
  enableTracing: true,       // or tracesSampleRate: 0.1
  tracesSampleRate: 0.1,     // successful pageloads; errors are 100%
  networkErrorOrigins: ['https://api.stripe.com'],
});

When tracing is on, the SDK:

• Starts a pageload transaction and records Web Vitals (lcp, inp, cls) as span attributes / span events.
• Creates fetch / XHR child spans for instrumented requests (Talaria ingest URLs are skipped).
• Injects W3C traceparent on same-origin and networkErrorOrigins allowlisted hosts only (same policy as failed-request promotion — so ads/analytics do not get a CORS preflight).
• Flushes the span queue on the same pagehide / keepalive path as replay.

Error events also receive traceId / spanId (when a trace is active) and the last 50 breadcrumbs (console + network, copied from the same hooks that feed session replay). Breadcrumbs are snapshotted before the replay flush so the error trail is the user session, not Talaria ingest. Fetch/XHR to the Talaria API (/events/, /spans/, /replays/) is omitted from breadcrumbs.

beforeSend remains the only event processor — there is no addProcessor.

Init options

| Option | Default | Description | | --- | --- | --- | | dsn / baseUrl | (required) | Talaria API base URL, e.g. https://api.newtalaria.com | | apiKey | (required) | Public client key (tal_live_…). Safe to embed; configure allowed domains in the dashboard for production. | | environment | (required) | production | staging | development (aliases accepted) | | release | — | Optional release string on every event | | commitSha | — | Optional git SHA for source context (TALARIA_COMMIT_SHA) | | userId | — | Optional app user id | | tags | — | Tags merged into every event | | minLevel | 'debug' | Default/root severity; use 'warning' in production | | enforceDefaultLevel | false | When true, scoped loggers cannot go below minLevel | | loggers | {} | Named presets for Talaria.logger('name') | | sampleRate | 1 | Fraction of eligible events to send (after level gate) | | beforeSend | — | (event, hint) => event \| null — mutate or drop after gates | | replaysSessionSampleRate | 0 | Fraction of sessions that upload continuously | | replaysOnErrorSampleRate | 1 | Fraction of errors that promote the ring buffer | | replaysErrorAfterMs | 15000 | Post-error upload window; 0 = continue until session cap | | maskAllInputs | true | Mask inputs in replay | | inlineStylesheet | false | Embed same-origin CSS (auth-gated admin UIs) | | blockSelector | — | Extra CSS selectors blocked from the DOM snapshot | | disableDefaultIntegrations | false | Skip window.onerror / unhandledrejection | | captureFailedRequests | true | Promote HTTP status failures (first-party / allowlisted only) | | captureNetworkErrors | true | Promote transport/timeout failures (first-party / allowlisted only) | | networkErrorOrigins | [] | Extra origins eligible for error promotion and traceparent injection; ['*'] = all (not recommended) | | failedRequestStatusCodes | [[500, 599]] | Status codes/ranges to promote when origin is eligible | | failedRequestIgnoreUrls | [] | URL substrings never promoted | | captureRequestQueryParameters | false | Keep ?query on network URLs after redaction | | inAppOrigins | [] | Extra origins treated as app code for stack inApp | | inAppAllowUrls / inAppDenyUrls | [] | Force stack frames inApp: true / false | | enableTracing | false | Turn on pageload + fetch/XHR spans. Also implied when tracesSampleRate > 0 | | tracesSampleRate | 0.1 when tracing is on, else 0 | Head sample rate for successful transactions (errors always kept) | | enableAnalytics | false | Product analytics; or call Talaria.analytics.optIn() after consent | | heatmaps | true | Click + scroll heatmaps while analytics consent is on; false keeps analytics without heatmaps |

Public API

| API | Description | | --- | --- | | Talaria.init(options) | Configure + start recording + install network/console hooks | | Talaria.logger(name \| options?) | Scoped logger (tags, minLevel, named presets) | | Talaria.withTags(tags) | Shorthand for logger({ tags }) | | Talaria.debug / info / warning / warn / error / fatal | Level helpers | | Talaria.log(level, message, context?) | Generic level helper | | Talaria.captureException(error, context?) | Ingest error (+ replay link when sampled) | | Talaria.captureMessage(message, level?, context?) | Ingest message | | Talaria.getMinLevel() / setMinLevel(level) | Read/update default/root level | | Talaria.isEnforceDefaultLevel() / setEnforceDefaultLevel(bool) | Hard-floor toggle | | Talaria.isLevelEnabled(level) | Whether a level would pass the root floor | | Talaria.getReplayId() | Active upload replay id, or null | | Talaria.getTraceId() / getSpanId() | Active pageload trace/span ids when tracing is on | | Talaria.flush() | Upload buffered replay segments and ended spans | | Talaria.close() | Stop recording, flush, finish |

Scoped loggers also expose child, withMinLevel, withTags, isLevelEnabled, and getMinLevel.

Troubleshooting

| Symptom | What to check | | --- | --- | | 401 / 403 | Client key (tal_live_…) belongs to the project; allowed domains configured for production | | logger.info never appears | Root minLevel is often 'warning' — use a scoped/named logger with minLevel: 'info', or lower the root | | Exceptions missing after setMinLevel('fatal') | captureException counts as 'error' and is filtered by a fatal floor | | No replay on an error | Check replay.capture / replay.capture_reason on the event; clip may have been skipped or failed to upload | | Permanent ingest 4xx | Misconfigured env/auth/payload disables further capture for that page session so the SDK cannot spin forever |

More guides: www.newtalaria.com/docs