Node.js SDK
Package @hellsoft/vaka-node (source: sdks/node). A thin layer on the standard OpenTelemetry Node SDK:
traces and logs go to Vaka's OTLP endpoint, and the SDK adds what
OpenTelemetry doesn't do well: crash capture, breadcrumbs, per-request user and tags, source
context, release tagging and feature flags. Errors go to the ingest API with the
active trace id, so an agent can move from an issue to its trace and back. Node.js 22.15+.
Agent-followable install guide: /docs/install/node.
npm install @hellsoft/vaka-node
node --import @hellsoft/vaka-node/register server.js # reads VAKA_KEY, VAKA_ENDPOINT, VAKA_RELEASE, ...
or in code, before the framework is imported:
import * as Vaka from '@hellsoft/vaka-node';
Vaka.init({ key: 'vk_...', endpoint: 'https://vaka.example.com', release: '2.4.0' });
Init options
| Option | Default | Meaning |
|---|---|---|
key |
$VAKA_KEY / $VAKA_INGEST_KEY |
Ingest key; missing disables the SDK with a warning |
endpoint |
$VAKA_ENDPOINT |
Server URL |
release |
$VAKA_RELEASE, else $npm_package_version |
App version (service.version on spans) |
environment |
$VAKA_ENVIRONMENT, else $NODE_ENV, else production |
|
serviceName |
$OTEL_SERVICE_NAME, else $npm_package_name |
service.name, and the service tag on errors |
otel |
true |
Start the OpenTelemetry Node SDK. false when you run your own |
tracesSampleRate |
1 ($VAKA_TRACES_SAMPLE_RATE with the preload) |
Share of new traces recorded; an incoming traceparent decision wins |
logs |
true |
Export OpenTelemetry log records |
instrumentations |
HTTP only | e.g. [getNodeAutoInstrumentations()] |
resourceAttributes |
Extra resource attributes | |
captureUnhandled |
true |
Report uncaught exceptions and unhandled rejections |
unhandledRejection |
Node's --unhandled-rejections, else strict |
strict reports and exits 1, warn reports and keeps running, none only reports |
exitOnUncaught |
true |
Exit 1 after an uncaught exception (skipped when the app has its own uncaughtException handler) |
shutdownTimeoutMs |
2000 |
How long a crash waits for delivery |
breadcrumbs |
true |
Console warn/error and outgoing fetch/http requests |
maxBreadcrumbs |
100 |
Per scope |
sourceContext |
true |
Read 5 lines around in-app frames from disk |
errorSampleRate |
1 |
Share of non-fatal errors sent |
ignoreErrors |
Strings or regexes matched against the message | |
shouldCaptureStatus |
status >= 500 |
Which HTTP errors the middleware reports |
flagsCacheTtlMs |
30000 |
Flag evaluations are cached per identity and properties |
beforeSend |
Change or drop (return null) an item |
|
flushIntervalMs |
2000 |
Batching interval; errors are sent at once |
debug |
false |
Log to stderr (VAKA_DEBUG=1 with the preload) |
API
| Call | |
|---|---|
captureException(err, ctx?) (alias captureError) |
Report an error with its cause chain. ctx: level, tags, extra, handled, fingerprint, user. Returns the event id |
captureMessage(msg, level?) |
|
addBreadcrumb({ category, message, level, data }) |
|
setUser(id | { id } | null) |
Opt-in. Also sets enduser.id on the active span |
setTag(k, v), setTags({}), setContext(name, obj) |
|
withScope(fn) |
Run fn with a copy of the current scope |
track(name, props?, { userId? }) |
Server-side product event |
getFlags(ctx?), getFlag(key, fallback?, ctx?), isEnabled(key, ctx?) |
Evaluate flags (see below) |
traceId() |
Active trace id |
flush(ms?), close(ms?) |
Send queued data; close also shuts OpenTelemetry down |
requestHandler(), errorHandler(), fastifyPlugin, wrapHandler(fn) |
Middleware |
vakaSpanExporter(), vakaLogRecordProcessor(), VakaScopeSpanProcessor |
For your own NodeSDK |
Scopes
User, tags, contexts, breadcrumbs and flags live on a scope. Outside a request it is a global
scope; the middleware (and withScope/wrapHandler) gives every request its own copy via
AsyncLocalStorage, so breadcrumbs from one request never show up on another request's error.
Errors
Error items use platform: "node", frames crash site first with module (express:lib/router
for packages, the relative path for app files), in_app: false for node_modules and Node
internals, and context_line/pre_context/post_context read from disk. They carry
contexts.runtime, contexts.os, contexts.request (method, URL without query, route, query
string and a few safe headers; never cookies or Authorization), the server_name and
transaction tags (GET /users/:id), trace_id, user and flags.
When the SDK reports an error inside a span it sets vaka.error_captured: true on that span, so
the server doesn't also turn the span's exception event into a second error.
Uncaught exceptions are sent with fatal: true, then the SDK prints the stack, waits up to
shutdownTimeoutMs for delivery and exits with code 1, the same outcome as without Vaka.
Feature flags
app.get('/checkout', async (req, res) => {
Vaka.setUser(req.user.id);
const variant = await Vaka.getFlag('new_checkout', 'control', { properties: { plan: req.user.plan } });
// ...
});
Evaluation uses POST /ingest/v1/flags with the scope's user id as distinct_id (or pass
distinctId). The values are added to the current scope, so errors and events in that request
carry them as exposures, and the active span gets feature_flag.<key> attributes. On failure
getFlag returns the fallback. See flags.
Cron jobs (heartbeat monitors)
Report each run of a job to a heartbeat monitor. Vaka alerts when a run is missed, fails or runs too long.
import { withMonitor, checkIn } from '@hellsoft/vaka-node';
// in_progress, then ok with the duration, or error (the exception is captured and rethrown).
// With a config, the monitor is created on first use.
await withMonitor('nightly-backup', () => backup(), { schedule: { cron: '0 3 * * *', timezone: 'Europe/Stockholm' } });
await checkIn('hourly-sync'); // a single ok
await checkIn('hourly-sync', 'error', { message: 'upstream down' });
Errors captured during a run carry the tag monitor.check_in_id, so the incident shows them.
checkIn resolves to false instead of throwing when the check-in fails.
User feedback
Forward what users wrote in your own forms (support, contact, in-app chat). It is sent right away with the scope's user, tags and flags.
app.post('/support', async (req, res) => {
const r = await Vaka.captureFeedback({
message: req.body.message,
email: req.body.email, // optional contact
issue: req.body.issue, // optional: 'API-12', or eventId from captureException
ip: req.ip,
attachments: req.file ? [{ filename: req.file.originalname, data: req.file.buffer }] : [],
});
res.json({ ticket: r.shortId }); // 'API-F12'
});
Fields: message (required), email, name, eventId, issue, userId, sessionId, url
(defaults to the request URL), ip, tags, attachments (up to 3 PNG, JPEG or WebP images of
5 MB). It rejects with a FeedbackError whose status is the HTTP status (429: rate limited).
Link it to a crash with the event id from a capture call, or to an issue by its short id (API-12). Pass the end user's IP address: feedback is rate limited per address (10 an hour by default), so without it all feedback from your server shares one limit. Vaka believes the address only from backends on a private network or listed in VAKA_TRUSTED_PROXIES. Rejected feedback raises an error with the HTTP status; 429 means a limit was hit. See user feedback.
Frameworks
Express: app.use(Vaka.requestHandler()) before routes, app.use(Vaka.errorHandler()) after.
Fastify: await app.register(Vaka.fastifyPlugin). Koa, Hono, plain http, Lambda: wrap the
handler with Vaka.wrapHandler(fn) and call captureException in your error middleware. For
spans with route names, add @opentelemetry/auto-instrumentations-node (or the single
instrumentation for your framework) to instrumentations.
Bring your own OpenTelemetry
import { NodeSDK } from '@opentelemetry/sdk-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace';
import * as Vaka from '@hellsoft/vaka-node';
const cfg = { endpoint: 'https://vaka.example.com', key: 'vk_...' };
new NodeSDK({
spanProcessors: [new Vaka.VakaScopeSpanProcessor(), new BatchSpanProcessor({ exporter: Vaka.vakaSpanExporter(cfg) })],
logRecordProcessors: [Vaka.vakaLogRecordProcessor(cfg)],
}).start();
Vaka.init({ ...cfg, otel: false, release: '2.4.0' });
Or skip the SDK's OpenTelemetry entirely and point standard OTEL_EXPORTER_OTLP_* variables at
Vaka (opentelemetry.md); @hellsoft/vaka-node then only adds error capture.
ES modules
The preload (--import @hellsoft/vaka-node/register) also registers OpenTelemetry's ESM loader hook, so
import express from 'express' is instrumented. With an instrument.mjs of your own, load it
with --import and register the hook yourself if you need ESM instrumentation:
module.register('@opentelemetry/instrumentation/hook.mjs', import.meta.url).
Source maps
Use node --enable-source-maps: stacks are already mapped to the original files, and source
context comes from those files.