pulse-metrics-sdk

Minimal Node.js SDK for Pulse Metrics instance tracking.

Sends a startup event on initialization and schedules periodic heartbeat pings. The instance ID is automatically generated and persisted to disk so the same ID survives restarts.

Requirements

Node.js 18 or later.

Installation

npm install pulse-metrics

Or copy index.ts directly into your project and compile it alongside your code.

Usage

import { init } from 'pulse-metrics';

init('https://analytics.example.com', 'your-service-token');

Call init once, as early as possible during startup (e.g. at the top of your entry file). That's it.

Options

init('https://analytics.example.com', 'your-service-token', {
  // Use a fixed instance ID instead of auto-generating one
  instanceId: 'my-server-1',

  // Heartbeat every 60 seconds instead of the default 24 hours
  heartbeatInterval: 60_000,

  // Disable heartbeats entirely (only send the startup event)
  // heartbeatInterval: false,

  // Custom path for the persisted instance ID file
  persistPath: '/var/lib/myapp/.analytics-id',
});

Option reference

| Option | Type | Default | Description | |---|---|---|---| | instanceId | string | auto | Override the instance ID. Skips persistence. | | heartbeatInterval | number \| false | 86_400_000 (24 h) | Milliseconds between heartbeats. false disables heartbeats. | | persistPath | string | .pulse-metrics-id (cwd) | File path used to persist the auto-generated instance ID. | | debug | boolean | false | When enabled, errors are logged to the console instead of being silently swallowed. |

Notes

• Network errors are silently ignored — tracking will never crash your app.
• The heartbeat timer is unreffed (setInterval(...).unref()) so it won't prevent Node.js from exiting naturally.
• The raw instanceId is never stored by the server — only a derived HMAC key is persisted.

Building

npm install
npm run build

Output is written to dist/.