SDK Documentation

npm install @vantatrace/sdk

import { VantaTrace } from '@vantatrace/sdk';

const vantaTrace = new VantaTrace({
  apiKey: 'ep_live_xxxxxxxxxxxxxxxxxxxxxxxx', // Your project API key
  debug: false, // Enable verbose SDK logs in development

  // ── try/catch capture ────────────────────────────────────────────────
  // An error you handle yourself never reaches errorHandler() or the
  // global handlers, so it needs its own capture path. Details in the
  // "try/catch Capture" section below.
  autoCapture: {
    http5xx: true,           // ON by default — a 5xx answer with no error reported
    httpClientErrors: true,  // ON by default — same for 4xx (401 + 404 excluded)

    // Opt-in: recovers the REAL Error object from inside your catch blocks
    // using the V8 inspector. Auto-disabled when NODE_ENV=production —
    // use the Babel plugin there instead (zero runtime cost).
    caughtExceptions: process.env.NODE_ENV !== 'production',
  },
});

// Call once, right after initialization
vantaTrace.initGlobalHandlers();

// This registers:
//  1. process.on('uncaughtException', ...)   – synchronous crashes
//  2. process.on('unhandledRejection', ...)  – async/await rejections
//  3. console.error patch                     – errors via console.error
//  4. Winston auto-patch (if installed)
//  5. Pino auto-patch (if installed)

import express from 'express';
import { VantaTrace } from '@vantatrace/sdk';

const app = express();

const vantaTrace = new VantaTrace({
  apiKey: process.env.VANTATRACE_API_KEY!,
});

// ① Mount requestHandler FIRST — before any routes or body parsers
app.use(vantaTrace.requestHandler());

app.use(express.json());

// ... your routes ...
app.get('/api/orders', async (req, res) => {
  const orders = await fetchOrders(); // any thrown error is auto-captured
  res.json(orders);
});

// ② Mount errorHandler LAST — after all routes and controllers
app.use(vantaTrace.errorHandler());

// Your own error response handler (still called via next(err))
app.use((err, req, res, next) => {
  res.status(500).json({ message: 'Internal Server Error' });
});

app.listen(3000);

app.get('/api/checkout', async (req, res) => {
  try {
    await chargeCard(req.body);
  } catch (error) {
    // Nothing escapes this block, so errorHandler() and the global
    // handlers never see it. Without try/catch capture, this failure is
    // invisible everywhere except your own logs.
    res.status(500).json({ error: 'Payment failed' });
  }
});

const isProd = process.env.NODE_ENV === 'production';

const vantaTrace = new VantaTrace({
  apiKey: process.env.VANTATRACE_API_KEY,
  autoCapture: {
    // ① Failed-request safety net — already ON, no config needed.
    //    The route above is reported as a synthetic HttpServerError with
    //    the method, route, status and the response body your catch block
    //    sent back. Pass false to turn it off.
    http5xx: true,

    // ② The same for 4xx answers your code returns on purpose
    //    (res.status(422).json(...)), at 'warning' severity.
    //    401 and 404 are excluded by default as routine traffic.
    httpClientErrors: true,

    // ③ Deep capture — the real Error object, not a synthetic one.
    //    Auto-disabled under NODE_ENV=production; use the Babel plugin there.
    caughtExceptions: !isProd,
  },
});

// Optional: detach the inspector session on graceful shutdown.
process.on('SIGTERM', () => vantaTrace.shutdown());

autoCapture: {
  caughtExceptions: {
    // 'request-failure' (default): buffer caught exceptions and report them
    // only if the request ends >= 500 — zero noise from errors your code
    // genuinely recovered from.
    // 'always': report every caught exception immediately, severity 'warning'.
    // Use this outside HTTP (queue consumers, cron jobs).
    report: 'request-failure',

    // Libraries throw and catch internally as control flow, which is noise.
    includeNodeModules: false,

    // Recording ceiling, protects throw-heavy hot loops.
    maxPerMinute: 120,

    // Required to run the inspector watcher under NODE_ENV=production.
    // Without it the watcher is skipped and a warning is logged.
    allowInProduction: false,
  },
}

// .babelrc — or babel.config.js
{
  "presets": ["@babel/preset-env"],
  "plugins": ["@vantatrace/sdk/babel-plugin"]
}

// What you write:
try {
  doSomething();
} catch (error) {
  res.status(500).json({ error: 'Failed' });
}

// What the plugin compiles it to — no inspector, no runtime cost:
import { captureExceptionGlobal } from '@vantatrace/sdk/runtime';

try {
  doSomething();
} catch (error) {
  captureExceptionGlobal(error);
  res.status(500).json({ error: 'Failed' });
}

// Opt a block out with a comment:
try {
  parseOptionalConfig();
} catch (error) { // vantatrace-ignore
  // expected control flow — not a defect worth reporting
}

try {
  await chargeCard(userId, amount);
} catch (error) {
  vantaTrace.captureException(error, {
    userId: 'user_482',
    route: '/api/checkout',
    method: 'POST',
    severity: 'critical',
    metadata: {
      amount: 29.99,
      currency: 'USD',
    },
  });
  throw error; // re-throw if needed
}

// Equivalent to captureException with severity: 'critical'
vantaTrace.captureCritical(error, { userId: 'user_42' });

// Equivalent to captureException with severity: 'warning'
vantaTrace.captureWarning(error, { route: '/api/webhook' });

// Equivalent to captureException with severity: 'info'
vantaTrace.captureInfo(error, { metadata: { source: 'scheduler' } });

// The full VantaTraceContext object you can pass to captureException:
{
  userId?: string;       // Authenticated user ID
  route?: string;        // API route (e.g. '/api/checkout')
  method?: string;       // HTTP method (e.g. 'POST')
  ip?: string;           // Client IP address
  headers?: Record<string, any>;  // Sanitized HTTP headers
  severity?: 'critical' | 'warning' | 'info';
  metadata?: Record<string, any>; // Any custom key-value payload
}

import winston from 'winston';
import { VantaTrace } from '@vantatrace/sdk';

const vantaTrace = new VantaTrace({
  apiKey: process.env.VANTATRACE_API_KEY!,
});

// Auto-patches Winston when initGlobalHandlers() is called.
// Any logger.error(error) call where the argument is an Error
// will be automatically forwarded to VantaTrace.
vantaTrace.initGlobalHandlers();

const logger = winston.createLogger({
  transports: [new winston.transports.Console()],
});

// This error will appear in your VantaTrace dashboard:
logger.error(new Error('Database connection refused'));

import pino from 'pino';
import { VantaTrace } from '@vantatrace/sdk';

const vantaTrace = new VantaTrace({
  apiKey: process.env.VANTATRACE_API_KEY!,
});

// Auto-patches Pino when initGlobalHandlers() is called.
vantaTrace.initGlobalHandlers();

const logger = pino();

// Any of these patterns will forward errors to VantaTrace:
logger.error(new Error('Connection timeout'));
logger.error({ err: new Error('DB query failed') }, 'Database error');
logger.error({ error: new Error('Payment failed') }, 'Payment error');

import { VantaTrace } from '@vantatrace/sdk';

// Get the active trace ID bound to the current async request context.
// Use this to correlate your own log entries with the VantaTrace dashboard event.
const traceId = VantaTrace.getActiveTraceId();

// Example: attach traceId to your response headers for distributed tracing
app.use(vantaTrace.requestHandler());

app.get('/api/orders', (req, res) => {
  const traceId = VantaTrace.getActiveTraceId();
  res.setHeader('X-Trace-Id', traceId ?? '');
  // ...
});