Developer-First Observability

"use client";

import { ObservabilityDashboard } from "@stacklenzz/ui";

export default function AdminObservabilityPage() {
  return (
    <main className="min-h-screen bg-background">
      <ObservabilityDashboard
        config={{
          endpoint: "http://localhost:5000/api/observability/stats",
          refreshIntervalMs: 5000,
        }}
        defaultDashboard="full"
        showSwitcher={true}
      />
    </main>
  );
}

Theme selections automatically persist immediately to localStorage (key: stacklenzz_theme). Upon page reloads or navigating between administrative views, your chosen theme is instantly restored without visual flickering.

import express from "express";
import { setupObservability } from "@stacklenzz/server/express";
import { logger, addBreadcrumb } from "@stacklenzz/server/core";

const app = express();

// Automatically configures:
// 1. /metrics (Prometheus scraper)
// 2. /api/observability/stats (JSON telemetry feed for dashboard UI)
// 3. OpenTelemetry NodeSDK distributed tracing
// 4. Winston JSON structured logging
setupObservability(app, {
  serviceName: "billing-service",
  environment: "production",
});

app.get("/api/checkout", (req, res) => {
  addBreadcrumb({ category: "cart", message: "Processing card payment", level: "info" });
  res.json({ status: "success" });
});

// Fallback for non-existent routes (captured as 404 in dashboard)
app.use((req, res) => {
  res.status(404).json({ statusCode: 404, error: "Not Found", message: `Cannot ${req.method} ${req.url}` });
});

app.listen(5000, () => console.log("Server listening on port 5000"));

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { ObservabilityModule } from "@stacklenzz/server/nestjs";

@Module({
  imports: [
    ConfigModule.forRoot(),
    ObservabilityModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        serviceName: config.get<string>("APP_NAME", "auth-service"),
        environment: config.get<string>("NODE_ENV", "production"),
      }),
    }),
  ],
})
export class AppModule {}

import { Hono } from "hono";
import { getObservabilitySnapshot, recordError } from "@stacklenzz/server/core";

const app = new Hono();

app.get("/api/observability/stats", async (c) => {
  c.header("Access-Control-Allow-Origin", "*");
  return c.json(await getObservabilitySnapshot());
});

app.onError((err, c) => {
  recordError({
    message: err.message,
    stack: err.stack,
    route: c.req.path,
    method: c.req.method,
    statusCode: 500,
  });
  return c.text("Internal Server Error", 500);
});

import { getObservabilitySnapshot, Counter, register } from "@stacklenzz/server/core";

// 1. Register custom business metric on the /metrics endpoint
const ordersCounter = new Counter({
  name: "orders_processed_total",
  help: "Total processed checkout orders",
  registers: [register],
});
ordersCounter.inc();

// 2. Fetch live telemetry JSON directly in backend code
const snapshot = await getObservabilitySnapshot();
console.log("Current Error Rate:", snapshot.summary.errorRate);
console.log("Active Requests:", snapshot.summary.activeRequests);

import { initTracing, logger } from "@stacklenzz/server";

// Tracing auto-initializes by default, injecting trace_id and span_id into Winston logs
logger.info("Processing order checkout", { orderId: "ORD-9912" });
// Output: {"level":"info","message":"Processing order checkout","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7"}

import { setupObservability, CrashLogEntry } from "@stacklenzz/server";

setupObservability(app, {
  serviceName: "payment-api",
  environment: "production",
  // Configure pluggable crash log adaptor for database persistence & UI management
  crashLogAdaptor: {
    // 1. Save 5xx server crash entry
    save: async (entry: CrashLogEntry) => {
      await db.crashLogs.create({ data: entry });
    },
    // 2. Query persisted logs for the UI dashboard
    list: async () => {
      return await db.crashLogs.findMany({ orderBy: { timestamp: "desc" } });
    },
    // 3. Delete an individual crash log from the UI dashboard
    delete: async (id: string) => {
      await db.crashLogs.delete({ where: { id } });
    },
    // 4. Purge all crash logs from the UI dashboard ("Clear All Logs")
    clearAll: async () => {
      await db.crashLogs.deleteMany({});
    },
  },
});

// middleware.ts (Next.js App Router)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  if (req.nextUrl.pathname.startsWith("/admin/observability")) {
    const adminToken = req.cookies.get("admin_session");
    if (!adminToken) {
      return NextResponse.redirect(new URL("/login", req.url));
    }
  }
  return NextResponse.next();
}