@upgoose/node

Error tracking for Node.js servers, from Upgoose.

Zero dependencies. Node 18+.

Install

npm install @upgoose/node

Use

Call init() once, as early as possible:

import * as Upgoose from "@upgoose/node";

Upgoose.init({
  dsn: process.env.UPGOOSE_DSN,
  environment: process.env.NODE_ENV ?? "production",
  release: process.env.BUILD_SHA,
});

With Express, register the error handler after all routes. It reports the error with its request context and passes it on, so your own error handling is unchanged:

app.use(Upgoose.errorHandler());

Report by hand anywhere:

try {
  await chargeCard(order);
} catch (err) {
  Upgoose.captureException(err, { orderId: order.id });
  throw err;
}

Crashes

Uncaught exceptions and unhandled rejections are reported by default. The report is sent before the process exits (waiting at most 2 seconds), and then the process exits exactly as Node would have: the error is printed and the exit code is 1. A crash is never swallowed. If your app installs its own uncaughtException or unhandledRejection handler, that handler decides what happens next.

Turn this off with captureUncaught: false.

Shutdown and serverless

Reports are sent in the background. Before a graceful shutdown, or at the end of a serverless handler, wait for them:

await Upgoose.flush(); // resolves false if it hit the 2s timeout

What is sent

The error message and stack, your environment and release, and for errors caught by errorHandler() the request method, path, user agent and x-request-id. Headers are never sent wholesale, so cookies and bearer tokens stay on your server, and the query string is dropped from the path. Use beforeSend to redact or drop anything else:

Upgoose.init({
  dsn: process.env.UPGOOSE_DSN,
  beforeSend: (event) => (event.message.includes("ECONNRESET") ? null : event),
});

The DSN key

The key in the DSN is write-only and publishable: it is the same kind of key a browser bundle ships. Give server-side services their own Upgoose project rather than reusing the browser project's DSN, so browser and server errors don't share one key and one release timeline.

License

BSD-3-Clause