@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
// Add this as the FIRST import in your app
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

$3

For better route extraction, add the middleware:

`js
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());
`

$3

`js
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

$3

`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';
`

$3

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

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

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

$3

`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