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+.
npm install @fictura/nodeWire it
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.
| Option | Environment | Default |
|---|---|---|
apiKey | FICTURA_API_KEY (Dashboard → Setup → SDK app key) | none |
apiBase | FICTURA_API_BASE | https://api.fictura.co |
release | FICTURA_RELEASE, else RAILWAY_GIT_COMMIT_SHA | none |
environment | FICTURA_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:
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
app.use(fictura.requestHandler()); // first, before your routes and auth
// ... your routes ...
app.use(fictura.errorHandler()); // after your routesFailed 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
| Option | Default | |
|---|---|---|
captureConsole | false | Also report plain-text console.error lines. |
capture5xx | true | Report 5xx responses your code sent. |
sampleRate | 1 | Share of error events sent. Fatal crashes always go. |
tracesSampleRate | 1 | Share of traces recorded. null turns tracing off. |
requestSessions | true | Per-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.