@tclohm/yoban 1.0.0

package/README.MD

@@ -0,0 +1,43 @@
+# @tclohm/yoban
+
+> Lightweight Express middleware for real-time API performance monitoring and SLA alerting.
+
+## Install
+```
+npm install @tclohm/yoban 
+```
+
+## Usage
+```javascript
+import { yoban } from '@tclohm/yoban';
+
+const metrics = new yoban({
+  service: "payments",
+  flushInterval: 10000,       // flush every 10s
+  violationThreshold: 0.5,    // alert if >50% of requests violate SLA
+  sla: { premium: 400, standard: 800 },
+  notify: {
+    slack: process.env.SLACK_WEBHOOK,
+    pagerduty: process.env.PAGERDUTY_KEY
+  },
+  enrichEvent: (req) => ({
+    tier: req.user?.tier ?? 'standard'
+  })
+});
+
+app.use(metrics.middleware());
+```
+
+## Config
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `service` | string | required | Name of your service |
+| `flushInterval` | number | 10000 | How often to flush in ms |
+| `violationThreshold` | number | 0.5 | Violation rate to trigger alert |
+| `sla` | object | — | SLA thresholds per tier in ms |
+| `notify.slack` | string | — | Slack webhook URL |
+| `notify.pagerduty` | string | — | PagerDuty routing key |
+| `enrichEvent` | function | — | Add custom metadata per request |
+
+## License
+MIT © tclohm

package/index.js

@@ -0,0 +1 @@
+export { yoban } from './src/yoban.js';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tclohm/yoban",
+  "version": "1.0.0",
+  "description": "Lightweight middleware for real-time API performance monitoring and SLA alerting",
+  "keywords": [
+    "monitoring",
+    "metrics",
+    "sla",
+    "middleware",
+    "alerting"
+  ],
+  "homepage": "https://github.com/tclohm/yoban#readme",
+  "bugs": {
+    "url": "https://github.com/tclohm/yoban/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tclohm/yoban.git"
+  },
+  "license": "MIT",
+  "author": "tclohm",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/notifiers/pagerduty.js

@@ -0,0 +1,19 @@
+export async function notifyPagerDuty(routingKey, entry, violationRate) {
+  await fetch("https://events.pagerduty.com/v2/enqueue", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      routing_key: routingKey,
+      event_action: "trigger",
+      payload: {
+        summary: `${entry.service} SLA violation on ${entry.route} (${entry.tier})`,
+        severity: "critical",
+        custom_details: {
+          violationRate: `${(violationRate * 100).toFixed(2)}%`,
+          mean: entry.mean,
+          median: entry.median
+        }
+      }
+    })
+  });
+}

package/src/notifiers/slack.js

@@ -0,0 +1,9 @@
+export async function notifySlack(webhookUrl, entry, violationRate) {
+  await fetch(webhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      text: `[yoban ALERT]: \`${entry.service}\` on \`${entry.route}\` (${entry.tier}) has a *${(violationRate * 100).toFixed(2)}%* SLA violation rate!`
+    })
+  });
+}

package/src/yoban.js

@@ -0,0 +1,82 @@
+import { notifySlack } from './notifiers/slack.js';
+import { notifyPagerDuty } from './notifiers/pagerduty.js';
+
+export class yoban {
+  #buffer = [];
+  #aggregated = [];
+
+  constructor(config) {
+    this.config = config;
+    this.#startFlushing();
+  }
+
+  middleware() {
+    return (req, res, next) => {
+      const start = Date.now();
+      res.on('finish', () => {
+        const duration = Date.now() - start;
+        const extra = this.config.enrichEvent ? this.config.enrichEvent(req) : {};
+        this.#buffer.push({
+          service: this.config.service,
+          method: req.method,
+          route: req.route?.path ?? req.path,
+          status: res.statusCode,
+          duration,
+          timestamp: Date.now(),
+          ...extra
+        });
+      });
+      next();
+    };
+  }
+
+  #startFlushing() {
+    setInterval(() => this.flush(), this.config.flushInterval ?? 10000);
+  }
+
+  flush() {
+    const events = this.#buffer.splice(0);
+    if (events.length === 0) return;
+    this.#aggregated = [...this.#aggregated, ...this.#parse(events)];
+    this.#checkAlerts();
+  }
+
+  #parse(events) {
+    const groups = new Map();
+    for (const event of events) {
+      const key = `${event.service} ${event.route} ${event.tier}`;
+      if (!groups.has(key)) {
+        groups.set(key, { service: event.service, route: event.route, tier: event.tier, durations: [] });
+      }
+      groups.get(key).durations.push(event.duration);
+    }
+    return Array.from(groups.values()).map(({ service, route, tier, durations }) => {
+      const sorted = [...durations].sort((a, b) => a - b);
+      const mean   = durations.reduce((sum, d) => sum + d, 0) / durations.length;
+      const mid    = Math.floor(sorted.length / 2);
+      const median = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+      return { service, route, tier, mean: Math.round(mean), median, durations };
+    });
+  }
+
+  async #checkAlerts() {
+    for (const entry of this.#aggregated) {
+      const threshold = this.config.sla?.[entry.tier];
+      if (!threshold) continue;
+
+      const violations = entry.durations.filter(d => d > threshold).length;
+      const violationRate = violations / entry.durations.length;
+
+      if (violationRate > (this.config.violationThreshold ?? 0.5)) {
+        console.log(`[ yoban ALERT ]: ${entry.service} ${entry.route} (${entry.tier}) violation rate ${(violationRate * 100).toFixed(2)}%`);
+
+        if (this.config.notify?.slack) {
+          await notifySlack(this.config.notify.slack, entry, violationRate);
+        }
+        if (this.config.notify?.pagerduty) {
+          await notifyPagerDuty(this.config.notify.pagerduty, entry, violationRate);
+        }
+      }
+    }
+  }
+}