Fictura
Error tracking

Node

npm install @fictura/node, a few lines, and crashes, failed requests and the errors you already log become issues.

For Express, Fastify, or any Node service. Zero dependencies, Node 18+.

Install
npm install @fictura/node

Wire it

TypeScript
import * as fictura from "@fictura/node";

fictura.init({ serviceName: "api" });

init() reads the rest from the environment. Without a key nothing is captured or sent, and under a test runner it stays off unless you pass enabled: true.

OptionEnvironmentDefault
apiKeyFICTURA_API_KEY (Dashboard → Setup → SDK app key)none
apiBaseFICTURA_API_BASEhttps://api.fictura.co
releaseFICTURA_RELEASE, else RAILWAY_GIT_COMMIT_SHAnone
environmentFICTURA_ENVIRONMENT, else RAILWAY_ENVIRONMENT_NAME"production"

What gets captured

Crashes and failed awaits — uncaughtException and unhandledRejection. Your process still dies on an uncaught error with the same exit code; adding a listener normally suppresses that, so we put it back. A rejection follows Node's --unhandled-rejections mode. And every console.error(...) you already write with an Error in its arguments:

TypeScript
try {
  await stripe.charges.create(payload);
} catch (e) {
  console.error("charge failed", e);   // ← already reported
  return retryLater();
}

A plain-text console.error("…") line is not an issue: it is kept as a breadcrumb on the next error, because most of those lines are other libraries logging. Set captureConsole: true to send them as issues too.

Anything explicit: fictura.captureException(e, { route: "/api/v1/generate", userId: user.id }) or fictura.captureMessage("…", "warning"). An error that is both logged and thrown is reported once.

Express

TypeScript
app.use(fictura.requestHandler());   // first, before your routes and auth
// ... your routes ...
app.use(fictura.errorHandler());     // after your routes

Failed requests then carry their route template, user id and status. A 5xx your own code sent (res.status(500).json(...)) is reported too, once per request; a 4xx is not an issue. The error passes through to your own handler untouched.

The user is read when the error is captured, from req.user.id and similar. A value that looks like an email address is dropped; pass getUserId: (req) => … to init to say exactly.

For Fastify, await app.register(fictura.fastifyPlugin). For plain http, wrap your listener in fictura.httpHandler(...).

Traces and request health

init() traces every request by default and sends the spans to the Performance page. Each request also counts as a session, for a crash-free request rate per release on the Releases page.

Options & guarantees

OptionDefault
captureConsolefalseAlso report plain-text console.error lines.
capture5xxtrueReport 5xx responses your code sent.
sampleRate1Share of error events sent. Fatal crashes always go.
tracesSampleRate1Share of traces recorded. null turns tracing off.
requestSessionstruePer-minute ok, errored and crashed counts.
beforeSend—Change an event, or return null to drop it.
environment"production"Keeps staging noise out of production's list.
release—Which deploy an error came from.

Never throws into your app, never blocks a response: bounded queue that drops oldest-first, 2s HTTP timeout, no retry storms. Secrets are scrubbed before anything leaves the process. The flush timer is unref'd, so a finished script still exits when it should.

Upgrading from 0.1

new Fictura({ apiBase, apiKey, release, environment }), install() and errorHandler() still work. Two defaults changed: plain-text console.error lines are breadcrumbs now, and an unhandled rejection no longer keeps alive a process that Node would have ended. Add requestHandler() first in the chain for route templates, users, handled 5xx, traces and request sessions.

On this page