observe-node 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "observe-node",
+  "version": "1.0.0",
+  "description": "Structured logs + Prometheus metrics SDK for Node.js (Loki/Grafana ready)",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "files": ["src"],
+  "keywords": ["observability","logging","metrics","prometheus","loki","grafana"],
+  "license": "MIT",
+  "scripts": {
+    "dev": "nodemon example.js"
+  },
+  "dependencies": {
+    "axios": "^1.13.5",
+    "prom-client": "^15.1.3"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.14"
+  }
+}

package/src/config.js

@@ -0,0 +1,34 @@
+// src/config.js
+const path = require("path");
+const os = require("os");
+const { createEventEmitter } = require("./schema/event");
+
+function defaultLogDir() {
+  // windows
+  if (process.platform === "win32") {
+    return path.join(os.homedir(), ".observe");
+  }
+  // linux/mac
+  return "/var/log/observe";
+}
+
+function loadConfig(userConfig) {
+  const config = {
+    app: userConfig.app || "unknown-app",
+    env: userConfig.env || process.env.NODE_ENV || "dev",
+
+    // ✅ output modes: "stdout" | "file" | "both"
+    output: userConfig.output || "file",
+
+    logDir: userConfig.logDir || process.env.OBSERVE_LOG_DIR || defaultLogDir(),
+    logFileName: userConfig.logFileName || `${userConfig.app || "unknown-app"}.log`,
+
+    metrics: userConfig.metrics !== false,
+    console: userConfig.console !== false,
+  };
+
+  config.emitEvent = createEventEmitter(config);
+  return config;
+}
+
+module.exports = { loadConfig };

package/src/http/express.js

@@ -0,0 +1,64 @@
+// src/http/express.js
+const { runWithContext } = require("../utils/context");
+const { newId } = require("../utils/ids");
+
+function getRoutePath(req) {
+  // Prefer express route pattern if available (best for metrics + grouping)
+  if (req.route && req.route.path) {
+    const base = req.baseUrl || "";
+    return `${base}${req.route.path}`;
+  }
+
+  // Fallback: originalUrl without querystring
+  const raw = req.originalUrl || req.url || "";
+  return raw.split("?")[0] || raw;
+}
+
+function expressMiddleware(observe) {
+  const config = observe.__config;
+
+  return function observeExpress(req, res, next) {
+    const requestId =
+      req.headers["x-request-id"] ||
+      req.headers["x-correlation-id"] ||
+      newId();
+
+    // expose id to downstream services
+    res.setHeader("x-request-id", String(requestId));
+
+    const start = process.hrtime.bigint();
+
+    runWithContext({ request_id: String(requestId) }, () => {
+      res.on("finish", () => {
+        const end = process.hrtime.bigint();
+        const durationMs = Number(end - start) / 1_000_000;
+
+        const status = res.statusCode;
+        const level = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+
+        const path = getRoutePath(req);
+
+        config.emitEvent({
+          event_name: "http.request",
+          level,
+          message: "HTTP request completed",
+          http: {
+            method: req.method,
+            path,
+            status,
+            duration_ms: Math.round(durationMs),
+          },
+        });
+
+        // metrics hook (if enabled)
+        if (typeof config._observeHttpMetric === "function") {
+          config._observeHttpMetric(req.method, path, status, durationMs);
+        }
+      });
+
+      next();
+    });
+  };
+}
+
+module.exports = { expressMiddleware };

package/src/http/expressError.js

@@ -0,0 +1,30 @@
+// src/http/expressError.js
+function createExpressErrorMiddleware(observe, opts = {}) {
+  const {
+    includeStack = true,
+  } = opts;
+
+  // eslint-disable-next-line no-unused-vars
+  return function observeExpressError(err, req, res, next) {
+    const status = err.status || err.statusCode || 500;
+
+    // your apps may set these:
+    const code = err.code; // e.g. "AUTH-401" / "WH-INV-001"
+
+    observe.emit({
+      event_name: "error",
+      level: "error",
+      message: err.message || "Unhandled error",
+      error: {
+        name: err.name || "Error",
+        code,
+        status,
+        stack: includeStack ? err.stack : undefined,
+      },
+    });
+
+    next(err);
+  };
+}
+
+module.exports = { createExpressErrorMiddleware };

package/src/http/metricsExpress.js

@@ -0,0 +1,15 @@
+// src/http/metricsExpress.js
+const { metricsHandler } = require("../metrics/handler");
+
+function metricsExpress(observe) {
+  return async function (req, res) {
+    try {
+      await metricsHandler(observe, req, res);
+    } catch (e) {
+      res.statusCode = 500;
+      res.end("metrics error");
+    }
+  };
+}
+
+module.exports = { metricsExpress };

package/src/index.js

@@ -0,0 +1,8 @@
+// src/index.js
+const start = require("./start");
+const { expressMiddleware } = require("./http/express");
+
+module.exports = {
+  start,
+  expressMiddleware,
+};

package/src/logger/console.js

@@ -0,0 +1,75 @@
+// src/logger/console.js
+const util = require("util");
+
+function safeStringify(args) {
+  try {
+    // util.format handles strings + objects like console does
+    return util.format(...args);
+  } catch {
+    try {
+      return args.map(a => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+    } catch {
+      return "[unstringifiable]";
+    }
+  }
+}
+
+function initConsolePatch(config) {
+  if (config.console === false) return;
+
+  const original = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+  };
+
+  // prevent recursion when our writer uses console.log(JSON)
+  let inPatch = false;
+
+  function wrap(level, origFn) {
+    return function (...args) {
+      // always keep original console behavior
+      origFn.apply(console, args);
+
+      // avoid recursion
+      if (inPatch) return;
+      inPatch = true;
+
+      try {
+        const msg = safeStringify(args);
+
+        config.emitEvent({
+          event_name: "log.console",
+          level: level === "error" ? "error" : level === "warn" ? "warn" : "info",
+          message: msg,
+          console: {
+            level,
+          },
+        });
+      } catch {
+        // never crash app
+      } finally {
+        inPatch = false;
+      }
+    };
+  }
+
+  console.log = wrap("log", original.log);
+  console.info = wrap("info", original.info);
+  console.warn = wrap("warn", original.warn);
+  console.error = wrap("error", original.error);
+  console.debug = wrap("debug", original.debug);
+
+  // allow restore
+  config._restoreConsole = () => {
+    console.log = original.log;
+    console.info = original.info;
+    console.warn = original.warn;
+    console.error = original.error;
+    console.debug = original.debug;
+  };
+}
+
+module.exports = { initConsolePatch };

package/src/logger/crash.js

@@ -0,0 +1,27 @@
+// src/logger/crash.js
+function initCrashHandlers(config) {
+  process.on("uncaughtException", (err) => {
+    config.emitEvent({
+      event_name: "process.crash",
+      level: "fatal",
+      error: {
+        type: err.name,
+        message: err.message,
+        stack: err.stack?.replace(/\n/g, " | ")
+      }
+    });
+    process.exit(1);
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    config.emitEvent({
+      event_name: "process.rejection",
+      level: "error",
+      error: {
+        message: String(reason)
+      }
+    });
+  });
+}
+
+module.exports = { initCrashHandlers };

package/src/logger/patchConsole.js

@@ -0,0 +1,43 @@
+// src/logger/patchConsole.js
+function safeToString(v) {
+  try {
+    if (typeof v === "string") return v;
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function patchConsole(observe, opts = {}) {
+  const { enabled = true } = opts;
+  if (!enabled) return () => {};
+
+  const original = {
+    log: console.log,
+    warn: console.warn,
+    error: console.error,
+  };
+
+  console.log = (...args) => {
+    observe.emit({ event_name: "log", level: "info", message: args.map(safeToString).join(" "), log: { logger: "console", args } });
+    original.log(...args);
+  };
+
+  console.warn = (...args) => {
+    observe.emit({ event_name: "log", level: "warn", message: args.map(safeToString).join(" "), log: { logger: "console", args } });
+    original.warn(...args);
+  };
+
+  console.error = (...args) => {
+    observe.emit({ event_name: "log", level: "error", message: args.map(safeToString).join(" "), log: { logger: "console", args } });
+    original.error(...args);
+  };
+
+  return function restore() {
+    console.log = original.log;
+    console.warn = original.warn;
+    console.error = original.error;
+  };
+}
+
+module.exports = { patchConsole };

package/src/logger/writer.js

@@ -0,0 +1,72 @@
+// src/logger/writer.js
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+let stream = null;
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function openStream(filePath) {
+  return fs.createWriteStream(filePath, { flags: "a" });
+}
+
+function buildFilePath(config) {
+  const primaryDir = config.logDir;
+  const primaryPath = path.join(primaryDir, config.logFileName);
+
+  // try primary
+  if (ensureDir(primaryDir)) {
+    try {
+      const s = openStream(primaryPath);
+      return { filePath: primaryPath, stream: s };
+    } catch {}
+  }
+
+  // fallback to home dir
+  const fallbackDir = path.join(os.homedir(), ".observe");
+  const fallbackPath = path.join(fallbackDir, config.logFileName);
+  ensureDir(fallbackDir);
+  const s2 = openStream(fallbackPath);
+  return { filePath: fallbackPath, stream: s2 };
+}
+
+function initWriter(config) {
+  const { filePath, stream: s } = buildFilePath(config);
+  stream = s;
+  config._logFilePath = filePath;
+
+  config.write = (event) => {
+    const line = JSON.stringify(event) + "\n";
+
+    // stdout
+    if (config.output === "stdout" || config.output === "both") {
+      try {
+        process.stdout.write(line);
+      } catch {}
+    }
+
+    // file
+    if (config.output === "file" || config.output === "both") {
+      try {
+        stream.write(line);
+      } catch {}
+    }
+  };
+
+  config._closeWriter = () => {
+    try {
+      stream?.end();
+    } catch {}
+    stream = null;
+  };
+}
+
+module.exports = { initWriter };

package/src/metrics/handler.js

@@ -0,0 +1,16 @@
+// src/metrics/handler.js
+async function metricsHandler(observe, req, res) {
+  const config = observe.__config;
+  if (!config.metricsRegistry) {
+    res.statusCode = 404;
+    res.end("metrics disabled");
+    return;
+  }
+
+  res.setHeader("Content-Type", config.metricsRegistry.register.contentType);
+  const body = await config.metricsRegistry.register.metrics();
+  res.statusCode = 200;
+  res.end(body);
+}
+
+module.exports = { metricsHandler };

package/src/metrics/http.js

@@ -0,0 +1,41 @@
+// src/metrics/http.js
+function initHttpMetrics(config) {
+  if (!config.metricsRegistry) return;
+
+  const client = config.metricsRegistry;
+
+  const httpReqCount = new client.Counter({
+    name: "observe_http_requests_total",
+    help: "Total HTTP requests",
+    labelNames: ["app", "env", "method", "path", "status"]
+  });
+
+  const httpReqDuration = new client.Histogram({
+    name: "observe_http_request_duration_ms",
+    help: "HTTP request duration in ms",
+    labelNames: ["app", "env", "method", "path", "status"],
+    buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]
+  });
+
+  // Keep path label sane (avoid high-cardinality)
+  function normalizePath(path) {
+    // basic cleanup: remove query string
+    const p = String(path || "").split("?")[0];
+    // optional: collapse numeric ids (simple rule)
+    return p.replace(/\/\d+(\b|\/)/g, "/:id$1");
+  }
+
+  config._observeHttpMetric = (method, path, status, durationMs) => {
+    const labels = {
+      app: config.app,
+      env: config.env,
+      method: String(method || "GET"),
+      path: normalizePath(path),
+      status: String(status || 0)
+    };
+    httpReqCount.inc(labels, 1);
+    httpReqDuration.observe(labels, durationMs);
+  };
+}
+
+module.exports = { initHttpMetrics };

package/src/metrics/registry.js

@@ -0,0 +1,12 @@
+// src/metrics/registry.js
+const client = require("prom-client");
+
+function initMetrics(config) {
+  if (!config.metrics) return;
+
+  client.collectDefaultMetrics();
+
+  config.metricsRegistry = client;
+}
+
+module.exports = { initMetrics };

package/src/schema/event.js

@@ -0,0 +1,52 @@
+// src/schema/event.js
+const os = require("os");
+const { getContext } = require("../utils/context");
+const { newId } = require("../utils/ids");
+
+function createEventEmitter(config) {
+  return function emitEvent(partial = {}) {
+    const ctx = getContext();
+
+    // pick only safe/known top-level from partial
+    const {
+      level,
+      event_name,
+      message,
+      request_id,
+      trace_id,
+      span_id,
+      ...details
+    } = partial;
+
+    const event = {
+      schema_version: "1.0",
+      source: "observe-sdk",
+      event_id: newId(),
+      timestamp: new Date().toISOString(),
+
+      app: config.app,
+      env: config.env,
+
+      // nice to have for prod
+      service: config.service || config.app,
+      version: config.version,
+      host: os.hostname(),
+      pid: process.pid,
+
+      level: level || "info",
+      event_name,
+      message,
+
+      request_id: ctx?.request_id || request_id,
+      trace_id: ctx?.trace_id || trace_id,
+      span_id: ctx?.span_id || span_id,
+
+      // extra blocks: http, error, db, log, meta...
+      ...details,
+    };
+
+    config.write(event);
+  };
+}
+
+module.exports = { createEventEmitter };

package/src/start.js

@@ -0,0 +1,54 @@
+// src/start.js
+const { loadConfig } = require("./config");
+const { initWriter } = require("./logger/writer");
+const { initCrashHandlers } = require("./logger/crash");
+const { initMetrics } = require("./metrics/registry");
+const { initHttpMetrics } = require("./metrics/http");
+const { expressMiddleware } = require("./http/express");
+const { metricsExpress } = require("./http/metricsExpress");
+const { initConsolePatch } = require("./logger/console");
+
+function start(userConfig = {}) {
+  const config = loadConfig(userConfig);
+
+  initWriter(config);
+  initConsolePatch(config);
+  initCrashHandlers(config);
+  initMetrics(config);
+  initHttpMetrics(config);
+
+  // ✅ create object first
+  const observe = {
+    __config: config,
+    emit: config.emitEvent,
+    express: null,
+    metrics: null,
+    shutdown: null,
+  };
+
+  // ✅ then assign functions
+  observe.express = () => expressMiddleware(observe);
+  observe.metrics = () => metricsExpress(observe);
+  observe.shutdown = () => config._closeWriter?.();
+
+  // events
+  config.emitEvent({ event_name: "process.start", level: "info" });
+
+  config.emitEvent({
+    event_name: "observe.writer",
+    level: "info",
+    message: `observe logging to: ${config._logFilePath}`,
+  });
+
+  // graceful exit
+  const onExit = () => {
+    try { config._closeWriter?.(); } catch {}
+    process.exit(0);
+  };
+  process.on("SIGINT", onExit);
+  process.on("SIGTERM", onExit);
+
+  return observe;
+}
+
+module.exports = start;

package/src/utils/context.js

@@ -0,0 +1,23 @@
+// src/utils/context.js
+const { AsyncLocalStorage } = require("async_hooks");
+
+const als = new AsyncLocalStorage();
+
+function runWithContext(ctx, fn) {
+  return als.run(ctx, fn);
+}
+
+function setContext(patch) {
+  const store = als.getStore() || {};
+  Object.assign(store, patch);
+  // if no store exists, create one
+  if (!als.getStore()) {
+    als.enterWith(store);
+  }
+}
+
+function getContext() {
+  return als.getStore();
+}
+
+module.exports = { runWithContext, setContext, getContext };

package/src/utils/env.js

@@ -0,0 +1,20 @@
+// src/utils/env.js
+const fs = require("fs");
+
+function isDocker() {
+  try {
+    if (fs.existsSync("/.dockerenv")) return true;
+    const cgroup = fs.readFileSync("/proc/1/cgroup", "utf8");
+    return cgroup.includes("docker") || cgroup.includes("kubepods") || cgroup.includes("containerd");
+  } catch {
+    return false;
+  }
+}
+
+function runtime() {
+  if (process.env.KUBERNETES_SERVICE_HOST) return "k8s";
+  if (isDocker()) return "docker";
+  return "host";
+}
+
+module.exports = { isDocker, runtime };

package/src/utils/ids.js

@@ -0,0 +1,8 @@
+// src/utils/ids.js
+const crypto = require("crypto");
+
+function newId() {
+  return crypto.randomUUID();
+}
+
+module.exports = { newId };

package/src/utils/time.js

@@ -0,0 +1,11 @@
+// src/utils/time.js
+function nowHr() {
+  return process.hrtime.bigint();
+}
+
+function msSince(startHr) {
+  const end = process.hrtime.bigint();
+  return Number(end - startHr) / 1_000_000;
+}
+
+module.exports = { nowHr, msSince };