npm package: @fixify/agent
Description: Fixify performance profiling agent for Node.js
Latest version: 1.3.0

<div align="center">

# @fixify/agent

**Lightweight Node.js performance monitoring agent for [Fixify](https://fixiry.io).**

[![npm version](https://img.shields.io/npm/v/@fixify/agent?color=cb3837&logo=npm)](https://www.npmjs.com/package/@fixify/agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org)

</div>

---

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](https://fixiry.io).

## Installation

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

## Quick Start

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

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

Get your API key at [fixiry.io](https://fixiry.io/register) — free account, no credit card needed.

## Full Options

```typescript
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:

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

See the [Fixify monorepo](https://github.com/mertcanaltin/fixify) 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:

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

## License

MIT — see [LICENSE](https://github.com/mertcanaltin/fixify/blob/main/LICENSE)