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

npm install @oisasoje/gloo

Setup & Usage

1. Register the Middleware

Mount the Gloo middleware at the top of your Express app:

import express from "express";
import { gloo } from "@oisasoje/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():

import { span, log, error } from "@oisasoje/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:

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 Gloo

The easiest way to start both the receiver and the visualizer dashboard is using the Gloo CLI:

npm install -g @oisasoje/gloo-cli
gloo dev

This will automatically:

1. Boot the telemetry receiver on port 7777.
2. Serve the static visualizer dashboard.
3. Open your default web browser to the dashboard at http://localhost:7777.

Architecture (v1)

[ Express App (Gloo SDK) ]
           │
      (HTTP POST)
           ▼
  localhost:7777 (Gloo Receiver)
           │
      (Serves static visualizer & WebSockets)
           ▼
  Browser Dashboard (UI on port 7777)

API Reference

gloo()

Express middleware that initializes request-scoped tracing context.

app.use(gloo());

span(name, fn)

Wraps a block of code and measures execution time. Supports nested calls.

await span("db.query", async () => {
  return db.user.findMany();
});

log(value)

Attaches a log entry to the active trace scope.

log("fetching user data");

error(err)

Records an error instance in the active trace timeline.

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.