Skip to main content
The HyperProbe Node.js SDK runs as a lightweight in-process agent that connects your application to the HyperProbe broker. Once initialized, it listens for probes set via the VS Code extension and captures telemetry — variable snapshots, logs, counters, and metrics — without pausing execution or requiring a redeploy.

​
Prerequisites

  • Node.js 18 or later
  • A running HyperProbe broker (URL provided by your team or HyperProbe cloud setup)
  • The git commit SHA of the deployed build (required for source map resolution)

​
Installation

Install the SDK using your preferred package manager: 
npm install @hyperprobe/node-sdk

​
Quick start

1

Initialize the agent at your entry point

Call HyperProbe.start() at the very top of your application’s entry file — before any other imports or framework setup. This ensures the agent is active before any code that you may want to instrument runs.
index.ts
import { HyperProbe } from '@hyperprobe/node-sdk';

HyperProbe.start({
  serviceId: 'payment-service',
  environment: 'production',
  brokerUrl: 'grpc://hyperprobe-broker.internal:50051',
  commitSha: process.env.GIT_COMMIT,
});
Place HyperProbe.start() before your framework initialization (e.g., Express, Fastify, NestJS). If the agent starts after your application code is loaded, probes on early-executing code may not be captured.
2

Supply the commit SHA

HyperProbe requires a valid commitSha to resolve source maps and match probes to the exact version of code running in production. Without it, the agent refuses to start.You can supply it in one of two ways:Option 1 — Pass it directly in code:
index.ts
HyperProbe.start({
  serviceId: 'payment-service',
  environment: 'production',
  brokerUrl: 'grpc://hyperprobe-broker.internal:50051',
  commitSha: 'a3f92c1d',
});
Option 2 — Set the GIT_COMMIT environment variable (recommended):Most CI/CD systems expose the commit SHA as an environment variable. Inject it at deploy time so your code stays clean:
GIT_COMMIT=$(git rev-parse HEAD) node dist/index.js
The SDK reads process.env.GIT_COMMIT automatically if commitSha is not passed in options.
If commitSha is missing or set to the string 'unknown', the agent logs a critical error and does not start. Check your deployment pipeline to ensure GIT_COMMIT is always set.
3

Handle graceful shutdown

Call agent.shutdown() when your process receives a termination signal. This flushes any queued telemetry events to the broker and cleanly disconnects the V8 inspector.
index.ts
import { HyperProbe } from '@hyperprobe/node-sdk';

const agent = HyperProbe.start({
  serviceId: 'payment-service',
  environment: 'production',
  brokerUrl: 'grpc://hyperprobe-broker.internal:50051',
  commitSha: process.env.GIT_COMMIT,
});

process.on('SIGTERM', () => {
  agent?.shutdown();
});

process.on('SIGINT', () => {
  agent?.shutdown();
});

​
Full initialization example

The example below shows a complete initialization with all available options. In most cases you only need the four required fields — the rest have safe defaults. See the configuration reference for a description of each option.
index.ts
import { HyperProbe } from '@hyperprobe/node-sdk';

const agent = HyperProbe.start({
  // Required
  serviceId: 'payment-service',
  environment: 'production',
  brokerUrl: 'grpc://hyperprobe-broker.internal:50051',
  commitSha: process.env.GIT_COMMIT,

  // Performance
  maxQueueSize: 200,
  flushIntervalMs: 500,
  syncIntervalMs: 30000,

  // Safety guardrails
  hitsPerSec: 20,
  bandwidthKbPerSec: 400,
  maxLagMs: 30,
  pauseBudgetMs: 10,
  cooldownSec: 15,

  // Source maps
  sourceMapDir: './dist',
  distLocation: './dist',

  // Data controls
  redactKeys: ['password', 'secret', 'token', 'ssn', 'creditCard'],
  maxObjectDepth: 4,
  maxArrayLength: 5,
  stackFrameDepth: 5,
  maxObjectProperties: 100,
  maxStringLength: 2048,
});

process.on('SIGTERM', () => agent?.shutdown());

​
Singleton behavior

HyperProbe.start() creates a singleton agent. Calling it more than once in the same process is a no-op — the second and subsequent calls are silently ignored and the original agent continues running. You do not need to guard against duplicate initialization.
If you’re running a monorepo or loading the SDK from multiple modules, you can safely call HyperProbe.start() in each module’s entry path without worrying about double initialization.

​
Source map uploads

On startup, the agent automatically detects whether it should upload source maps to the broker. Only one instance across your deployment handles the upload — others poll until the upload completes. The agent looks for source maps in sourceMapDir (defaults to process.cwd()). Point it to your compiled output directory if your source maps live elsewhere. 
HyperProbe.start({
  // ...required options
  sourceMapDir: './dist',    // directory containing *.js.map files
  distLocation: './dist',    // built output directory sent to the broker
});

​
Environment variables

All safety guardrail and data control options can be set via environment variables instead of code. Environment variables take precedence over the values passed in options. See the configuration reference for the full list.
.env
GIT_COMMIT=a3f92c1d
HYPERPROBE_HITS_SEC=20
HYPERPROBE_BANDWIDTH_KB_SEC=400
HYPERPROBE_MAX_LAG_MS=30
HYPERPROBE_REDACT_KEYS=password,secret,token,ssn