@fixify/agent

Lightweight Node.js performance monitoring agent for Fixify.

Drop two lines into your Node.js application and start seeing CPU, memory, event loop, HTTP, and GC metrics in real-time on your Fixify dashboard.

Installation

npm install @fixify/agent
# or
pnpm add @fixify/agent

Quick Start

import { init } from '@fixify/agent';

init({
  apiKey: 'your-api-key',
  serverUrl: 'https://api.fixiry.io',
});

Get your API key at fixiry.io — free account, no credit card needed.

Full Options

import { init, stop } from '@fixify/agent';

const agent = init({
  apiKey: 'your-api-key',
  serverUrl: 'https://api.fixiry.io',
  collectInterval: 5000,
  traceEnabled: true,
  logEnabled: true,
  slowThreshold: 200,
  profilingEnabled: false,
  profileDuration: 5000,
  profileCooldown: 60000,
});

// Graceful shutdown
process.on('SIGTERM', () => {
  stop();
  process.exit(0);
});

Options Reference

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Project API key from your Fixify dashboard | | serverUrl | string | required | Fixify server URL (https://api.fixiry.io for cloud) | | collectInterval | number | 5000 | How often to push metrics, in milliseconds | | traceEnabled | boolean | true | Capture individual HTTP request traces | | logEnabled | boolean | true | Intercept and stream console.* output | | slowThreshold | number | 200 | Mark requests slower than this many ms as slow | | profilingEnabled | boolean | false | Enable V8 CPU profiling for flame graphs | | profileDuration | number | 5000 | How long each CPU profile capture runs (ms) | | profileCooldown | number | 60000 | Minimum gap between profile captures (ms) |

What Gets Collected

| Collector | Data | |---|---| | CPU | Usage percentage, core count, load average | | Memory | Heap used/total, RSS, external, array buffers | | Event Loop | Lag mean, p50, p99 percentiles | | HTTP | Request count, durations, status codes, throughput | | Errors | Uncaught exceptions, unhandled promise rejections with stack traces | | Process | PID, uptime, Node.js version, platform | | Traces | Per-request method, URL, status code, duration, slow flag | | Logs | console.log/info/warn/error/debug with level tagging | | GC | Pause counts, durations, major/minor breakdown | | Heap | V8 heap space-by-space breakdown | | Dependencies | Outgoing HTTP calls grouped by hostname | | CPU Profiles | V8 CPU samples for flame graph visualization (opt-in) |

Self-Hosted

Running your own Fixify server? Point serverUrl at your instance:

init({
  apiKey: 'your-api-key',
  serverUrl: 'http://your-server:4000',
});

See the Fixify monorepo for self-hosting instructions.

Compatibility

• Node.js >= 18
• ESM only ("type": "module" or .mjs extension)
• Works with Express, Fastify, Koa, raw http, and any Node.js HTTP server

CommonJS Usage

The agent is ESM-only. If your project uses CommonJS, use dynamic import:

const { init } = await import('@fixify/agent');
init({ apiKey: '...', serverUrl: '...' });

License

MIT — see LICENSE