@sentienguard/apm

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

Installation

npm install @sentienguard/apm

Quick Start

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

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

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

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

Browser / Frontend Monitoring (RUM)

For React, Vue, or other browser apps, bundlers automatically use the browser build. Call init() explicitly in your app entry (client-side only):

import SentienGuard from '@sentienguard/apm';

SentienGuard.init({
  apiKey: 'your-apm-key',
  service: 'my-frontend',
  endpoint: 'https://your-backend.com/api/v1/apm/ingest',
  environment: 'production'
});

What Gets Tracked (Browser)

• Outgoing fetch/XHR — API calls from the browser with latency and errors
• Core Web Vitals — LCP, FID, INP, CLS
• Page load timing — TTFB, DOM ready, full load
• JS errors — Unhandled exceptions and promise rejections
• SPA routes — Client-side navigation via History API

Browser Configuration

| Option | Required | Default | Description | |--------|----------|---------|-------------| | apiKey | Yes | - | APM application key | | service | Yes | - | Frontend service name | | endpoint | No | SentienGuard dev ingest URL | Full ingest URL | | environment | No | production | Environment name | | flushInterval | No | 10 | Flush interval in seconds | | debug | No | false | Enable SDK debug logging |

Requirements

• Node.js >= 16.0.0 (server SDK)
• Modern browser with PerformanceObserver support (browser SDK)

License

MIT