Skip to content
Docs menu

The errors SDK and ingest

Send your app's errors to your Venom Cloud with the dependency-free TypeScript SDK or plain HTTP: init, captureException, breadcrumbs, flags served, releases, grouping and the limits.

View .md

The SDK is one TypeScript file with no dependencies (sdk/errors/index.ts in Venom Cloud's source), the same way Venom Flags' SDK is. It posts only to the base URL you give it, batches events, never throws into your app, and has no session replay.

Node

import { init, captureException, captureMessage, addBreadcrumb, setUser } from "./venom-errors";

init({
  baseUrl: "https://cloud.example.com",
  key: process.env.VENOM_FLAGS_SDK_KEY!, // the environment's server key, vfs_…
  release: process.env.GIT_SHA,          // grouping, regressions and source maps are per release
  commit: process.env.GIT_SHA,
  tags: { service: "api" },
});

setUser({ id: "u_123" });                // "users affected" counts these
addBreadcrumb({ category: "http", message: "GET /pay" });
try {
  await charge();
} catch (err) {
  captureException(err, { tags: { route: "/pay" } });
}

uncaughtException and unhandledRejection are reported for you (the process still exits after an uncaught exception when yours is the only handler). Pass autoCapture: false to turn that off.

Browser

init({ baseUrl: "https://cloud.example.com", key: "vfc_…", release: "web@1.4.0" });

key is the environment's public client-side id (vfc_…), the same one Flags' browser SDK uses; it is safe to ship. error and unhandledrejection are captured. Requests carry the id in x-venom-client-id, and the endpoint answers CORS.

Which flags were on

const flags = new VenomFlags({ sdkKey, baseUrl });
init({ baseUrl, key, release, flags }); // anything with recentEvaluations(), or () => ({ checkout: "v2" })

The Flags server SDK remembers the last 100 values it served. They are attached to each error and shown on the issue page, so you can see that every failing user had checkout = v2. Per-call: captureException(err, { flags: {...} }).

Options and calls

init(options) baseUrl, key, release, commit, tags, autoCapture, flushMs (5 s), flags, beforeSend, fetch, onError
captureException(err, ctx?) ctx: level, tags, user, fingerprint, extra, flags. Returns the event id
captureMessage(text, level?, ctx?) for things that are not exceptions
addBreadcrumb(b) the last 50 are kept
setUser, setTag, flush(), close() flush resolves when sends settle; neither rejects

beforeSend(event) can change an event or return null to drop it. A send that fails is retried once; after that the events are dropped and onError is told (the SDK never retries forever or blocks your app).

Over HTTP

POST /incidents/sdk/events takes one event, a list, or { "events": [...], "release": { "version", "commit" } }, with Authorization: Bearer vfs_… or x-venom-client-id: vfc_…. It answers 202 {"accepted", "rejected", "ids"}.

{
  "type": "TypeError",
  "message": "Cannot read properties of undefined (reading 'id')",
  "stack": "TypeError: …\n    at charge (/srv/app/dist/charge.js:42:17)",
  "release": "1.4.0",
  "level": "error",
  "user": { "id": "u_123" },
  "tags": { "route": "/pay" },
  "flags": { "checkout": "v2" },
  "breadcrumbs": [{ "category": "http", "message": "GET /pay" }]
}

stack is read on the server (V8, Firefox and Safari, Python tracebacks and Java frames); send frames instead if you have them already. An event needs a type or a message.

How events are grouped

  1. A fingerprint array from the SDK wins.
  2. Otherwise the exception type and the in-app frames (module and function, never line numbers, so a deploy that moves code does not split an issue). Frames in node_modules, site-packages, runtimes and internals are library frames.
  3. With no in-app frames, the type and the message with ids, numbers and durations masked.
  4. Then the project's fingerprint rules (Settings), including the ones a merge adds.

Limits and storage

  • A request is at most 200 KB and 100 events; larger answers 413.
  • Counts are exact. Of the events for one issue in one hour, the first 20 are stored in full. Full events are kept 30 days, hourly counts 90 days.
  • An organisation can send 100,000 events an hour (VENOM_ERRORS_HOURLY_CAP on a self-hosted cloud). Over it, ingest answers 429 with retry-after, and the refused events are counted in errors_usage, not stored.
  • Keys are checked through a 30 second cache: a rotated key keeps working for up to that long.
  • Secrets in messages, URLs, breadcrumbs, tags and extra data are replaced with [REDACTED:…] first.
  • The ingest path does not evaluate alerts; spikes are found by the cron from the hourly counts.

From CI

curl -X POST "$ORIGIN/incidents/api/v1/releases?project=default" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H "Content-Type: application/json" \
  -d '{"version":"'$GIT_SHA'","environment":"production","commit":"'$GIT_SHA'"}'

Source maps are uploaded the same way; see Errors.

Self-hosting notes

Apply migration 0155_errors.sql. The hourly cron /api/cron/incidents keeps the event table's daily partitions a week ahead and drops the expired ones; CRON_SECRET must be set. The add-on is sold with STRIPE_PRICE_INCIDENTS_SEAT; without it every organisation has Incidents.