Connect Node.js to Bugsink
When a Node.js application fails, Bugsink gives you the exception, JavaScript stack trace, and context you need to investigate it.
This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting an existing application and triggering a deliberate error to confirm that it reaches Bugsink.
To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the SDK
Install the open-source Sentry SDK for Node.js. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:
npm install @sentry/nodenpm install @sentry/node
Configure your DSN
Import and initialize the SDK before the rest of your application. Reading the DSN from the environment keeps it out of source control:
import * as Sentry from "@sentry/node"; :::javascript function configureErrorReporting() { Sentry.init({ dsn: process.env.SENTRY_DSN, }); }import * as Sentry from "@sentry/node"; :::javascript function configureErrorReporting() { Sentry.init({ dsn: process.env.SENTRY_DSN, }); }
Call configureErrorReporting() at the beginning of normal startup, and set
SENTRY_DSN in the environment where the application runs:
export SENTRY_DSN=https://key@bugsink.example/1export SENTRY_DSN=https://key@bugsink.example/1
Send a test error
Temporarily add an exception to a code path you can run:
throw new Error("Bugsink setup check");throw new Error("Bugsink setup check");
Run that code path once. The exception still terminates the request or process normally; the SDK reports it to Bugsink.
See the error in Bugsink
Open your Bugsink project. The new Error issue contains the JavaScript stack
trace and points at the line that raised the exception.
Error
That’s it: your Node.js application is connected. Remove the deliberate exception. Bugsink will capture future uncaught exceptions and unhandled promise rejections automatically.
Capture other kinds of errors
Unhandled failures arrive automatically. You can also report exceptions your code catches and exceptional conditions that do not have an exception.
Handled exceptions
A handled exception can still be worth investigating. Pass the caught error to
captureException() when the application can recover but you want its stack
trace and context. Handled Errors explains when this
is useful in more depth:
try { processOrder(orderId, 0); } catch (error) { Sentry.captureException(error); }try { processOrder(orderId, 0); } catch (error) { Sentry.captureException(error); }
Bugsink preview: handled exception
OrderQuantityError
Messages without exceptions
A message creates a Bugsink event without requiring an exception. Use
captureMessage() for an exceptional condition such as an unresponsive queue,
and pass the severity Bugsink should show. Prefer exceptions when a stack trace
from the actual failure is available:
Sentry.captureMessage(`Order queue is not responding [${orderId}]`, "error");Sentry.captureMessage(`Order queue is not responding [${orderId}]`, "error");
error Order queue is not responding [node-message]Bugsink preview: captured message
Log Entry
For short-lived commands, call await Sentry.flush(5000) before exiting so
queued events have time to be sent. Servers normally send them in the
background.
Add useful context
An exception tells you what failed; context helps explain why. Context added to the current scope is attached to subsequent events.
Tags
Tags make events searchable by short key/value pairs. Use setTag() for your
own component, region, plan, or feature flag. This adds component: orders to
later events on the current scope:
Sentry.setTag("component", "orders");Sentry.setTag("component", "orders");
ordersBugsink preview: component tag
Tags
Structured context
Structured context adds a named group of details to an event. Use it for values you want to inspect but not search, such as the order or job being processed:
Sentry.setContext("order", { id: orderId, quantity });Sentry.setContext("order", { id: orderId, quantity });
node-handled 0Bugsink preview: structured context
Contexts
ORDER
Breadcrumbs
Breadcrumbs record what happened before an error. Call addBreadcrumb() for
steps the SDK cannot know about, such as starting checkout or retrying an
external call. The next error includes it:
Sentry.addBreadcrumb({ category: "order", message: "Starting order processing", data: { orderId }, level: "info", });Sentry.addBreadcrumb({ category: "order", message: "Starting order processing", data: { orderId }, level: "info", });
Bugsink preview: breadcrumb
order
Starting order processing
event time
JavaScript frameworks
Server and browser integrations capture failures in their normal request or rendering lifecycle and add the relevant context automatically.
