SDK Integration
Node.js SDK Setup Guide
Install, initialize, and optimize the InSitu Node.js SDK inside in-process Node applications.
The InSitu 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
pnpm
yarn
npm
install
@InSitu/node-sdk
pnpm
add
@InSitu/node-sdk
yarn
add
@InSitu/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 InSitu agent inside your application:
1
Create your initialization file
Create a dedicated file named
InSitu.ts
(or
InSitu.js
) inside your project source root. Select your module syntax below:
TypeScript / ES Modules (InSitu.ts)
CommonJS (InSitu.js)
src/InSitu.ts
import
{
InSitu
}
from
'@InSitu/node-sdk'
;
InSitu
.
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.useinsitu.com'
,
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')
});
src/InSitu.js
const
{
InSitu
}
=
require
(
'@InSitu/node-sdk'
);
InSitu
.
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.useinsitu.com'
,
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')
});
2
Import it in your entrypoint
In your main application entrypoint (e.g.,
index.ts
,
server.ts
, or
app.js
), import your newly created
./InSitu
module
as early as possible
before starting your web server:
src/index.ts (ES Modules / TypeScript)
src/index.js (CommonJS)
import
'./InSitu.js'
;
// Import as early as possible
import
express
from
'express'
;
const
app
=
express
();
...
require
(
'./InSitu.js'
);
// Import as early as possible
const
express
=
require
(
'express'
);
const
app
=
express
();
...
Environment Variables Loading Order:
You should import
./InSitu
as early as possible. However, if you are configuring parameters inside
InSitu.ts
that rely on environment variables (such as those loaded via
dotenv
), ensure that you import/initialize
./InSitu
after your environment configuration loader has run completely
, if needed.
3
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 InSitu 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}
4
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
.
5
Inject correct SHA in CI/CD (The PR Merge Trap)
To protect alignment, InSitu 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
InSitu.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
InSitu_*
environment variables
which can override them:
src/InSitu.ts
import
{
InSitu
}
from
'@InSitu/node-sdk'
;
InSitu
.
start
({
// --- CORE OPTIONS ---
serviceId:
'<service-uuid-from-dashboard>'
,
// Env: InSitu_SERVICE_ID
environment:
process
.
env
.
NODE_ENV
,
// Env: InSitu_ENVIRONMENT
brokerUrl:
'https://logger.app.useinsitu.com'
,
commitSha:
process
.
env
.
GIT_COMMIT
,
// Env: GIT_COMMIT (Mandatory)
// --- BUFFERING & PERFORMANCE ---
maxQueueSize:
100
,
// Env: InSitu_MAX_QUEUE_SIZE      - Cap on telemetry stored in memory
flushIntervalMs:
1000
,
// Env: InSitu_FLUSH_INTERVAL_MS   - Milliseconds before draining the queue
syncIntervalMs:
60000
,
// Env: InSitu_SYNC_INTERVAL_MS    - Sync cycle to fetch new active probes
// --- SAFETY GUARDRAILS ---
hitsPerSec:
10
,
// Env: InSitu_HITS_PER_SEC         - Global limit on triggers per second
bandwidthKbPerSec:
1024
,
// Env: InSitu_BANDWIDTH_KB_PER_SEC - Throughput cap in Kilobytes/sec
maxLagMs:
80
,
// Env: InSitu_MAX_LAG_MS          - Cooldown triggers if loop lag exceeds this (ms)
pauseBudgetMs:
30
,
// Env: InSitu_PAUSE_BUDGET_MS     - Max cumulative CPU overhead allowed per second (ms)
cooldownSec:
10
,
// Env: InSitu_COOLDOWN_SEC        - Duration (in seconds) the agent remains dormant after entering cooldown
// --- DATA SOURCE MAPS ---
distLocation:
'dist'
,
// Env: InSitu_DIST_LOCATION       - Compiled code folder name
appRoot:
''
,
// Env: InSitu_APP_ROOT            - Subdirectory path in monorepos
sourceMapDir:
''
// Env: InSitu_SOURCE_MAP_DIR     - Directory path to scan and upload source map files
// --- DATA & REDACTION CONTROLS ---
redactKeys
: [
// Env: InSitu_REDACT_KEYS (comma-separated list, e.g. InSitu_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: InSitu_REDACT_VALUES (comma-separated list) of literal strings to redact
maxObjectDepth:
3
,
// Env: InSitu_MAX_OBJECT_DEPTH     - Max nested properties serialized
maxArrayLength:
3
,
// Env: InSitu_MAX_ARRAY_LENGTH     - Max elements serialized per array
maxObjectProperties:
50
,
// Env: InSitu_MAX_OBJECT_PROPERTIES - Max key-value parameters recorded per object
maxStringLength:
1024
,
// Env: InSitu_MAX_STRING_LENGTH    - Max character count before string truncation
stackFrameDepth:
3
,
// Env: InSitu_STACK_FRAME_DEPTH    - Number of call stack frames captured per snapshot
});
Environment Variable Precedence:
Any environment variable specified (e.g. setting
InSitu_HITS_PER_SEC=5
inside your server environment) will
automatically override
the code-level option passed to
InSitu.start()
.
VS Code Extension IDE Guide
Previous
Java SDK Setup Guide
Next
⌘
I
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Terms of Service
On this page
Back to top
Technical Prerequisites
Installation
🗺️ Configuring Source Maps for Transpilers
Initialization Walkthrough
⚙️ Configuration & Environment Variables Reference