Node.js Installation

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
import * as hud from 'hud-sdk/setup';

// Add internal packages names 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.js
const hud = require('hud-sdk/setup');

// Add internal packages names 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 <your_service_name> with your service's name.
• Replace <hud_api_key> with your Hud API key.

hud.register({
  includeModules: ['@org/*'],
  excludeDirs: ['tests', 'seed.js'],
  verbose: true,
  useAsyncEsmHooks: true
});

hud.initSession(
  'local_f47da...3eb',
  'main-service',
  {
    tags: {
      region: 'us-east',
      env: 'production',
    },
    deploymentId: 'v2.4.1',
  }
);

3. Load the init file as early as possible

Option A - preferred: preload with --import

--import loads Hud before your application and instruments both ES Modules (ESM) and CommonJS (CJS) in the same process. Use it for every app.

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

npx ts-node --transpileOnly --import ./hud-init.ts [YOUR_ENTRY_POINT].ts

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

// NOTE: Next.js is not fully supported yet, endpoints data will not be collected

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

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

//project.json

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

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

If your app and all its dependencies are CommonJS-only, --require ./hud-init.js also works. Use --import if any of your code or dependencies load as ESM.

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, and this form does not install Hud's ESM loader. Use option A (--import) for full coverage.

If your app loads as ESM, use option A. Static import statements run before the rest of your entry file, so Hud would load after your frameworks and report only partial data.

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 picks up any source maps you deploy alongside your code.

5. Run your service and trigger it!

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

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

Self-hosted: send data to your own collector (OTLP)

With Hud self-hosted, the SDK sends its metrics and forensics over OTLP to your own OpenTelemetry collector, not to Hud. Install the SDK with steps 1 to 5 above, then turn on OTLP mode as shown here. It needs hud-sdk 1.12.0 or later, and only the Node.js SDK supports it.

The SDK still opens a session with Hud, so it needs your Hud API key, as in step 2. Your metrics and forensics don't go to Hud.

Turn on OTLP mode

Set the exporter to otlp and give the URL of your collector, with environment variables or in the init file:

HUD_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=<your-collector-url>

hud.register({
  exporter: 'otlp',
  otlp: { endpoint: '<your-collector-url>' },
});

Replace <your-collector-url> with the base URL of your collector's OTLP/HTTP endpoint, for example http://my-collector:4318. The SDK adds /v1/metrics and /v1/logs itself. With no URL set, it sends to http://localhost:4318.

The SDK exports delta metrics, which Prometheus doesn't accept, so your collector needs the deltatocumulative processor before its Prometheus exporter.

Settings

The SDK also reads the standard OTEL_EXPORTER_OTLP_* variables, so settings your app already has for OpenTelemetry apply to Hud too. To give Hud its own settings, use the same variables with the HUD_OTLP_ prefix instead, such as HUD_OTLP_PROTOCOL, or the otlp option. Both win over the standard variables.

Resource attributes tie your data to a release and a commit, so set them when you deploy. For example:

OTEL_RESOURCE_ATTRIBUTES="service.version=1.4.2,deployment.environment.name=production,vcs.repository.url.full=https://github.com/org/repo,vcs.ref.head.revision=$GIT_SHA,vcs.ref.head.name=main"

Hud refuses these settings: gRPC, TLS certificates and client keys, any temporality other than delta, any histogram other than base2 exponential, an export timeout (OTEL_METRIC_EXPORT_TIMEOUT) and OpenTelemetry config files (set HUD_OTLP_IGNORE_CONFIG_FILE=true to ignore one). OTLP mode doesn't work with customForensicsStorage or in AWS Lambda.

If the SDK doesn't start

Hud prints an error code. For these errors, the SDK shuts itself down, and your app keeps running.

Warnings

Hud prints these and keeps running.

If an export fails

Hud prints each of these once per process, then keeps exporting. The data from failed exports is lost, and your app keeps running. The URL in the message leaves out user info and the query string.