Node.js SDK Setup Guide

The HyperProbe Node.js SDK runs as an extremely lightweight in-process agent. It hooks directly into the V8 Virtual Machine inspector layer to execute non-blocking debugging, variable captures, metrics, and log injection in microseconds.

Technical Prerequisites

Runtime: Node.js 18 and later.
Metadata: Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).
Source Maps: Mandatory for transpiled or bundled projects (TypeScript, Esbuild, Webpack).

Installation

Add the SDK as a dependency using your package manager:

npm install @hyperprobe/node-sdk

pnpm add @hyperprobe/node-sdk

yarn add @hyperprobe/node-sdk

🗺️ Configuring Source Maps for Transpilers

If your project is transpiled or bundled, source maps are strictly mandatory for the SDK agent to translate compiled bytecode coordinates back to your local source files.

TypeScript (tsconfig.json)
Esbuild
Webpack

Ensure "sourceMap": true is enabled in your compiler options:

tsconfig.json

{
  "compilerOptions": {
    "sourceMap": true,  // Must be true
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Pass the --sourcemap flag inside your CLI build command, or set sourcemap: true in your build script API:

build.js

import esbuild from 'esbuild';

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  sourcemap: true, // Must be true (generates *.js.map)
  outdir: 'dist',
});

Set the devtool option inside your webpack.config.js to compile standard external source maps:

webpack.config.js

module.exports = {
  entry: './src/index.ts',
  devtool: 'source-map', // Must be 'source-map'
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

Initialization Walkthrough

Follow these steps to initialize the HyperProbe agent inside your application:

Create your initialization file

Create a dedicated file named hyperprobe.ts (or hyperprobe.js) inside your project source root. Select your module syntax below:

TypeScript / ES Modules (hyperprobe.ts)
CommonJS (hyperprobe.js)

src/hyperprobe.ts

import { HyperProbe } from '@hyperprobe/node-sdk';

HyperProbe.start({
  serviceId: '<service-uuid-from-dashboard>',
  environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
  brokerUrl: 'https://logger.app.hyperprobe.co',
  commitSha: process.env.GIT_COMMIT, // CI-injected commit SHA (reads process.env.GIT_COMMIT by default)
  distLocation: 'dist',              // Output directory name (e.g. 'dist' or 'build')
  sourceMapDir: './dist'             // Directory containing your *.js.map source map files
});

src/hyperprobe.js

const { HyperProbe } = require('@hyperprobe/node-sdk');

HyperProbe.start({
  serviceId: '<service-uuid-from-dashboard>',
  environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
  brokerUrl: 'https://logger.app.hyperprobe.co',
  commitSha: process.env.GIT_COMMIT, // CI-injected commit SHA (reads process.env.GIT_COMMIT by default)
  distLocation: 'dist',              // Output directory name (e.g. 'dist' or 'build')
  sourceMapDir: './dist'             // Directory containing your *.js.map source map files
});

Import it in your entrypoint

In your main application entrypoint (e.g., index.ts, server.ts, or app.js), import your newly created ./hyperprobe module as early as possible before starting your web server:

import './hyperprobe.js'; // Import as early as possible
import express from 'express';

const app = express();
...

require('./hyperprobe.js'); // Import as early as possible
const express = require('express');

const app = express();
...

Environment Variables Loading Order: You should import ./hyperprobe as early as possible. However, if you are configuring parameters inside hyperprobe.ts that rely on environment variables (such as those loaded via dotenv), ensure that you import/initialize ./hyperprobe after your environment configuration loader has run completely, if needed.

Configure your Dockerfile

To enable Docker-based deployments, define a GIT_COMMIT build argument inside your Dockerfile with a default value of unknown.This ensures that existing local builds or developers’ environments do not fail if they do not yet pass a build argument—safely fallback-disabling the HyperProbe agent until a valid SHA is injected:

Dockerfile

# Define build argument with 'unknown' fallback to protect non-CI builds
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}

Run local Docker builds

For building and testing Docker containers locally on your laptop, inject your active git head using standard command line arguments:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .

Inject correct SHA in CI/CD (The PR Merge Trap)

To protect alignment, HyperProbe refuses to start if commitSha resolves to "unknown". Map your CI/CD platform’s built-in commit SHA environment variable to GIT_COMMIT at deployment.Always use your CI/CD engine’s native environment variables to pass the real commit SHA:

Platform / Engine	Configuration Option	Build Argument Syntax
GitHub Actions	PR-Safe HEAD Check (Recommended)	`--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha \|\| github.sha }}`
GitHub Actions (Push)	Standard Branch Push	`--build-arg GIT_COMMIT=${{ github.sha }}`
GitLab CI/CD	GitLab Variable	`--build-arg GIT_COMMIT=$CI_COMMIT_SHA`
CircleCI	CircleCI Variable	`--build-arg GIT_COMMIT=$CIRCLE_SHA1`
PM2 / Systemd	Native Linux CLI	`GIT_COMMIT=$(git rev-parse HEAD) pm2 start dist/app.js`

⚠️ Beware of the PR Merge Commit Trap: By default, GitHub Actions checking out on a pull_request trigger checkout a virtual merge commit (testing how your branch merges into main) instead of the actual branch commit you pushed.If you run git rev-parse HEAD or use ${{ github.sha }} inside a PR workflow, coordinate mapping will fail because your local VS Code environment is pointing to your actual branch head.To bypass this, always configure GitHub Actions on PRs to use: ${{ github.event.pull_request.head.sha || github.sha }}

⚙️ Configuration & Environment Variables Reference

You can configure the agent by passing properties inside your HyperProbe.start() options object, or by overriding them using environment variables. The code block below illustrates a complete initialization containing all available options, along with their default values and corresponding HYPERPROBE_* environment variables which can override them:

src/hyperprobe.ts

import { HyperProbe } from '@hyperprobe/node-sdk';

HyperProbe.start({
  // --- CORE OPTIONS ---
  serviceId: '<service-uuid-from-dashboard>',   // Env: HYPERPROBE_SERVICE_ID
  environment: process.env.NODE_ENV,             // Env: HYPERPROBE_ENVIRONMENT
  brokerUrl: 'https://logger.app.hyperprobe.co',
  commitSha: process.env.GIT_COMMIT,             // Env: GIT_COMMIT (Mandatory)

  // --- BUFFERING & PERFORMANCE ---
  maxQueueSize: 100,      // Env: HYPERPROBE_MAX_QUEUE_SIZE      - Cap on telemetry stored in memory
  flushIntervalMs: 1000,  // Env: HYPERPROBE_FLUSH_INTERVAL_MS   - Milliseconds before draining the queue
  syncIntervalMs: 60000,  // Env: HYPERPROBE_SYNC_INTERVAL_MS    - Sync cycle to fetch new active probes

  // --- SAFETY GUARDRAILS ---
  hitsPerSec: 10,         // Env: HYPERPROBE_HITS_PER_SEC         - Global limit on triggers per second
  bandwidthKbPerSec: 1024,// Env: HYPERPROBE_BANDWIDTH_KB_PER_SEC - Throughput cap in Kilobytes/sec
  maxLagMs: 80,           // Env: HYPERPROBE_MAX_LAG_MS          - Cooldown triggers if loop lag exceeds this (ms)
  pauseBudgetMs: 30,      // Env: HYPERPROBE_PAUSE_BUDGET_MS     - Max cumulative CPU overhead allowed per second (ms)
  cooldownSec: 10,        // Env: HYPERPROBE_COOLDOWN_SEC        - Duration (in seconds) the agent remains dormant after entering cooldown

  // --- DATA SOURCE MAPS ---
  distLocation: 'dist',   // Env: HYPERPROBE_DIST_LOCATION       - Compiled code folder name
  sourceMapDir: './dist', // Env: HYPERPROBE_SOURCE_MAP_DIR       - Directory containing *.js.map files
  appRoot: '',            // Env: HYPERPROBE_APP_ROOT            - Subdirectory path in monorepos

  // --- DATA & REDACTION CONTROLS ---
  redactKeys: [           // Env: HYPERPROBE_REDACT_KEYS (comma-separated list, e.g. HYPERPROBE_REDACT_KEYS=password,secret,token,ssn,cvv)
    'password', 'secret', 'token', 'authorization', 'cookie', 'key', 'signature'
  ],                      // Blacklisted keys are completely stripped and replaced with [REDACTED] in-process
  redactValues: [],       // Env: HYPERPROBE_REDACT_VALUES (comma-separated list) of literal strings to redact
  maxObjectDepth: 3,      // Env: HYPERPROBE_MAX_OBJECT_DEPTH     - Max nested properties serialized
  maxArrayLength: 3,      // Env: HYPERPROBE_MAX_ARRAY_LENGTH     - Max elements serialized per array
  maxObjectProperties: 50,// Env: HYPERPROBE_MAX_OBJECT_PROPERTIES - Max key-value parameters recorded per object
  maxStringLength: 1024,  // Env: HYPERPROBE_MAX_STRING_LENGTH    - Max character count before string truncation
  stackFrameDepth: 3,     // Env: HYPERPROBE_STACK_FRAME_DEPTH    - Number of call stack frames captured per snapshot
});

Environment Variable Precedence: Any environment variable specified (e.g. setting HYPERPROBE_HITS_PER_SEC=5 inside your server environment) will automatically override the code-level option passed to HyperProbe.start().

Get Started

AI-Native Debugging

VS Code Extension

SDK Integration

Probe Types

Guides

Troubleshooting

Self-Hosting

Node.js SDK Setup Guide

Technical Prerequisites

Installation

🗺️ Configuring Source Maps for Transpilers

Initialization Walkthrough

⚙️ Configuration & Environment Variables Reference

​Technical Prerequisites

​Installation

​🗺️ Configuring Source Maps for Transpilers

​Initialization Walkthrough

​⚙️ Configuration & Environment Variables Reference

Technical Prerequisites

Installation

🗺️ Configuring Source Maps for Transpilers

Initialization Walkthrough

⚙️ Configuration & Environment Variables Reference