Node.js SDK with ESM

How to add nodejs sdk into your application

1. Installing node-SDK package

npm install @hypertestco/node-sdk --save-exact 

2. Initializing sdk

2.1 Adding SDK in code and Initialize open telemetry sdk with hypertest

• Create a new file and add this code to initialize hypertest node sdk, then import that file at the top of your entryfile.

It is necessary to initialize sdk in a separate file and then import that file at the top of your entry file. This is needed with esm because imports are loaded before the file's code is run.

Hypertest sdk needs to be initialized as early as possible. Make sure no require/import call is made before that.

// import * as htSdk from '@hypertestco/node-sdk'; // for esm/ts
const htSdk = require('@hypertestco/node-sdk'); // for commonJS
htSdk.initialize({
    apiKey: '<your-api-key>',
    serviceId: '<your-service-identifier-from-dashboard>',
    serviceName: '<organizationName:service-name>',
    exporterUrl: '<hypertest-logger-url>',
    // ignoredHostsForHttpReqs: ['abc.xyz.com', /^\d+\.abcd\.co(m|)$/],
    // disableInstrumentations: [] // htSdk.HtInstrumentations enum. 
});

2.2 Mark app as ready

Call the markAppAsReady method when the app is ready to receive traffic, it indicates that tests can be started (This is important ONLY FOR REPLAY mode).

// Rest Application code...
// add htSdk.markAppAsReady(); when your app is ready to accept requests
app.listen(3000, () => {
  console.log(`Listening for requests on http://localhost:3000`);
  // Indicates the App has booted up successfully for REPLAY And Tests can be started
  htSdk.markAppAsReady();
});

2.3 Use hypertest esm hooks

Give hypertest's esm hooks to the node's esm hooks loader API. This will happen where you start your app with node

HT_MODE=RECORD node --loader=@hypertestco/node-sdk/hooks.mjs my-app.js

ts-node or tsx can't be used to run your project. Your source code needs to be transpiled to js and then run using node.

To enable hypertest, set the HT_MODE env variable to RECORD and start your app

HT_MODE can't be set at the top of your entryfile like this.

// DO NOT DO THIS AT ALL FOR ESM !!!
process.env.HT_MODE = process.env.HT_MODE || 'RECORD';

It only works with cjs because cjs preserves the order of execution of code. Esm imports all modules before the file's code is run.

HT_MODE needs to be set on boot

HT_MODE=RECORD node my-app.js

OR

export HT_MODE=RECORD
node my-app.js

2.3 Set env if opentelemetry is already being used.

// Set this on top inside your JS app
process.env.APPLY_HT_OTEL_PATCH = 'yes'; // Set this env only if opentelemetry is already being used in your application.

3. Verifying traffic is captured

Start sending http requests on your app running with hypertest sdk.

You should start seeing requests under All requests section on the dashboard