Node.js Support

• Quick Start
• Capture Errors
• Capture Messages
• Console Log Patching
• Context

Quick Start

The @understand/understand-js package supports Node.js environments in addition to the browser.

Install via npm:

npm install @understand/understand-js

Then initialise as early as possible in your application:

const Understand = require('@understand/understand-js');

Understand.init({
  env: 'production',
  token: '<your-input-token>'
}).catchErrors();

Capture Errors

Handled exceptions can be sent manually using logError:

try {
  throw new Error('Node.js test error');
} catch (e) {
  Understand.logError(e);
}

You can also attach custom metadata as a second argument:

try {
  throw new Error('Database connection failed');
} catch (e) {
  Understand.logError(e, { db_host: 'localhost', retry_count: 3 });
}

Capture Messages

Send structured log messages using logMessage:

Understand.logMessage('Server started successfully', 'info');
Understand.logMessage('Cache miss for key: user_42', 'debug');
Understand.logMessage('Disk usage above 90%', 'warning');

Available severity levels: fatal, error, warning, info, debug.

You can also attach metadata:

Understand.logMessage('Payment processed', 'info', { order_id: 1234, amount: 99.99 });

Console Log Patching

Automatically capture all console output as structured events:

Understand.patchConsoleLogs({
  enableConsoleLog: true,
  enableConsoleInfo: true,
  enableConsoleWarn: true,
  enableConsoleDebug: true
});

console.log('User clicked a button');   // captured as "log" level
console.info('App initialized');        // captured as "info" level
console.warn('Deprecated API call');    // captured as "warn" level
console.debug('Value of x:', 42);       // captured as "debug" level
console.error('Something went wrong');  // captured as "error" level

Set any flag to false to disable capturing that specific level.

Context

All context features available in the browser version work in Node.js too. You can set context at init time or using setters:

Understand.init({
  env: 'production',
  token: '<your-input-token>',
  context: {
    request_id: '<uuid>',
    session_id: '<hashed-session-id>',
    user_id: 42,
    client_ip: '141.93.46.10'
  }
});

Or dynamically per request (useful in Express middleware, for example):

app.use((req, res, next) => {
  Understand.withContext(function (context) {
    context.setUserId(req.user?.id);
    context.setClientIp(req.ip);
  });
  next();
});

See the API reference for the full list of context setters.