Vantmetry

Appearance

Tracker ​

The Vantmetry tracker is a lightweight script that captures errors in your browser and sends them to the ingestor. There are two ways to install it: a CDN script tag or the npm package.

The tracker source code is published on npm. You can inspect every line before embedding it in your site.

CDN script tag (HTML) ​

The simplest integration. Add this to your HTML <head> or before </body>:

html
<script
  src="https://cdn.vantmetry.com/tracker.js"
  data-public-key="YOUR_PUBLIC_KEY"
></script>

The script initializes automatically and begins capturing errors. No additional code is needed.

Accessing the tracker instance ​

After the script loads, the tracker is available globally:

javascript
// Option 1: use the global directly
window.Vantmetry.error('Something went wrong');
window.Vantmetry.warn('Deprecation notice', { component: 'Header' });

// Option 2: wait for ready callback
window.onVantmetryReady = function (vantmetry) {
  vantmetry.info('Tracker initialized');
};

npm package ​

For bundled applications (React, Vue, Svelte, etc.):

bash
npm install vantmetry

Then initialize in your app entry point:

typescript
import { init, logger } from 'vantmetry';

init({ publicKey: 'YOUR_PUBLIC_KEY' });

// Use the logger anywhere in your app
logger.error('Payment failed', { orderId: '12345' });
logger.warn('Slow API response', { endpoint: '/api/users', ms: 3200 });
logger.info('User signed in');
logger.debug('Cache hit', { key: 'user:42' });

Framework Integrations ​

For framework-specific setup and patterns:

  • React - Context provider, hooks, error boundary
  • Next.js - App Router and Pages Router support

Logger API ​

All methods accept an optional details object for structured context:

MethodSeverityUse case
logger.error(message, details?)ERRORCaught exceptions, failed operations
logger.warn(message, details?)WARNDeprecations, degraded states
logger.info(message, details?)INFOBusiness events, user actions
logger.debug(message, details?)DEBUGDevelopment diagnostics

Call logger.flush() to send buffered logs immediately (e.g., before navigation).

How batching works ​

The tracker buffers logs and sends them in batches to minimize network overhead:

  • Flushes automatically when the buffer reaches 50 items
  • Flushes on a 2-second timer if the batch isn't full
  • Flushes when the page becomes hidden (tab switch, minimize, navigation)

Deduplication ​

The tracker prevents duplicate errors from flooding your dashboard:

  • Within a batch: identical errors are merged and their count is incremented
  • Across batches: errors with the same signature are suppressed for 60 seconds after first send

Circuit breaker ​

If your app enters an error loop (over 100 events per second), the tracker disables itself and prints a warning to the console. This prevents runaway errors from consuming your quota or impacting page performance.

PII masking ​

Before any data leaves the browser, the tracker scrubs sensitive patterns:

PatternExampleMasked as
Email addressesuser@example.comu***@example.com
Credit card numbers4111111111111234************1234
Social Security Numbers123-45-6789***-**-6789
JWTseyJhbG...[JWT REDACTED]
Auth headersBearer abc123Bearer [TOKEN REDACTED]

Object keys like password, secret, token, api_key, session, and cookie are fully redacted to [REDACTED].

Transport chain ​

The tracker tries the fastest available transport and falls back gracefully:

  1. WebTransport (QUIC/HTTP3) fastest, non-blocking, survives page unload
  2. navigator.sendBeacon reliable during page unload
  3. fetch with keepalive: true broadest browser support

This happens transparently. You don't need to configure anything.

Automatic source map resolution ​

When your code is minified for production, stack traces contain references to minified file names and line numbers. Vantmetry automatically resolves these back to your original source code by fetching the source maps from the same location as your JavaScript files.

No upload or configuration is needed. The ingestor discovers source maps by looking for the sourceMappingURL comment in your JavaScript files, or by appending .map to the file URL. Once found, they're cached and used to decode stack traces.

Some frameworks may use different source map formats or locations, so resolution may not work in all cases. When a source map cannot be resolved, the original minified stack trace is shown unchanged.

Debug mode ​

Enable verbose console output by setting a localStorage flag:

javascript
localStorage.setItem('vantmetry_debug', 'true');

Remove it to disable:

javascript
localStorage.removeItem('vantmetry_debug');