Hud Node.js SDK

Common errors

• Hud: Can't load Hud due to an unsupported Node.js version.

  cause The application is running a Node.js version not supported by the Hud SDK.
  fix Check the Hud SDK's compatibility matrix and upgrade your Node.js runtime to a supported version, then restart your service.

• Hud: SDK has initiated a graceful shutdown. Your application remains unaffected. (Error E9002)

  cause The SDK failed to establish or maintain communication with the Hud backend after multiple retry attempts.
  fix Verify outbound network connectivity from your runtime host to `https://api-prod.hud.io`. Check firewall, proxy settings, and ensure custom SSL certificates are trusted by Node.js.

• Hud: SDK limit of instrumented functions exceeded. SDK has initiated a graceful shutdown. Your application remains unaffected. (Error E1022)

  cause Your application has too many functions, exceeding the SDK's internal instrumentation limit.
  fix Reduce the scope of instrumentation, potentially by configuring the SDK to exclude specific modules or paths. Consult Hud documentation or support for configuration options to manage instrumentation.

• I don't see any endpoints in Hud dashboard.

  cause Hud's SDK did not detect or collect data for your HTTP endpoints, possibly due to `register()` being called too late, unsupported framework, or endpoints not being invoked.
  fix Ensure `register()` is called at the very beginning of your application. Invoke your HTTP endpoints to generate traffic. Check Hud's support matrix for your specific HTTP framework.

• Hud: 'ts-node' was detected but could not be resolved by Hud. This may happen if 'ts-node' is installed globally. Try installing it locally in your project. The SDK has initiated a graceful shutdown.

  cause `ts-node` is either not installed locally or not resolvable by Hud's module loading mechanism.
  fix Install `ts-node` locally in your project (`npm install ts-node`). Ensure `npx ts-node` or `node --require ts-node/register` is used to run your TypeScript application, rather than a globally installed `ts-node` or other problematic setups.

Warnings

• gotcha The `register()` call must be placed as early as possible in your application's entry file, typically before any other application code or framework imports. Delaying this call can result in incomplete or incorrect instrumentation, as Hud might miss wrapping certain functions or modules.
  Fix: Ensure `import { register } from 'hud-sdk';` and its subsequent `register()` call are the very first executable lines in your application's main entry file (e.g., `src/index.ts` or `app.js`).
• breaking Running the SDK with an unsupported Node.js version will prevent it from loading and initiating graceful shutdown. This means no runtime data will be collected.
  Fix: Refer to the official Hud documentation for the compatibility matrix and upgrade your Node.js runtime to a supported version. Restart your service after the update.
• gotcha Failure to communicate with the Hud backend due to network issues, firewall restrictions, proxy configurations, or untrusted certificates will cause the SDK to shut down gracefully.
  Fix: Verify network connectivity to `https://api-prod.hud.io`, check proxy/firewall settings, and ensure any custom CA certificates are correctly configured in your Node.js environment (e.g., via `NODE_EXTRA_CA_CERTS`).
• gotcha When using `ts-node` for TypeScript execution, Hud requires it to run in `transpileOnly` mode to avoid performance issues and ensure proper module loading. If `ts-node` is not resolvable locally, Hud will also gracefully shut down.
  Fix: Run `ts-node` with `--transpileOnly` flag (e.g., `npx ts-node --transpileOnly index.ts`), set `TS_NODE_TRANSPILE_ONLY=true` environment variable, or configure it programmatically. Also, ensure `ts-node` is installed locally in your project dependencies (`npm install ts-node`).
• gotcha The SDK has an internal limit on the number of functions it can instrument to prevent performance degradation. Exceeding this limit will cause the SDK to gracefully shut down.
  Fix: If this occurs, consider reducing the number of instrumented functions by excluding certain modules if your application is exceptionally large or complex. Consult Hud support for guidance on configuring instrumentation scope.

Install

• npm install hud-sdk npm
• yarn add hud-sdk yarn
• pnpm add hud-sdk pnpm

Imports

• register
  wrong:

  const Hud = require('hud-sdk'); Hud.register(...);

  correct:

  import { register } from 'hud-sdk';

  The `register` function is the primary entry point to initialize the Hud SDK. It should be called as early as possible in your application's entry point for optimal auto-instrumentation. Ensure your `package.json` specifies `"type": "module"` for ESM, or use CommonJS `require()` if not.
• HudClient

  import { HudClient } from 'hud-sdk/client';

  While auto-instrumentation is the primary use case, advanced scenarios might require interacting with a client. This is a common pattern, though specific direct client interaction is less emphasized for general setup. Always refer to official documentation for advanced usage.
• * as Hud
  wrong:

  import Hud from 'hud-sdk';

  correct:

  import * as Hud from 'hud-sdk';

  The SDK likely exposes multiple named exports, making `import * as Hud` suitable for accessing various utilities or the `register` function (e.g., `Hud.register()`) if not directly destructuring. Avoid a default import unless explicitly documented, as it's less common for libraries with multiple exports.

Quickstart

This quickstart initializes the Hud Node.js SDK for runtime monitoring and demonstrates a basic Express application whose routes and errors will be automatically instrumented and monitored by Hud. It requires a `HUD_API_KEY` environment variable.

import { register } from 'hud-sdk';

// Ensure this is called as early as possible in your application's entry file.
// It's crucial for Hud's auto-instrumentation to wrap functions correctly.
register({
  apiKey: process.env.HUD_API_KEY ?? '',
  // Optional: Provide a service name for better identification in Hud's dashboard
  serviceName: process.env.SERVICE_NAME ?? 'my-nodejs-app',
  // Optional: Enable debug logging if needed for troubleshooting
  // debug: process.env.NODE_ENV === 'development'
});

// Example of a simple Express app to demonstrate instrumentation
import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  console.log('Request received for /');
  res.send('Hello from Hud-instrumented app!');
});

app.get('/error', (req, res) => {
  console.error('Simulating an error!');
  throw new Error('This is a simulated error detected by Hud!');
});

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});