@bugwalk/node

Node.js SDK for Bugwalk. Records requests and errors on your server and joins them to what the person was doing in the browser at the time.

Most apps should install their framework's adapter instead, which wires this up for them: @bugwalk/express, @bugwalk/nestjs, @bugwalk/fastify, @bugwalk/hono, @bugwalk/koa, or @bugwalk/next.

Install

npm install @bugwalk/node

Use

import { init, identify, capture } from '@bugwalk/node';

init(); // reads BUGWALK_DSN, NODE_ENV, and BUGWALK_RELEASE from the environment

// anywhere inside a request
identify({ id: user.id, email: user.email });
capture('invoice_generated', { invoiceId });

identify and capture attach to the request they were called in, however deep in the call stack that is. No context object needs threading through your code.

Cron, queues, and other background work

withWork names the run (cron, queue, or task). Leave out a person and the run is unscoped. forPerson attributes one iteration to a user, using the same id and email as identify, then clears them so the next iteration does not inherit them.

import { withWork, forPerson } from '@bugwalk/node';

await withWork({ id: 'daily-digest', kind: 'cron' }, async () => {
  for (const user of users) {
    await forPerson({ id: user.id, email: user.email }, async () => {
      await sendDigest(user);
    });
  }
});

Work for a person that is not a job is just forPerson. Express, Fastify, Koa, Hono, and @bugwalk/next/server re-export both functions.

How a journey is joined

The browser SDK sends two headers with each request:

| Header | Purpose | | --- | --- | | traceparent | W3C trace context, so this request continues the browser's trace | | x-bugwalk-session | The visit, so a failed API call lands on the right person's timeline |

Requests with neither — cron jobs, webhooks, service-to-service calls — get a fresh session each, so they stay grouped per request rather than piling into one endless session.

Instrumenting a framework we do not cover

import { withRequest, finishRequest, getClient } from '@bugwalk/node';

const input = { method: req.method, url: req.url, headers: req.headers, route: '/orders/:id' };

await withRequest(input, async (scope) => {
  try {
    const response = await handle(req);
    finishRequest(getClient()!, scope, input, { statusCode: response.status });
    return response;
  } catch (error) {
    finishRequest(getClient()!, scope, input, { statusCode: 500, error });
    throw error;
  }
});

That is the whole of every adapter in this repo. If you write one for another framework, a pull request is welcome.

Handled failures in logs

By default, console.error is mirrored to Bugwalk as warnings: they show on the person's journey when the failure was caught and the request still returned 2xx, without opening a new issue. Terminal output is unchanged. Set captureLogErrors: false in init to turn this off.

Shutdown

No SIGTERM handler is installed. Attaching one suppresses Node's default termination, and an SDK that quietly changed how your process shuts down would be a bad neighbour. Flush in your own handler:

process.on('SIGTERM', async () => {
  await shutdown();
  server.close();
});

@bugwalk/nestjs does this for you through onApplicationShutdown.

Redaction

Authorization headers, cookies, password-like keys, card numbers, and tokens are stripped in your process, before anything is sent. Request and response bodies are not collected unless you set captureBodies: true. See the redaction rules.

Apache-2.0