Skip to main content
Every option you pass to HyperProbe.start() is documented here. Only three fields are strictly required to get started — all others have production-safe defaults. Where an environment variable equivalent exists, it takes precedence over the value passed in code, which lets you tune the agent’s behavior in different environments without modifying your source.

​
Required options

These four options must be provided. The agent will not start without them.
​
serviceId
string
required
A stable, human-readable identifier for the service running this agent. HyperProbe uses this to scope probes and telemetry. Use a value that is consistent across deployments — for example, payment-service or user-api.
serviceId: 'payment-service'
​
environment
string
required
The deployment environment, such as production, staging, or canary. This is displayed in the VS Code extension alongside captured snapshots so you always know which environment a capture came from.
environment: 'production'
​
brokerUrl
string
required
The gRPC address of your HyperProbe broker. The agent connects to this URL to receive probe instructions and report captured telemetry.
brokerUrl: 'grpc://hyperprobe-broker.internal:50051'
​
commitSha
string
required
The full or abbreviated git commit SHA of the deployed build. HyperProbe uses this to resolve source maps and match probe line numbers to the exact version of code running in production. Without an accurate commitSha, probes will not resolve correctly.You can pass this directly or omit it and set the GIT_COMMIT environment variable instead — the agent reads GIT_COMMIT automatically.
// Pass directly:
commitSha: 'a3f92c1d'

// Or read from the environment (recommended):
commitSha: process.env.GIT_COMMIT
If commitSha is absent or set to the string 'unknown', the agent logs a critical error and refuses to start. Ensure your deployment pipeline always sets GIT_COMMIT or passes the SHA explicitly.
Environment variable: GIT_COMMIT

​
Performance options

These options control how quickly the agent buffers and flushes telemetry events to the broker.
​
maxQueueSize
number
default:"100"
The maximum number of telemetry events the agent holds in memory before it starts dropping new captures. When the queue is full, the agent logs a warning and discards the incoming event — it still increments the hit counter to enforce probe limits, but the captured data is not sent. Increase this if you see dropped events under heavy probe activity.No environment variable override — set this in code only.
​
flushIntervalMs
number
default:"1000"
How often (in milliseconds) the agent drains the telemetry queue and sends events to the broker. Lower values reduce latency between a probe firing and data appearing in the VS Code extension. Values below 200 are not recommended in high-throughput services.No environment variable override — set this in code only.
​
syncIntervalMs
number
default:"60000"
How often (in milliseconds) the agent syncs with the broker to fetch new or updated probes. The broker may also instruct the agent to use a different interval via nextSyncMs in its response, so the effective interval may vary at runtime.Environment variable: HYPERPROBE_SYNC_INTERVAL_MS

​
Safety guardrails

HyperProbe’s safety system monitors your application’s overhead in real time. If instrumentation exceeds any of the thresholds below, the agent suspends all probes for a cooldown period and then attempts to resume. This ensures the agent never meaningfully impacts production performance.
​
hitsPerSec
number
default:"10"
The maximum number of probe hits the agent will process per second across all active probes. Hits that exceed this limit are skipped (the hit is still counted toward the probe’s hitLimit, but no data is captured). This is your primary throughput guardrail.Environment variable: HYPERPROBE_HITS_SEC
​
bandwidthKbPerSec
number
default:"200"
The maximum outbound telemetry bandwidth in kilobytes per second. If captured data exceeds this rate, the agent throttles captures to stay within the limit.Environment variable: HYPERPROBE_BANDWIDTH_KB_SEC
​
maxLagMs
number
default:"50"
The maximum instrumentation lag in milliseconds before the safety shield activates. The agent continuously monitors how much latency its V8 inspector hooks add to request processing. If the measured lag exceeds maxLagMs, the agent transitions to RED status, suspends all probes, and waits for the cooldown period to end before resuming.Environment variable: HYPERPROBE_MAX_LAG_MS
​
pauseBudgetMs
number
default:"20"
The maximum total pause time in milliseconds that the agent is allowed to introduce per second. Pause time accumulates across all probe hits within a one-second window. Exceeding this budget triggers the safety shield.Environment variable: HYPERPROBE_PAUSE_BUDGET_MS
​
cooldownSec
number
default:"10"
The number of seconds the agent waits after the safety shield activates before attempting to resume probe instrumentation. During cooldown, no probes fire and no telemetry is captured. The agent resumes automatically once the cooldown expires.Environment variable: HYPERPROBE_COOLDOWN_SEC

​
Data controls

These options control how much data the agent captures per probe hit and which field values are automatically redacted before telemetry is sent to the broker.
​
redactKeys
string[]
An array of field name patterns the agent redacts from captured snapshots. Any object property whose name matches an entry in this list has its value replaced with [REDACTED] before the telemetry event is sent. The default list covers the most common sensitive fields.To add your own sensitive keys while keeping the defaults, include the default values in your array.
redactKeys: ['password', 'secret', 'token', 'authorization', 'cookie', 'key', 'signature', 'ssn', 'creditCard']
Environment variable: HYPERPROBE_REDACT_KEYS (comma-separated list)
HYPERPROBE_REDACT_KEYS=password,secret,token,ssn,creditCard
Setting HYPERPROBE_REDACT_KEYS via environment variable replaces the default list entirely. Include any defaults you want to keep when using the env var.
​
redactValues
string[]
default:"[]"
An array of literal values to redact from captured snapshots, regardless of which field they appear in. Use this to scrub specific known-sensitive strings — for example, a static API key or a known test credential — from all captured data.Environment variable: HYPERPROBE_REDACT_VALUES (comma-separated list)
​
maxObjectDepth
number
default:"3"
The maximum depth to which the agent serializes nested objects in a snapshot. Properties deeper than this limit are replaced with a truncation marker. Increase this if your data structures are deeply nested and you need to see inner values, but be aware that higher depths produce larger telemetry payloads.Environment variable: HYPERPROBE_MAX_OBJECT_DEPTH
​
maxArrayLength
number
default:"3"
The maximum number of elements the agent captures from any array. Elements beyond this limit are truncated. If you frequently need to inspect longer arrays, increase this value — but note the impact on telemetry payload size.Environment variable: HYPERPROBE_MAX_ARRAY_LENGTH
​
stackFrameDepth
number
default:"3"
The number of call stack frames included in each snapshot. The first frame is always the line where the probe fired. Additional frames give you the call chain leading up to that point.Environment variable: HYPERPROBE_STACK_FRAME_DEPTH
​
maxObjectProperties
number
default:"50"
The maximum number of properties the agent captures from any single object. Properties beyond this limit are omitted. This guards against capturing very large objects (e.g., HTTP request objects) that would produce outsized telemetry payloads.Environment variable: HYPERPROBE_MAX_OBJECT_PROPERTIES
​
maxStringLength
number
default:"1024"
The maximum number of characters captured from any string value. Strings longer than this limit are truncated at the character boundary and marked with a truncation indicator. Increase this if you need to capture long payloads such as JSON bodies or SQL queries.Environment variable: HYPERPROBE_MAX_STRING_LENGTH

​
Source map options

HyperProbe uses source maps to translate probe positions in compiled output back to your original TypeScript or transpiled source. The agent automatically discovers and uploads source maps to the broker on startup.
​
sourceMapDir
string
default:"process.cwd()"
The directory the agent searches for *.js.map source map files. Set this to your compiled output directory if your source maps live somewhere other than the current working directory.
sourceMapDir: './dist'
Environment variable: HYPERPROBE_SOURCE_MAP_DIR
​
distLocation
string
default:"\"\""
The path to your built output directory. This is sent to the broker alongside the source maps so HyperProbe can correctly resolve file paths when you navigate to a captured snapshot in the VS Code extension.
distLocation: './dist'
Environment variable: HYPERPROBE_DIST_LOCATION

​
Complete configuration example

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', 'authorization', 'cookie', 'key', 'signature', 'ssn'],
  redactValues: [],
  maxObjectDepth: 4,
  maxArrayLength: 5,
  stackFrameDepth: 5,
  maxObjectProperties: 100,
  maxStringLength: 2048,
});

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

​
Environment variable precedence

When the same option is set both in code and via an environment variable, the environment variable always wins. This lets you deploy a single build with conservative defaults baked in and override specific guardrails per environment without redeploying.
.env.production
GIT_COMMIT=a3f92c1d
HYPERPROBE_HITS_SEC=20
HYPERPROBE_BANDWIDTH_KB_SEC=400
HYPERPROBE_MAX_LAG_MS=30
HYPERPROBE_PAUSE_BUDGET_MS=10
HYPERPROBE_COOLDOWN_SEC=15
HYPERPROBE_SYNC_INTERVAL_MS=30000
HYPERPROBE_SOURCE_MAP_DIR=./dist
HYPERPROBE_DIST_LOCATION=./dist
HYPERPROBE_REDACT_KEYS=password,secret,token,authorization,cookie,key,signature,ssn
HYPERPROBE_MAX_OBJECT_DEPTH=4
HYPERPROBE_MAX_ARRAY_LENGTH=5
HYPERPROBE_STACK_FRAME_DEPTH=5
HYPERPROBE_MAX_OBJECT_PROPERTIES=100
HYPERPROBE_MAX_STRING_LENGTH=2048