npm package: @sentienguard/apm
Description: SentienGuard APM SDK - Minimal, production-safe application performance monitoring
Author: SentienGuard
Latest version: 1.0.8

# @sentienguard/apm

Minimal, production-safe APM SDK for Node.js applications. Zero-config setup with automatic instrumentation.

## Installation

```bash
npm install @sentienguard/apm
```

## Quick Start

```js
// If using dotenv, import it first
import 'dotenv/config';

// Then import the SDK (before other app modules for best instrumentation coverage)
import '@sentienguard/apm';

// Your app code
import express from 'express';
const app = express();
// ...
```

Set environment variables:

```bash
SENTIENGUARD_APM_KEY=your-app-key
SENTIENGUARD_SERVICE=my-api
```

That's it. The SDK automatically instruments your application and sends metrics to SentienGuard.

## Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SENTIENGUARD_APM_KEY` | Yes | - | Your application's APM key |
| `SENTIENGUARD_SERVICE` | Yes | - | Service name (e.g., `orders-api`) |
| `SENTIENGUARD_ENV` | No | `production` | Environment (`production`, `staging`, `development`) |
| `SENTIENGUARD_ENDPOINT` | No | `https://sentienguard-dev.the-algo.com/api/v1` | SentienGuard backend URL |
| `SENTIENGUARD_FLUSH_INTERVAL` | No | `10` | Metrics flush interval in seconds |

> **Note:** If `SENTIENGUARD_APM_KEY` or `SENTIENGUARD_SERVICE` is missing, the SDK disables itself silently without affecting your application.

## What Gets Tracked

- **HTTP Requests** - Incoming requests with method, route, status, and latency
- **Dependencies** - Outgoing HTTP/HTTPS calls to external services
- **Errors** - Uncaught exceptions and unhandled rejections

## Framework Integration

### Express

For better route extraction, add the middleware:

```js
import 'dotenv/config'; // if using dotenv
import '@sentienguard/apm';
import { expressMiddleware, expressErrorMiddleware } from '@sentienguard/apm';
import express from 'express';

const app = express();

// Add early in middleware chain
app.use(expressMiddleware());

// Your routes
app.get('/users/:id', (req, res) => { ... });

// Add error middleware last
app.use(expressErrorMiddleware());
```

### Fastify

```js
import 'dotenv/config'; // if using dotenv
import '@sentienguard/apm';
import { fastifyPlugin, fastifyErrorHandler } from '@sentienguard/apm';
import Fastify from 'fastify';

const app = Fastify();

// Register plugin
app.register(fastifyPlugin);

// Add error handler
app.setErrorHandler(fastifyErrorHandler);
```

## API Reference

### Functions

```js
import {
  shutdown,      // Graceful shutdown (flushes pending metrics)
  getStatus,     // Get SDK status and stats
  flush,         // Force flush metrics now
  isEnabled      // Check if SDK is enabled
} from '@sentienguard/apm';
```

### Graceful Shutdown

The SDK automatically handles `SIGTERM` and `SIGINT` signals. For manual shutdown:

```js
import { shutdown } from '@sentienguard/apm';

process.on('exit', async () => {
  await shutdown();
});
```

### Check Status

```js
import { getStatus } from '@sentienguard/apm';

console.log(getStatus());
// {
//   enabled: true,
//   initialized: true,
//   config: { service: 'my-api', environment: 'production', flushInterval: 10 },
//   stats: { requests: 150, dependencies: 45, errors: 2 }
// }
```

## Requirements

- Node.js >= 16.0.0

## License

MIT