hud-sdk

library0.4.8jsnpmunverified

The `hud-sdk` package provides a lightweight, low-overhead runtime sensor for Node.js applications, designed to capture real-time, function-level behavior directly from production environments. It observes performance characteristics, error behavior, and execution patterns without requiring manual instrumentation, logs, or dashboards. The SDK integrates with various developer tools, including IDEs and CI/CD pipelines, and is specifically optimized for AI-assisted development workflows (e.g., GitHub Copilot, Cursor) to ensure AI-generated code is production-safe. Current stable version is 1.8.3, with frequent updates indicated by its last publish date. It differentiates itself by offering continuous visibility directly in the developer's IDE, focusing on high-fidelity, function-level data, and adhering to strict security and privacy standards (SOC 2 Type II, ISO 27001, GDPR compliance), transmitting only anonymized metadata.

observability devops ai-ml

npm install hud-sdk

package ↗homepage ↗

INSTALL

IMPORT

SIG · HUD-SDK

hud-sdk

observabilityjavascriptv0.4.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { register } from 'hud-sdk';

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

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

✓ import * as Hud from 'hud-sdk';

✗ import 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.

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}`); });

Debug

Known issues

gotchaThe `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`).

affects: >=1.0.0

breakingRunning 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.

affects: >=1.0.0

gotchaFailure 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`).

affects: >=1.0.0

gotchaWhen 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`).

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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)

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)

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.

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.

`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.

Upgrade

Version history

0.4.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

packagehttps://www.npmjs.com/package/hud-sdk ↗

homepagehttps://www.hud.ai ↗