@sentienguard/apm

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

Installation

npm install @sentienguard/apm

Quick Start

// 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:

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:

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

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

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:

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

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

Check Status

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