Docs / SDKs / JavaScript

JavaScript SDK

Browser SDK (@newtalaria/browser) for error capture, session replay, Web Vitals, and tracing.

On Silverstripe, the PHP module can inject @newtalaria/browser for you — see the Silverstripe guide. Full reference: npm README.

Install

npm install @newtalaria/browser

Initialize

Use a project client key (tal_live_…). In production set minLevel: 'warning', keep session replay sampling low (or 0), and rely on on-error clips. Put stable product dimensions in init tags (service, platform).

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

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…', // Project settings → Client keys
  environment: 'production',
  release: '1.4.2',
  minLevel: 'warning', // production: drop info/debug noise
  tags: { service: 'storefront', platform: 'web' },
  // Defaults — cheapest useful replay profile
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 1,
  replaysErrorAfterMs: 15_000,
  maskAllInputs: true,
});

Logger API

Prefer Talaria.logger (or withTags) and level methods. Exceptions stay on captureException. Console hooks only add replay breadcrumbs — they are not gated by minLevel and do not create events. Gates run minLevel → sampleRate → beforeSend.

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

await logger.info('Checkout opened', { extra: { cart_id: 'abc123' } });
await logger.warn('Payment method missing');

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

// Child scopes inherit tags; minLevel can only raise the floor.
const payments = logger.child({
  tags: { component: 'payments' },
  minLevel: 'error',
});
await payments.error('Charge failed');

Tags and patterns

Use tags for low-cardinality filters (feature, operation, component). Put ids, payloads, and counts in extra. Do not put environment or release in tags — use the first-class init fields.

// tags = low-cardinality filters; extra = high-cardinality diagnostics
await logger.error('Charge declined', {
  tags: { feature: 'checkout', operation: 'charge', component: 'stripe' },
  extra: { cart_id: 'cart_01H…', decline_code: 'insufficient_funds' },
});

// Prefer warn/error in production (minLevel: 'warning').
// Use info for intentional product signals when you lower the floor.

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

Performance tracing

Tracing is off until enableTracing is true or tracesSampleRate is greater than 0. Head-based sampling: 100% of error transactions; default 10% of successful pageloads. The SDK records navigation transactions, fetch/XHR spans, and Web Vitals. Inspect waterfalls and vitals in Performance. Child spans are not billed — only sampled root transactions.

Talaria.init({
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production',
  enableTracing: true,
  tracesSampleRate: 0.1, // 10% of successful navigations; errors always traced
});

Already running an OpenTelemetry Collector? That is an advanced path — export OTLP/HTTP JSON to POST /otlp/v1/traces. Prefer the native SDK unless you already operate a Collector. See the API overview.

Troubleshooting

• 401/403 — check API key and that it belongs to the target project.
• No issue appears — confirm environment filter in the dashboard.
• Rejected events — validate JSON shape against the API overview.

• logger.info missing — check minLevel (production often uses warning). Use isLevelEnabled before building expensive context.
• Exceptions dropped after setMinLevel('fatal') — captureException counts as error.

Full options, replay sampling, and network capture details are in the @newtalaria/browser README. Prefer another language? See all SDKs or the API overview.