Node.js servers and APIs
For an API or any backend without pages of its own, install the SnowAnalytics package for servers. It reports the errors your routes throw, sends server-side events, says which user a visitor is, and checks in your cron jobs. It works on Node 18 and later, Bun and Deno.
Create a server key
Open Site settings → API keys. Under Server keys, click Create key and copy it. It is shown once. Put it
in an environment variable called SNOW_API_KEY.
Install the package
npm install @kapybara/snowanalyticsCall init at startup
Put it in a file of its own and import that file first in your entry, before anything that loads your database client:
import { init } from "@kapybara/snowanalytics/node";
init({ release: process.env.GIT_SHA });import "./instrument";
// the rest of your importsinit reads SNOW_API_KEY, or takes apiKey directly. It also reports errors nothing caught: unhandled promise
rejections and uncaught exceptions. Without a key every call does nothing, so local runs and tests stay quiet.
Add your framework's handler
Pick yours below. The handler reports a failed request with its method, route pattern (like /users/:id, so one
bug is one issue in Errors, not one per user) and status. Your own error handling still answers the request.
Only failures are issues: a 5xx, or an error without a status. A thrown 4xx, such as a validation error, a not found or
a rate limit, is the client's mistake and is left out. Set reportClientErrors: true in init to report those too.
Framework handlers
snowExpress() goes first, so each request keeps its own breadcrumbs; the error handler goes after your routes and
before your own. Express 4 and 5.
import { expressErrorHandler, snowExpress } from "@kapybara/snowanalytics/node";
app.use(snowExpress());
// your routes
app.use(expressErrorHandler());
app.use((error, request, response, next) => response.status(500).json({ error: "Something went wrong" }));Your own errors
Report an error you caught yourself, with tags to group or search by:
import { captureException } from "@kapybara/snowanalytics/node";
try {
await chargeCard(order);
} catch (error) {
await captureException(error, { tags: { orderId: order.id } });
}Name the person it happened to with user, and their visits and payments show beside the error:
await captureException(error, { user: { id: request.user.id }, request: { method, path, status: 500 } });Breadcrumbs
Each report lists what happened right before it, the way Sentry does. Without any code you get:
- Outgoing HTTP calls through
fetchornode:http/node:https(axios, got and most API clients): the method, the address without its query string, the status and how long it took. A 4xx shows in the warning colour, a 5xx or a call with no answer in red. - Database queries on Node: Postgres through
pg(so Drizzle, Kysely, Knex andpg.Pool) and Redis throughioredis5.11 or later. A query shows its SQL with the$1placeholders, never the values, and a Redis command shows only the arguments that can't hold data (SET plan:42 ?). Each has its time, and a failed one its error. This needsinitto run beforepgloads; if it can't, the SDK says so in the console once. console.warnandconsole.errorlines.
With the framework handlers, each request keeps its own: an error lists what that request did, not what other requests did at the same moment. Outside a request (a job, a script) the last 30 seconds are listed.
Add your own steps with addBreadcrumb, and turn the automatic ones off with init({ breadcrumbs: false }), or one
kind with init({ breadcrumbs: { database: false } }):
import { addBreadcrumb } from "@kapybara/snowanalytics/node";
addBreadcrumb({ type: "network", text: "POST https://api.stripe.com/v1/charges", status: 402, ms: 310 });Filter what's sent
beforeSend sees every report first. Return it (changed or not) to send it, or null to drop it:
init({
beforeSend: (report) =>
report.message.includes("rate limited") ? null : { ...report, tags: { ...report.tags, region: "eu" } },
});Delivery
Reports wait 200 ms so a burst goes out as a few requests, and a network failure, a 429 or a 5xx is tried twice more.
Each report has its own id, so a retry is never counted twice. The same error within 5 seconds is sent once. A
rejected promise is reported whatever it rejected with, not only an Error.
Events and users
track sends a custom event from the server, such as a signup or an API call that matters.
Name the user so it joins their visits.
import { identify, track } from "@kapybara/snowanalytics/node";
await track("api_key_created", { userId: user.id, properties: { plan: "pro" } });identify says which signed-in user a visitor is. Pass the visitor id the browser tracker sent with the request:
await identify(visitorId, {
userId: user.id,
email: user.email,
name: user.name,
traits: { plan: "pro", company: "Acme" },
});Cron jobs
cron.wrap checks a job in when it starts and when it ends, with how long it took. A job that throws is reported
and fails its check-in. Give it a schedule and the monitor is created on the first run. See
Cron check-ins.
import { cron } from "@kapybara/snowanalytics/node";
await cron.wrap("nightly-invoices", () => sendInvoices(), { schedule: "0 2 * * *" });Scripts and serverless functions
A process that exits right after its work can quit before the last report is sent. Call flush first:
import { flush } from "@kapybara/snowanalytics/node";
await flush();Settings
| Option | Environment variable | What it does |
|---|---|---|
apiKey | SNOW_API_KEY | The server key. |
release | SNOW_RELEASE | The build or version, so Errors says which release broke. |
environment | SNOW_ENVIRONMENT, then NODE_ENV | production, staging and so on. |
url | SNOW_URL | Your SnowAnalytics address, if not api.snowanalytics.app. |
captureUnhandled | Set to false to leave uncaught errors alone. | |
beforeSend | Changes or drops each report before it goes. | |
reportClientErrors | Set to true to report thrown 4xx answers as well as 5xx. | |
breadcrumbs | false turns the automatic ones off; { http, database, console } picks. |