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.
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
- A
fingerprintarray from the SDK wins. - 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. - With no in-app frames, the type and the message with ids, numbers and durations masked.
- 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_CAPon a self-hosted cloud). Over it, ingest answers429withretry-after, and the refused events are counted inerrors_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.