Quickstart: Set Up HyperProbe and Capture Your First Probe

This guide walks you through the complete HyperProbe setup: installing the VS Code extension, connecting it to your backend, logging in to the dashboard, adding the SDK agent to your Node.js application, and capturing your first probe. By the end, you will have a live probe returning data from your running service.

Install the VS Code extension

Open VS Code and go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X). Search for HyperProbe and click Install.The extension adds a HyperProbe icon to the activity bar. Click it to open the HyperProbe panel.

Configure the extension (Optional - for self hosted only)

HyperProbe needs to know where your backend server is running. Open VS Code settings (Ctrl+, / Cmd+,) and search for hyperprobe.serverUrl.or you can directly open HyperProbe Settings.Set it to your HyperProbe backend URL:

After completing the previous steps, a Login button will appear in the HyperProbe panelClicking this button will redirect you to the HyperProbe dashboard.Before logging in, ensure that:

You have been added to at least one team by your administrator

If you are not authorized or not part of any team, you will encounter an error.

Once your access is confirmed:

Log in using SSO.
After successful login, you can create and manage your services from the dashboard.

Add a .hprc file to your project

Create a .hprc file in the root of your project. This file tells HyperProbe which service the probes in this repository belong to.

.hprc

{
  "serviceId": "<your-service-uuid>"
}

The serviceId must match the value you pass to HyperProbe.start() in the next step. The VS Code extension reads this file automatically when you open the project.

Install the Node.js SDK

Add the @hyperprobe/node-sdk package to your application:

npm install @hyperprobe/node-sdk

Initialize the agent at startup

Create hyperprobe.ts/js file and import it on the top of your application’s root entrypoint.
Your entrypoint might be something like main.ts, index.js etc.Call HyperProbe.start() as early as possible in your application’s entry point — before any other application code runs.

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

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

HyperProbe.start({
  serviceId: '<service-uuid>',
  environment: 'production',
  brokerUrl: 'https://logger.app.hyperprobe.co',
  commitSha: process.env.GIT_COMMIT,
  
  // Optional fields
  syncIntervalMs: 10 * 1000, // Remove or increase to 60 sec for production
  appRoot: '/apps/my-service', // path of the service from git root, leave it for non-monorepos 
  distLocation: 'dist', // path of build/dist folder from the appRoot above (SourceMapRequired should be set to true while creating this service on the dashboard), leave it if not using typescript/babel etc
});

commitSha is required. Without it, the agent cannot resolve source maps and will refuse to start. Pass it via the GIT_COMMIT environment variable or the commitSha option directly.

Doing this in you docker image as an argument during build time is the easiest way

For typescript / transpiled projects projects, make sure to include sourcemaps in the final build

tsconfig.json

{
  "compilerOptions": {
    "sourceMap": true, // for TS projects, ensure this is true
    "outDir": "./dist",
    "rootDir": "./src",
   // rest of compiler options...
  },
  "include": ["src/**/*"]
}

Set your first probe

With your application running and the extension configured:

Open a source file in VS Code.
Check for the line of code you want to instrument.
Insert a Snapshot from the context menu.

The Insert a Snapshot panel appears that lets you create a probe by selecting a source and specifying the target file and line number.

You can optionally configure hit limits, watch expressions, and conditional logic to control when and what data gets captured.

View captured data

The next time production code executes the instrumented line, the agent captures the local variables and call stack. Open the HyperProbe panel in VS Code to see the result.

You can inspect variable values, navigate the call stack, and manage active probes — all without leaving your editor.

The agent polls for active probes periodically (every 60 seconds by default). New probes may take up to one sync cycle to become active. You can reduce this with the syncIntervalMs option.

Next steps

How it works

Understand the full probe lifecycle, from VS Code to capture and display.

Probe types

Explore Snapshots, Logs, Counters, Metrics, and Tic & Toc probes.

SDK configuration

Tune safety guardrails, data limits, and queue behavior.

Safety guardrails

Learn how HyperProbe protects your application from instrumentation overhead.

​Next steps

How it works

Probe types

SDK configuration

Safety guardrails

Next steps