vaka
CI statusLatest releaseGitHub

Install Vaka in a Node.js service

Project: your-project · Endpoint: https://vaka.example.com · Ingest key: vk_your_ingest_key

These steps are written to be followed by a coding agent. Do them in order and verify at the end. Requires Node.js 22.15 or later.

1. Install

npm install @hellsoft/vaka-node

Optional, for Express, Fastify, Koa, databases, Redis, queues and more in your traces:

npm install @opentelemetry/auto-instrumentations-node

2. Initialize before the app loads

OpenTelemetry can only instrument modules loaded after it starts, so Vaka must start first. Pick one:

Option A: preload (no code change). Set the environment and add a flag to the start command:

export VAKA_KEY=vk_your_ingest_key
export VAKA_ENDPOINT=https://vaka.example.com
export VAKA_RELEASE=REPLACE_WITH_APP_VERSION     # e.g. the git sha or package version
export VAKA_ENVIRONMENT=production
export OTEL_SERVICE_NAME=REPLACE_WITH_SERVICE_NAME
node --import @hellsoft/vaka-node/register dist/server.js    # CommonJS apps: --require @hellsoft/vaka-node/register

In package.json scripts this is "start": "node --import @hellsoft/vaka-node/register dist/server.js". Release defaults to npm_package_version when started through npm.

Option B: an instrument file. Create instrument.mjs (or .ts) and load it with --import ./instrument.mjs, or require('./instrument') as the very first line of a CommonJS entry point:

import * as Vaka from '@hellsoft/vaka-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; // optional

Vaka.init({
  key: 'vk_your_ingest_key',
  endpoint: 'https://vaka.example.com',
  release: process.env.APP_VERSION,     // must match the release used for source map uploads
  environment: process.env.NODE_ENV,
  serviceName: 'api',
  instrumentations: [getNodeAutoInstrumentations()],   // omit for HTTP only
});

If the app already runs its own OpenTelemetry NodeSDK, pass otel: false and add the Vaka exporters to it instead (see sdk-node).

3. What you get automatically

4. Add the framework middleware

Express (after Vaka.init):

app.use(Vaka.requestHandler());   // first: isolates breadcrumbs, user and tags per request
// ... routes ...
app.use(Vaka.errorHandler());     // after routes, before your own error handler

Fastify:

await app.register(Vaka.fastifyPlugin);

Anything else (plain http, serverless): wrap the handler with Vaka.wrapHandler(fn). Errors with status 500 and above are reported; change it with shouldCaptureStatus.

5. Optional calls

Vaka.captureException(err, { tags: { area: 'billing' } });   // handled error
Vaka.captureMessage('Payment provider slow', 'warning');
Vaka.addBreadcrumb({ category: 'job', message: 'import started' });
Vaka.setTag('tenant', 'acme');
Vaka.setUser(req.user.id);                 // opt-in; per request inside the middleware
Vaka.track('order_paid', { amount: 49 });  // server-side product event
if (await Vaka.isEnabled('new_checkout')) { /* ... */ }   // feature flag for the scope's user

Call await Vaka.close() before a deliberate process.exit() so queued data is sent.

6. Source maps (TypeScript or bundled code)

Start Node with --enable-source-maps so stack traces point at the original .ts files; Vaka then reads source lines from disk where they exist. Nothing to upload.

7. Verify

VAKA_KEY=vk_your_ingest_key VAKA_ENDPOINT=https://vaka.example.com VAKA_RELEASE=test node -e "
const Vaka = require('@hellsoft/vaka-node');
Vaka.init({ otel: false });
Vaka.captureMessage('vaka install test', 'info');
Vaka.close().then((ok) => console.log(ok ? 'sent' : 'NOT sent'));"

It prints sent. Then check vaka issues -p your-project (or the MCP tool list_issues). Set debug: true (or VAKA_DEBUG=1 with the preload) to log what the SDK sends.