@oisasoje/gloo 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# Gloo 🚀
+
+A lightweight Node.js/Express middleware for tracing HTTP requests using spans and logs, with a local receiver + live dashboard for inspection.
+
+Gloo helps you see where time is spent inside a request in real time.
+
+---
+
+## Features (v1)
+
+* ⚡ **Express Middleware:** Dynamic request-scoped lifecycle tracing.
+* 🌳 **Nested Spans:** Wrap async/sync blocks to measure nested code paths.
+* 🧠 **Scoped Context:** Lightweight request-scoped isolation via `AsyncLocalStorage`.
+* 📊 **Live Telemetry:** Streams active spans and logs over WebSockets in real time.
+* 🖥 **Developer Dashboard:** A sleek developer UI built specifically to inspect request bottlenecks.
+* 🪶 **Featherweight SDK:** Zero runtime third-party package dependencies.
+
+---
+
+## Installation
+
+```bash
+npm install gloo
+```
+
+---
+
+## Setup & Usage
+
+### 1. Register the Middleware
+Mount the Gloo middleware at the top of your Express app:
+
+```javascript
+import express from "express";
+import { gloo } from "gloo";
+
+const app = express();
+
+app.use(gloo());
+```
+
+### 2. Wrap Spans & Logs
+Track synchronous and asynchronous operations using `span()`, and write trace-scoped logs using `log()` or `error()`:
+
+```javascript
+import { span, log, error } from "gloo";
+
+app.get("/users/:id", async (req, res) => {
+  await span("get-user", async () => {
+    try {
+      const response = await fetch(`https://api.example.com/user/${req.params.id}`);
+      const data = await response.json();
+
+      await span("log-user-data", async () => {
+        log("user fetched successfully");
+      });
+      
+    } catch (err) {
+      error(err);
+    }
+  });
+
+  res.json({ status: "ok" });
+});
+```
+
+---
+
+## Mental Model
+
+Gloo tracks each incoming request as a tree of nested spans and logs:
+
+```text
+HTTP Request
+├── middleware execution
+├── span: get-user
+│    └── span: log-user-data (with log details)
+└── response
+```
+
+Each span records:
+* Start time & end time
+* Total duration (latency)
+* Success/error state
+
+---
+
+## Start the Receiver
+
+Before running your application, start the local telemetry receiver. It acts as the collector database and WebSocket broadcaster:
+
+```bash
+npx gloo-receiver
+```
+
+* **Collector API:** Runs on `http://localhost:7777`
+* **Dashboard stream:** Broadcasts live trace payloads via WebSockets.
+
+---
+
+## Run the Dashboard
+
+To view your traces in real-time, launch the visualizer dashboard app:
+
+```bash
+npm run dev
+```
+
+Then open your browser to:
+```text
+http://localhost:3500
+```
+
+The dashboard automatically hooks up to the receiver and streams live traces.
+
+---
+
+## Architecture (v1)
+
+```text
+[ Express App ]
+      ↓
+   Gloo SDK
+      ↓
+localhost:7777 (Receiver)
+      ↓
+WebSocket Stream
+      ↓
+Gloo Dashboard (UI on port 3500)
+```
+
+---
+
+## API Reference
+
+### `gloo()`
+Express middleware that initializes request-scoped tracing context.
+```javascript
+app.use(gloo());
+```
+
+### `span(name, fn)`
+Wraps a block of code and measures execution time. Supports nested calls.
+```javascript
+await span("db.query", async () => {
+  return db.user.findMany();
+});
+```
+
+### `log(value)`
+Attaches a log entry to the active trace scope.
+```javascript
+log("fetching user data");
+```
+
+### `error(err)`
+Records an error instance in the active trace timeline.
+```javascript
+error(err);
+```
+
+---
+
+## Notes
+* Gloo is custom-designed for local development observability.
+* The telemetry receiver must be running for traces to be successfully captured.
+* The dashboard reads from the receiver server, remaining completely decoupled from your application code.

package/asyncLocalStorage.js

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const als = new AsyncLocalStorage();
+
+export default als;

package/endSpan.js

@@ -0,0 +1,13 @@
+import als from "./asyncLocalStorage.js";
+
+const endSpan = (span) => {
+  const trace = als.getStore();
+
+  if (!trace) return;
+
+  const now = Date.now();
+  span.endTime = now;
+  span.latency = now - span.startTime;
+};
+
+export default endSpan;

package/error.js

@@ -0,0 +1,14 @@
+import als from "./asyncLocalStorage.js";
+
+const error = (msg) => {
+  const trace = als.getStore();
+
+  if (!trace) return;
+
+  const errorTag = msg instanceof Error ? msg.message : String(msg);
+
+  const now = Date.now();
+  trace.errors.push({ tag: errorTag, startTime: now, latency: 0 });
+};
+
+export default error;

package/gloo.js

@@ -0,0 +1,35 @@
+import als from "./asyncLocalStorage.js";
+import initTrace from "./initTrace.js";
+import { sendTrace } from "./sendTrace.js";
+
+const gloo = () => {
+  return (req, res, next) => {
+    const { receiverId, traceData } = initTrace(req, res);
+
+    let finished = false;
+    const finalizeTrace = (status) => {
+      if (finished) return;
+      finished = true;
+
+      const latency = Date.now() - traceData.startTime;
+      traceData.latency = latency;
+      traceData.status = status || res.statusCode;
+      traceData.responseTime = `${latency}ms`;
+
+      sendTrace(traceData);
+    };
+
+    als.run(traceData, () => {
+      res.on("finish", () => finalizeTrace(res.statusCode));
+      res.on("close", () => {
+        if (!res.writableEnded) {
+          finalizeTrace(499); // 499 Client Closed Request
+        }
+      });
+
+      next();
+    });
+  };
+};
+
+export default gloo;

package/index.js

@@ -0,0 +1,6 @@
+import gloo from "./gloo.js";
+import span from "./span.js";
+import log from "./log.js";
+import error from "./error.js";
+
+export { gloo, span, log, error };

package/initTrace.js

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+
+const initTrace = (req, res) => {
+  const receiverId = crypto.randomUUID();
+  req.glooId = receiverId;
+
+  const traceData = {
+    id: receiverId,
+    method: req.method,
+    url: req.originalUrl,
+    status: res.statusCode,
+    startTime: Date.now(),
+    logs: [],
+    spans: [],
+    errors: [],
+  };
+
+  return { receiverId, traceData };
+};
+
+export default initTrace;

package/log.js

@@ -0,0 +1,12 @@
+import als from "./asyncLocalStorage.js";
+
+const log = (msg) => {
+  const trace = als.getStore();
+
+  if (!trace) return;
+
+  const now = Date.now();
+  trace.logs.push({ tag: msg, startTime: now, latency: 0 });
+};
+
+export default log;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@oisasoje/gloo",
+  "version": "1.0.0",
+  "description": "Premium real-time request tracing, nested span tracking, and error logging SDK for Node.js Express.",
+  "license": "ISC",
+  "author": "Victor",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "gloo.js",
+    "asyncLocalStorage.js",
+    "initTrace.js",
+    "sendTrace.js",
+    "startSpan.js",
+    "endSpan.js",
+    "span.js",
+    "log.js",
+    "error.js"
+  ],
+  "dependencies": {}
+}

package/sendTrace.js

@@ -0,0 +1,15 @@
+export const sendTrace = async (event) => {
+  try {
+    const response = await fetch("http://localhost:7777/gloo/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to send trace: ${response.status}`);
+    }
+  } catch (error) {
+    console.error("Gloo transport error:", error.message);
+  }
+};

package/span.js

@@ -0,0 +1,30 @@
+import startSpan from "./startSpan.js";
+import endSpan from "./endSpan.js";
+import als from "./asyncLocalStorage.js";
+
+const span = async (name, fn) => {
+  const trace = als.getStore();
+
+  if (!trace) {
+    try {
+      return await fn();
+    } catch (err) {
+      throw err;
+    }
+  }
+  const s = startSpan(name);
+
+  try {
+    const result = await fn();
+    s.status = "ok";
+    return result;
+  } catch (err) {
+    s.status = "error";
+    s.error = err.message || String(err);
+    throw err;
+  } finally {
+    endSpan(s);
+  }
+};
+
+export default span;

package/startSpan.js

@@ -0,0 +1,13 @@
+import als from "./asyncLocalStorage.js";
+
+const startSpan = (name) => {
+  const trace = als.getStore();
+
+  if (!trace) return;
+
+  const span = { tag: name, startTime: Date.now() };
+  trace.spans.push(span);
+  return span;
+};
+
+export default startSpan;