1. Install SDK package

Run the installation command according to your package manager.

npm install hud-sdk

yarn add hud-sdk

pnpm add hud-sdk

2. Create a Hud Initialization File

Create a new file named hud-init.js to init Hud. In this file, call register, optionally passing a configuration object. Then, initialize the session by calling initSession with your API key and service name.

API keys can be found here.

const hud = require('hud-sdk/setup');

// Specify your internal modules as a glob pattern (e.g. '@your-org/*'), or leave empty 
hud.register({
  includeModules: [],
});

hud.initSession(<API_KEY>, <SERVICE_NAME>);

import * as hud from 'hud-sdk/setup' 

// Specify your internal modules as a glob pattern (e.g. '@your-org/*'), or leave empty 
hud.register({
  includeModules: [],
});

hud.initSession(<API_KEY>, <SERVICE_NAME>);

If your configuration or environment variables are initialized later in the application lifecycle, you may invoke hud.initSession at that later stage or from a separate file.

3. Load the init file as early as possible

📘

Hud's SDK needs to be imported as early as possible in your code to make sure it instruments any forthcoming modules' functions.

Option A - preferred: preload with node --require

node --require ./hud-init.js [YOUR_ENTRY_POINT].js

npx ts-node --require ./hud-init.ts [YOUR_ENTRY_POINT].ts

nest start --exec "node --require ./hud-init.js"

// Create a file called instrumentation.ts with the following code:

export async function register() {
	require('./hud-init.js');
}

//project.json

"my-app": {
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "runtimeArgs": ["--require", "./hud-init.js"],
        //...
      },
    },
  }
}

// If using `npm run`, check your package.json and modify the relevant script that runs your backend:
"scripts": {
  "dev": "node --require ./hud-init.js index.js"
}

Option B - simple import

Add the import at the very top of your entrypoint:

require('./hud-init.js'); // must come first
// …rest of your app

import './hud-init.ts';   // must come *before* any other imports
// …rest of your app

Note: When imported using this option, Hud won't instrument functions declared in the same file.

4. Using a Bundler, Transpiler, or Minifier?

Hud uses source maps to reconstruct the original code in your production traces so you get clear, accurate visibility into what ran, where. Hud automatically pick up any source maps you deploy with your code.

📘

What are source maps?
Source maps map your minified or transpiled JavaScript back to the original source code. They’re essential when using tools like Webpack, ESBuild, SWC, or any code minifier.

If source maps aren’t bundled with your code, we offer other options like bundler plugins and a CLI uploader. Just reach out at [email protected] and we’ll help you find the best fit.

You're All Set!

Start your service and trigger the functions you want to measure - metrics collection will begin automatically.
If everything worked as expected, you’ll see a log message confirming: “Hud initialized successfully”. Then, head over to Hud to explore your data live, or install the IDE extension to view it directly alongside your code.