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>);
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
--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.
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.
Updated 4 days ago