apm-optima 0.0.1 → 1.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to Optima APM
+
+Thank you for your interest in contributing to **Optima APM**! We welcome bug fixes, feature proposals, documentation updates, and performance improvements.
+
+This document provides a set of guidelines and instructions for setting up your local development environment and contributing to the project.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Monorepo Architecture](#monorepo-architecture)
+- [Prerequisites](#prerequisites)
+- [Local Development Setup](#local-development-setup)
+- [Project Workflow & Commands](#project-workflow--commands)
+- [Development Guidelines](#development-guidelines)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+
+---
+
+## Code of Conduct
+
+Please be respectful, constructive, and collaborative in all communications, issues, and Pull Requests.
+
+---
+
+## Monorepo Architecture
+
+This project is structured as a **Monorepo** using **npm workspaces**:
+
+```
+├── packages/
+│   └── core/          # Telemetry engine, interceptors, and WebSocket adapters (apm-optima/core)
+│   └── dashboard/     # Next.js React Dashboard (exported statically into apm-optima/core)
+├── apps/              # Integration & demo application (Express & NestJS)
+```
+
+- **`apm-optima/core`**: The published npm package containing the telemetry engine.
+- **`packages/dashboard`**: A Next.js application that gets exported statically (`output: 'export'`) and bundled into `apm-optima/core`.
+- **`apps`**: A local environment used to test `apm-optima/core` changes in real time.
+
+---
+
+## Prerequisites
+
+Ensure you have the following installed locally:
+
+- **Node.js**: `>= 20.0.0` (LTS version recommended)
+- **npm**: `>= 10.0.0` (Native support for npm workspaces)
+- **Git**: `>= 2.x`
+
+---
+
+## Local Development Setup
+
+Follow these steps to clone and run the repository locally:
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/Nosalis1/Optima.git
+cd Optima
+```
+
+### 2. Install Dependencies
+
+Install all dependencies across the entire monorepo with a single command from the root directory:
+```bash
+npm install
+```
+
+### 3. Build the Packages
+
+Build all packages in order (this compiles the Next.js static dashboard and builds `apm-optima/core`):
+```bash
+npm run build
+```
+
+---
+
+## Project Workflow & Commands
+
+You can run workspace tasks from the root directory using central npm scripts:
+
+### Build Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npm run build` | Builds the Dashboard first, then compiles `apm-optima/core`. |
+| `npm run build:dashboard` | Statically exports the Next.js Dashboard into `apps/dashboard/out`. |
+| `npm run build:core` | Compiles TypeScript code for `apm-optima/core`. |
+| `npm run clean` | Cleans `dist`, `.next`, and build artifacts across all packages. |
+
+### Development Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npm run dev:dashboard` | Runs Next.js Dashboard in dev/watch mode (`localhost:3001`). |
+| `npm run dev:core` | Runs TypeScript watch mode for `apm-optima/core`. |
+| `npm run dev:express` | Launches the Express integration demo. |
+| `npm run dev:nest` | Launches the NestJS integration demo. |
+| `npm test` | Runs test suites inside `apm-optima/core`. |
+
+---
+
+## Development Guidelines
+
+**Working with Core and Dashboard**
+
+1. **Dashboard Changes:** Any UI changes inside `packages/dashboard` need to be statically exported before being served via `apm-optima/core`.
+2. **Local Linking:** Thanks to `npm workspaces`, `example-app` automatically links to `apm-optima/core` in real time without needing `npm link`.
+3. **TypeScript:** Ensure all packages compile without errors (`npm run build`) before submitting changes.
+
+---
+
+## Submitting a Pull Request
+
+1. **Fork & Branch:** Create a fork of the repository and create a new feature branch:
+```bash
+git checkout -b feat/your-feature-name
+```
+2. **Commit Changes:** Write clear, concise commit messages following conventions:
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `refactor`: Code improvements without functional changes
+3. **Push & Open PR:** Push your branch to GitHub and open a Pull Request against the `main` branch. Provide a clear summary of your changes in the PR description.
+
+---
+
+## Need Help?
+
+If you run into issues or have questions, feel free to open a [GitHub Issue](https://github.com/Nosalis1/Optima/issues) or reach out through discussions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksa Stanojevic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+<h1>Optima APM</h1>
+
+<img src="docs/assets/optima-icon.svg" alt="Optima Icon" width="64" />
+
+<p><b>Lightweight, real-time Telemetry & Application Performance Monitoring for Node.js</b></p>
+
+[![npm version](https://img.shields.io/npm/v/@optima/core.svg?style=flat-square&color=fc6c26)](https://www.npmjs.com/package/apm-optima)
+[![license](https://img.shields.io/github/license/Nosalis1/Optima?style=flat-square&color=8A897C)](https://github.com/Nosalis1/Optima/blob/main/LICENSE)
+[![node version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![npm version](https://img.shields.io/badge/npm-%3E%3D10.0.0-red?style=flat-square)](https://www.npmjs.com/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+<br/>
+
+<a href="#key-features">Key Features</a> •
+<a href="#architecture">Architecture</a> •
+<a href="#quick-start">Quick Start</a> •
+<a href="#configuration-options">Configuration</a> •
+<a href="#dashboard-preview">Dashboard</a>
+
+</div>
+
+---
+
+## Overview
+
+**Optima** is an in-memory Application Performance Monitoring (APM) library designed for modern Node.js web services. It intercepts HTTP requests, tracks Event Loop lag, computes latency percentiles in real time, and identifies performance anomalies—all while serving an embedded React Dashboard with zero external database dependencies.
+
+> Built for **Express.js** and **NestJS** applications with low runtime overhead.
+
+---
+
+## Key Features
+
+- **Real-time Latency Metrics:** On-the-fly computation of $P_{50}$, $P_{95}$, and $P_{99}$ percentiles.
+- **Z-Score Anomaly Detection:** Statistical detection of unexpected response time spikes.
+- **In-Memory Storage:** Efficient metric aggregation using typed array (`Uint32Array`) histogram buckets and circular ring buffers.
+- **Embedded React Dashboard:** Zero-config static dashboard served directly through your primary Node.js HTTP server.
+- **Framework Agnostic Core:** Native support for both **Express** (middleware) and **NestJS** (interceptors/modules).
+- **Live Updates:** Low-latency WebSocket layer pushing live metrics straight to the UI.
+
+---
+
+## Dashboard Preview
+
+<div align="center">
+  <table border="0">
+    <tr>
+      <td width="33.3%"><img src="docs/assets/dashboard-1.png" alt="Optima Dashboard Preview 1" /></td>
+      <td width="33.3%"><img src="docs/assets/dashboard-2.png" alt="Optima Dashboard Preview 2" /></td>
+      <td width="33.3%"><img src="docs/assets/dashboard-3.png" alt="Optima Dashboard Preview 3" /></td>
+    </tr>
+  </table>
+  <td width="33.3%"><img src="docs/assets/dashboard-1-dark.png" alt="Optima Dashboard Preview 3" /></td>
+  <p><i>Real-time monitoring interface served directly via <code>/optima-metrics</code>.</i></p>
+</div>
+
+---
+
+## Architecture
+
+Optima is structured as a **Monorepo** managed with `npm workspaces`:
+
+```
+├── packages/
+│   └── core/          # Telemetry engine, interceptors, and WebSocket adapters (apm-optima/core)
+│   └── dashboard/     # Next.js React Dashboard (exported statically into apm-optima/core)
+├── apps/              # Integration & demo application (Express & NestJS)
+```
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm i apm-optima
+# or
+pnpm add apm-optima
+# or
+yarn add apm-optima
+```
+
+### Express.js Integration
+
+Attach Optima using setupOptima and hook the HTTP server instance:
+```ts
+const express = require('express');
+const { setupOptima } = require('apm-optima/express');
+
+const app = express();
+app.use(express.json());
+
+// Initialize Optima telemetry & embed UI
+const optima = setupOptima(app, {
+  dashboardPath: '/optima-metrics',
+  publisher: {
+    intervalMs: 1000,
+    slowLatencyThresholdMs: 500,
+  },
+});
+
+app.get('/api/v1/resource', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+const server = app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+
+// Attach WebSocket server & background timers
+const stopMetrics = optima.attachServer(server);
+```
+
+### NestJS Integration
+
+Import MetricsModule into your root application module:
+```ts
+import { Module } from '@nestjs/common';
+import { MetricsModule } from 'apm-optima/nest';
+
+@Module({
+  imports: [
+    MetricsModule.forRoot({
+      dashboardPath: '/optima-metrics',
+      publisher: {
+        intervalMs: 1000,
+        slowLatencyThresholdMs: 500,
+      },
+      excludePaths: ['/health'],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dashboardPath` | `string \| false` | `/optima-metrics` | Route endpoint for serving the embedded UI (`false` to disable). |
+| `simulation` | `false \| { intervalMs: number, requestsPerTick: number }` | `false` | Generates synthetic traffic for local testing and load simulation. |
+| `publisher.intervalMs` | `number` | `1000` | Broadcast interval (in ms) for pushing telemetry updates over WebSockets. |
+| `publisher.slowLatencyThresholdMs` | `number` | `500` | Latency limit in milliseconds above which requests are flagged as slow. |
+| `publisher.eventLoopLagThresholdMs` | `number` | `50` | Event Loop delay threshold in milliseconds for triggering lag alerts. |
+| `publisher.eventLoopResolutionMs` | `number` | `10` | Sampling resolution interval for computing Event Loop delay. |
+| `tickIntervalMs` | `number` | `250` | Resolution interval for recalculating internal metrics and buckets. |
+| `excludePaths` | `string[]` | `['/_next/*','/_next/**','*.map','/favicon.ico','/metrics_pack']` | Array of route patterns or paths to skip from metric collection (e.g., `/health`). |
+| `consoleLog` | `boolean` | `false` | Enables logging internal system events and alerts to `stdout`. |
+| `ringBufferSize` | `number` | `60` | Capacity of the internal ring buffer used for storing time-series data. |
+| `alertBufferSize` | `number` | `100` | Maximum capacity of the buffer holding recent alerts and detected anomalies. |
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!  
+Feel free to check out the [issues page](https://github.com/Nosalis1/Optima/issues).
+
+Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a Pull Request or opening an issue.
+
+## License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.

package/docs/assets/optima-icon.svg

@@ -0,0 +1,39 @@
+<svg
+            width="64"
+            height="64"
+            viewBox="0 0 200 200"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+        >
+            <circle
+                cx="100"
+                cy="100"
+                r="75"
+                stroke="white"
+                strokeWidth="7"
+                strokeOpacity="0.25"
+            />
+
+            <path
+                d="M 45 135 A 65 65 0 1 1 155 135"
+                stroke="white"
+                strokeWidth="10"
+                strokeLinecap="round"
+            />
+
+            <circle cx="50" cy="130" r="4" fill="white" />
+            <circle cx="100" cy="42" r="4" fill="white" />
+            <circle cx="150" cy="130" r="4" fill="white" />
+
+            <rect x="78" y="130" width="7" height="18" rx="3.5" fill="white" fillOpacity="0.5" />
+            <rect x="92" y="118" width="7" height="30" rx="3.5" fill="white" fillOpacity="0.9" />
+            <rect x="106" y="124" width="7" height="24" rx="3.5" fill="white" fillOpacity="0.6" />
+
+            <path
+                d="M 100 100 L 132 68"
+                stroke="white"
+                strokeWidth="8"
+                strokeLinecap="round"
+            />
+            <circle cx="100" cy="100" r="8" fill="white" />
+        </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apm-optima",
-    "version": "0.0.1",
+    "version": "1.0.1",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "publishConfig": {
@@ -34,6 +34,9 @@
     "files": [
         "dist",
         "README.md",
+        "LICENSE",
+        "CONTRIBUTING.md",
+        "docs",
         "package.json"
     ],
     "scripts": {
@@ -68,4 +71,4 @@
         "ts-jest": "^29.0.0",
         "typescript": "^5.0.0"
     }
-}
+}