testvibe-telemetry

Drop-in server telemetry for Node.js applications. Reports your server's CPU, memory, an optional session count, and application errors to TestVibe — so you can see why the server behaves the way it does under load.

Server vitals render in your load test results, right next to the client-side charts; application errors are grouped and persisted under Dashboard → Telemetry → Errors & exceptions.

The agent polls for active runs while idle and sends samples while a load run is active. Error reports are independent of load runs. It has no dependencies; network failures are handled in the background and each request is bounded to 10 seconds. Polling timers do not keep an otherwise finished process alive.

Running .NET? Use the TestVibe.Telemetry NuGet package instead.

Install

npm install testvibe-telemetry

Requires Node.js 18+ (uses the built-in fetch).

Quick start

Start the agent once at boot with your TestVibe server URL, a workspace API key (TestVibe → Settings → CLI & API keys), and your project id (shown in Settings → Telemetry):

const { startTestVibeLoadAgent } = require('testvibe-telemetry');

startTestVibeLoadAgent({
  server: 'https://app.testvibe.com',
  apiKey: 'tvb_…',                    // Settings → CLI & API keys
  project: '<your-project-id>',       // Settings → Telemetry
  sessions: () => myActiveSessions,   // optional — unlocks Sessions & Memory/session
});

That's it. The agent quietly polls TestVibe and, while a load run is active for your project, samples every ~2 seconds and streams CPU, memory, and sessions into the run's results.

Options

| Option | Required | Description | | --- | --- | --- | | server | yes | TestVibe server URL, e.g. https://app.testvibe.com. | | apiKey | yes | Workspace API key (tvb_…). | | project | yes | Project id from Settings → Telemetry. | | source | no | Label for this server in the results (default: hostname). | | sessions | no | () => number — live session count callback. | | sampleSeconds | no | Seconds between samples during a run (default 2). | | idleSeconds | no | Seconds between polls while idle (default 10). | | captureErrors | no | Observe fatal exceptions without changing Node's exit behavior (default true). |

Application errors

The agent observes fatal exceptions through Node's uncaughtExceptionMonitor, including unhandled rejections that Node raises as exceptions. It preserves Node's normal crash behavior. Delivery at process exit is best-effort and is not guaranteed; report handled errors through the returned handle while the app is running. If your app installs its own rejection handler, call reportError there.

const telemetry = startTestVibeLoadAgent({ /* … */ });

try {
  doWork();
} catch (err) {
  telemetry.reportError(err);
  throw err;
}

Opt out of automatic capture with captureErrors: false.

Call telemetry.stop() during shutdown or when replacing the agent. It cancels pending requests, removes the error monitor, and discards any unsent reports.

License

Copyright © ICE TEA GROUP LLC. All rights reserved.