@equartiste/deploy-tracker

A robust Node.js telemetry package to expose detailed system diagnostics and environment details via a secure GET endpoint.

Features

• On-Demand Telemetry: No background heartbeats; data is only collected and served when requested.
• Deep System Insights: Powered by systeminformation to provide CPU, Memory, OS, Storage, and Network details.
• Middleware Support: Easily integrate into Express, Koa, or standard Node.js http servers.
• Standalone Mode: Run a dedicated monitoring server on a custom port.
• Environment Aware: Automatically captures process.env and runtime details.

Installation

npm install @equartiste/deploy-tracker
# or
bun add @equartiste/deploy-tracker

Usage

1. Standalone Status Server

Start a dedicated server that exposes system vitals.

import { Tracker } from '@equartiste/deploy-tracker';

const tracker = new Tracker({
  serverPort: 3001,           // Starts a server on port 3001
  serverPath: '/status'       // Endpoint path (defaults to /deploy-tracker)
});

// Access diagnostics at: http://localhost:3001/status

2. Express Middleware Integration

Integrate into your existing Express application.

import express from 'express';
import { Tracker } from '@equartiste/deploy-tracker';

const app = express();
const tracker = new Tracker({
  serverPath: '/api/vitals'
});

// Use as middleware
app.get('/api/vitals', tracker.handleRequest);

app.listen(3000);

3. Manual Collection

Manually trigger diagnostic collection.

import { Tracker } from '@equartiste/deploy-tracker';

const tracker = new Tracker();

async function checkVitals() {
  const vitals = await tracker.getDeployInfo();
  console.log(vitals);
}

API Configuration

The Tracker constructor accepts a TrackerConfig object:

| Property | Type | Description | | --- | --- | --- | | serverPort | number | (Optional) Port to start a standalone HTTP server. | | serverPath | string | Path for the status endpoint (default: /deploy-tracker). | | onCollect | function | Async callback to modify or extend the data before it's returned. |

Data Structure

The endpoint returns a JSON object with the following structure:

{
  "timestamp": "2024-05-08T12:00:00.000Z",
  "system": {
    "cpu": { ... },
    "memory": {
      "total_gb": "16.00",
      "free_gb": "4.50",
      "used_gb": "11.50"
    },
    "os": { ... },
    "storage": [ ... ],
    "network": [ ... ],
    "virtualization": {
      "docker": { ... },
      "vbox": { ... }
    }
  },
  "environment": { ... process.env ... },
  "runtime": {
    "version": "v20.10.0",
    "platform": "linux",
    "arch": "x64",
    "uptime": 12345,
    "loadavg": [0.5, 0.4, 0.3]
  }
}

License

ISC