Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trodo.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

When you initialise the Node or Python SDK with autoEvents: true / auto_events=True, Trodo installs process-wide exception hooks and emits a single server_error event whenever your backend crashes or rejects an unhandled promise. This is the server-side counterpart to the browser SDK’s js_error capture — far more targeted than browser auto-events because your backend typically doesn’t have page views, clicks, or scrolls.
Server auto-events capture only uncaught exceptions. Everything else — domain events, API calls, background jobs — goes through track().

​
Enable

import trodo from 'trodo-node';

trodo.init({
  siteId: process.env.TRODO_SITE_ID,
  autoEvents: true,
});

// Or toggle at runtime:
trodo.enableAutoEvents();
trodo.disableAutoEvents();
Trodo registers handlers on:
  • process.on('uncaughtException')
  • process.on('unhandledRejection')

​
The server_error event

Every uncaught exception emits a single event with the following shape: 
{
  "event_name": "server_error",
  "event_type": "auto",
  "distinct_id": "server_global",
  "custom_properties": {
    "error_type": "TypeError",
    "error_message": "Cannot read properties of undefined (reading 'id')",
    "stack_trace": "TypeError: Cannot read properties...\n    at handler (/app/src/routes/users.ts:42:18)",
    "runtime": "nodejs"
  }
}
PropertyDescription
error_typeException class name (TypeError, ValueError, RuntimeError, …)
error_messageThe exception message
stack_traceFull stack trace as a string
runtime"nodejs" or "python" — identifies which backend emitted the event

​
Why distinct_id = "server_global"?

Uncaught exceptions fire outside any request context. There is no user to attribute them to, so the SDK uses the synthetic id server_global. In the dashboard, filter by distinct_id = server_global to see every backend crash. If you want a crash attributed to a specific user, catch the exception and use manual error capture instead.

​
Manual error capture

For handled exceptions inside a request where you already know the user, use captureError / capture_error on a user context. It emits the same server_error event but attaches the real distinctId. 
try {
  await chargeCustomer(userId, amount);
} catch (err) {
  await trodo.forUser(userId).captureError(err, 'error');
  throw err;
}
Severity accepts 'critical' | 'error' | 'warning' (default 'error').

​
Shutdown

Auto-event handlers stay installed for the lifetime of the process. On graceful termination, call shutdown() to remove them and flush any queued events: 
process.on('SIGTERM', async () => {
  await trodo.shutdown();
});

​
What’s not captured

  • HTTP 4xx/5xx responses — those are application behaviour, not exceptions. Track them explicitly with track('api_error', { status, route }).
  • Database connection pool warnings, deprecation notices, log output — not exceptions, not captured.
  • Exceptions you catch and handle — unless you call captureError / capture_error yourself.
  • Signals (SIGKILL, SIGTERM) and OOM kills — the process dies before a handler can fire. Use your orchestrator’s crash reporting for these.

​
Next

Client-side auto-events

Page views, clicks, forms, media, errors in the browser

Track custom events

Instrument your own backend signals