@polarsignals/pprof

Node.js profiling library that automatically uploads heap profiles to Polar Signals.

Installation

npm install @polarsignals/pprof

Usage

const { heapProfiler, monitorOutOfMemory } = require('@polarsignals/pprof');

// Start heap profiling
heapProfiler.start(512 * 1024, 64); // 512KB sampling, stack depth 64

// Monitor for out-of-memory events and auto-upload profiles
monitorOutOfMemory({
  exportOptions: {
    labels: { service: 'my-app', version: '1.0.0' },
  },
});

// Resolve frames locally against .map files; skips server-side resolution.
const profile = await heapProfiler.encodedProfile({
  localSourceMapRoots: [process.cwd()],
});

endpoint, projectId, and token fall back to POLARSIGNALS_SERVER_URL, POLARSIGNALS_PROJECT_ID, and POLARSIGNALS_TOKEN env vars respectively, so typical deployments don't need to set them in code.

exportOptions

| Field | Type | Default | Description | | ------------ | ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Field | Type | Default | Description | | --------------------- | ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | endpoint | string | https://api.polarsignals.com/api/parca/profilestore | Profile-store base URL. | | projectId | string | $POLARSIGNALS_PROJECT_ID | Polar Signals project UUID. | | labels | Record<string, string> | — | Extra series labels attached to the profile (e.g. service, version). | | headers | Record<string, string> | — | Extra HTTP headers added to the upload request. | | timeout | number | 30000 | Request timeout in ms. | | localSourceMapRoots | string[] | — | If set, the OOM upload-worker resolves frames against .map files in these dirs and skips server-side resolution. The same option is available on heapProfiler.encodedProfile — see below. |

The bearer token is read exclusively from POLARSIGNALS_TOKEN env var.

heapProfiler.encodedProfile(options?)

Returns a gzipped pprof Buffer for ad-hoc serving (e.g. a /debug/pprof/allocs endpoint).

| Field | Type | Default | Description | | --------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | localSourceMapRoots | string[] | — | If set, the lib walks these directories for .map files and resolves frames locally at encode time, skipping server-side resolution. If omitted, frames are encoded for server-side resolution. |

Features

• Automatic heap profile collection
• Out-of-memory monitoring with automatic profile upload
• Background upload process to ensure profiles are saved even during crashes
• Configurable labels for profile metadata