Backend Instrumentation (dynamic)

Applies to: backend Node.js services — Express/Nest/Fastify APIs, workers, and similar.

Backend services use dynamic instrumentation. SeaLights attaches to the Node.js process at startup and instruments code at runtime.

This is different from Scanning Your Application. scan uploads the build map. run and preload.js attach runtime coverage to the live process.

Nothing is rewritten before deployment. You deploy the original service and start it through SeaLights.

1

Scan the backend service

Start by scanning the service code. This creates the SeaLights build map.

You need a valid token and Build Session ID first. See Scanning Your Application → Prerequisites.

Use the same app folder in --scanDir that you used during the scan.

2

Start the service with SeaLights

Choose the attach method that matches how you start the service.

• Use preload.js when you want to keep the original start command unchanged.
• Use slnodejs run when you control the full launch command.

If you run TypeScript with ts-node, prefer preload.js. It works without extra runner flags.

Option A — preload.js

Inject the agent with NODE_OPTIONS and keep your normal startup command unchanged.

This also works behind npm start, pm2, containers, and other startup wrappers. Set NODE_OPTIONS and keep the original startup command unchanged.

Bash

export SL_tokenfile=./sltoken.txt
export SL_buildsessionidfile=buildSessionId
export SL_labid=my_lab_id
export NODE_OPTIONS="--require ./node_modules/slnodejs/lib/preload.js"

node ./server/app.js

GitHub Actions

PowerShell

Azure DevOps

Option B — slnodejs run

Wrap the startup command with run.

Everything after -- is passed to your application startup command.

Bash

npx slnodejs run \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir ./server \
  --labId my_lab_id \
  --useInitialColor \
  -- ./server/app.js

GitHub Actions

PowerShell

Azure DevOps

Validate

After startup, confirm that SeaLights is attached and receiving activity.

1. Start the service with one of the methods above.
2. Trigger at least one request, job, or worker execution.
3. Check Agent Monitor for the running agent.
4. Confirm coverage appears after your tests hit the service.

3

Run your tests

Once the backend service is running with SeaLights attached, continue to Capturing Tests.

Reference

Multiple environments and replicas

Use Lab IDs consistently across environments.

• Use the same labId for multiple replicas of the same environment.
• Use a different labId for each separate environment, such as qa-api and staging-api.
• Use testStage when you want the agent grouped under a specific test stage.

If you omit --labId or SL_labid, SeaLights uses the Build Session ID as the fallback Lab ID.

Troubleshooting

If the service starts but coverage does not appear, validate the runtime attachment first.

Bash

ps -ef | grep slnodejs

PowerShell

If the startup succeeds but the agent does not appear, check whether NODE_OPTIONS was replaced by another startup layer.

Common issues:

• The --scanDir path does not match the folder used during scan.
• The -- separator is missing in slnodejs run.
• The process starts correctly, but no traffic reaches instrumented code.

See also:

• dryRun Command: Troubleshooting and Validation
• Understanding the -- (Double Dash) Separator in slnodejs run Commands

Parameters

Parameter	Purpose
--tokenFile / --token	SeaLights authentication. Use a file locally or a secret in CI.
--buildSessionIdFile / --buildSessionId	Build session identifier. This must match the build you scanned.
--scanDir	The service source directory used during scan.
--labId	Connects the running service to a specific lab or environment.
--testStage	Names the stage this running agent belongs to.
--useInitialColor	Starts collecting coverage from process startup, not only from later requests.

Use --useInitialColor when you need coverage from bootstrap code, startup hooks, or worker initialization.