Node.js Installation

Integrate Hud Node.js SDK for enhanced observability in your application in a few simple steps

📘

Prerequisites for Hud Integration

Before integrating Hud, please make sure your application meets the requirements.


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 the Initialization File

Set up Hud by creating an initialization file. This file should register the SDK and initiate a session.

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

// Add internal packages from node_modules using glob patterns (e.g., '@your-org/*').
// Hud does not auto-instrument anything inside node_modules unless specified.
hud.register({
  includeModules: [],
});

void hud.initSession(<hud_api_key>, <your_service_name>);
// hud-init.ts
import * as hud from 'hud-sdk/setup' 

// Add internal packages from node_modules using glob patterns (e.g., '@your-org/*').
// Hud does not auto-instrument anything inside node_modules unless specified.
hud.register({
  includeModules: [],
});

void hud.initSession(<hud_api_key>, <your_service_name>);
Replace <hud_api_key> with your Hud API key and <your_service_name> with your service's name.

register() and initSession() Configuration Options

register() Options

register(options) accepts a configuration object with the following keys:

includeModules
Hud monitors all of your code by default, excluding external dependencies (node_modules). Use includeModules to specify internal modules you want Hud to monitor. Accepts an array of glob patterns.
Example: ['@org/*']
debug
Enables verbose logging for development and debugging purposes.

Example:

hud.register({
  includeModules: ['@org/*'],
  debug: true
});

initSession() Options

initSession(key, service) takes the following parameters:

key
Your API token from Hud. Use the key for the correct environment to ensure metrics are tagged appropriately.
service
Unique name used to identify your service in Hud.

Example:

hud.initSession(
  'local_f47da...3eb',
  'main-service'
);

📘

Need to load secrets before initSession()?

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

⚠️

Load Hud Before Anything Else

Hud's SDK needs to be imported as early as possible in your code to make sure it instruments any forthcoming modules' functions. Best practices on how to do it can be found here.

Option A - preferred: preload with --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 before any other imports
// …rest of your app
import './hud-init.ts';   // must come before any other imports
// …rest of your app

Note: Functions in the same file won't be instrumented. Use option A for full coverage (--require).



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 alongside your code.

If your source maps aren’t shipped with your code, we offer alternatives like a CLI uploader.
Chat with our support team or email us at [email protected] and we’ll help you find the best fit.

📘

What are source maps?

Source maps connect your minified or transpiled JavaScript back to the original source code.
They're essential when using tools like Webpack, TSC, or Terser to ensure Hud can display the correct file and function names. These files typically end with .map (e.g., bundle.js.map) and are stored alongside your built JavaScript.



5. Run your service and trigger it!

Start your service and trigger the functions you want to measure - metrics collection will begin automatically.

📘

How to Know If Your Integration Worked

Hud logs success or failure directly to stdout, look for the following logs on success:

  • Hud: Hud session started
  • Hud: First code mapping sent successfully
  • Hud: First invocation sent successfully
  • Hud: Your service is sending data successfully

Then, head over to the web app to explore your data live, or install the IDE extension to view it directly alongside your code.