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/snowanalytics

Call 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:

instrument.ts
import { init } from "@kapybara/snowanalytics/node";

init({ release: process.env.GIT_SHA });
server.ts
import "./instrument";
// the rest of your imports

init 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 } });

Each report lists what happened right before it, the way Sentry does. Without any code you get:

  • Outgoing HTTP calls through fetch or node: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 and pg.Pool) and Redis through ioredis 5.11 or later. A query shows its SQL with the $1 placeholders, 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 needs init to run before pg loads; if it can't, the SDK says so in the console once.
  • console.warn and console.error lines.

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

OptionEnvironment variableWhat it does
apiKeySNOW_API_KEYThe server key.
releaseSNOW_RELEASEThe build or version, so Errors says which release broke.
environmentSNOW_ENVIRONMENT, then NODE_ENVproduction, staging and so on.
urlSNOW_URLYour SnowAnalytics address, if not api.snowanalytics.app.
captureUnhandledSet to false to leave uncaught errors alone.
beforeSendChanges or drops each report before it goes.
reportClientErrorsSet to true to report thrown 4xx answers as well as 5xx.
breadcrumbsfalse turns the automatic ones off; { http, database, console } picks.

On this page