@bhooai/nexus-telemetry 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @bhooai/nexus-telemetry
+
+Structured logging, metrics, and trace/request-ID propagation.
+
+## Exports
+
+- **Logger** — JSON or pretty output, child loggers, levels, redaction of
+  sensitive fields (`password`, `secret`, `authorization`), console + rotating
+  file transports.
+- **MetricsRegistry** — counters and histograms; `counter(name, help)` registers
+  a counter, `inc(name, value, labels)` increments it, `toJSON()` snapshots.
+- **trace** — request/trace-ID helpers for propagation across Node → WS → Python.
+
+## Usage
+
+```ts
+import { Logger, MetricsRegistry } from '@bhooai/nexus-telemetry';
+
+const log = new Logger({ level: 'info', format: 'pretty', console: true, redact: ['password'] });
+log.info('listening', { port: 4000 });
+
+const metrics = new MetricsRegistry();
+metrics.counter('http_requests_total', 'Total HTTP requests');
+metrics.inc('http_requests_total', 1, { method: 'GET' });
+```
+
+> `counter()` returns the registered counter state; it does **not** chain `.inc()`.
+> Increment via the registry's `inc(name, …)`.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-telemetry",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './logger/Logger.js';
+export * from './metrics/Metrics.js';
+export * from './trace.js';

package/src/logger/Logger.ts

@@ -0,0 +1,178 @@
+import { createWriteStream, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { EOL } from 'node:os';
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export const LEVEL_ORDER: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+export interface LogRecord {
+  level: LogLevel;
+  time: number;
+  msg: string;
+  [key: string]: unknown;
+}
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  format?: 'json' | 'pretty';
+  console?: boolean;
+  /** File transport settings. */
+  file?: { dir: string; maxFileSize: number; maxFiles: number };
+  /** Field names to redact (replaced with [REDACTED]). */
+  redact?: string[];
+  /** Default bindings applied to every record. */
+  bindings?: Record<string, unknown>;
+}
+
+const COLORS: Record<LogLevel, string> = {
+  trace: '\x1b[90m',
+  debug: '\x1b[36m',
+  info: '\x1b[32m',
+  warn: '\x1b[33m',
+  error: '\x1b[31m',
+  fatal: '\x1b[35m',
+};
+const RESET = '\x1b[0m';
+
+/** Inbuilt structured logger with JSON/pretty formatting, redaction, and rotating file transport. */
+export class Logger {
+  private opts: Required<Pick<LoggerOptions, 'level' | 'format' | 'console' | 'redact'>> & {
+    file?: NonNullable<LoggerOptions['file']>;
+    bindings: Record<string, unknown>;
+  };
+  private stream: NodeJS.WritableStream | null = null;
+  private currentSize = 0;
+
+  constructor(opts: LoggerOptions = {}) {
+    this.opts = {
+      level: opts.level ?? 'info',
+      format: opts.format ?? 'pretty',
+      console: opts.console ?? true,
+      redact: opts.redact ?? [],
+      file: opts.file,
+      bindings: opts.bindings ?? {},
+    };
+    if (this.opts.file) this.openStream(this.opts.file);
+  }
+
+  private openStream(file: NonNullable<LoggerOptions['file']>): void {
+    if (!existsSync(file.dir)) mkdirSync(file.dir, { recursive: true });
+    const target = join(file.dir, 'nexus.log');
+    try {
+      this.currentSize = existsSync(target) ? statSync(target).size : 0;
+    } catch {
+      this.currentSize = 0;
+    }
+    this.stream = createWriteStream(target, { flags: 'a' });
+    this.stream.on('error', () => {
+      this.stream = null;
+    });
+  }
+
+  child(bindings: Record<string, unknown>): Logger {
+    return new Logger({
+      level: this.opts.level,
+      format: this.opts.format,
+      console: this.opts.console,
+      file: this.opts.file,
+      redact: this.opts.redact,
+      bindings: { ...this.opts.bindings, ...bindings },
+    });
+  }
+
+  setLevel(level: LogLevel): void {
+    this.opts.level = level;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.opts.level];
+  }
+
+  log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
+    if (!this.shouldLog(level)) return;
+    const record: LogRecord = {
+      level,
+      time: Date.now(),
+      msg,
+      ...this.opts.bindings,
+      ...(data ?? {}),
+    };
+    const safe = this.redactFields(record);
+    const line = this.opts.format === 'json' ? JSON.stringify(safe) : this.pretty(safe);
+    this.write(line + EOL, level);
+  }
+
+  private redactFields(record: LogRecord): LogRecord {
+    if (this.opts.redact.length === 0) return record;
+    const out: LogRecord = { ...record };
+    for (const key of this.opts.redact) {
+      if (key in out) out[key] = '[REDACTED]';
+    }
+    return out;
+  }
+
+  private pretty(rec: LogRecord): string {
+    const time = new Date(rec.time).toISOString();
+    const levelTag = `${COLORS[rec.level]}${rec.level.toUpperCase().padEnd(5)}${RESET}`;
+    const base = Object.fromEntries(
+      Object.entries(rec).filter(([k]) => k !== 'level' && k !== 'time' && k !== 'msg'),
+    );
+    const payload = Object.keys(base).length ? ` ${JSON.stringify(base)}` : '';
+    return `${time} ${levelTag} ${rec.msg}${payload}`;
+  }
+
+  private write(line: string, level: LogLevel): void {
+    if (this.opts.console) {
+      if (level === 'error' || level === 'fatal') process.stderr.write(line);
+      else process.stdout.write(line);
+    }
+    if (this.stream && this.opts.file) {
+      this.currentSize += Buffer.byteLength(line);
+      this.stream.write(line);
+      if (this.currentSize >= this.opts.file.maxFileSize) this.rotate();
+    }
+  }
+
+  private rotate(): void {
+    const file = this.opts.file!;
+    const target = join(file.dir, 'nexus.log');
+    if (!existsSync(target)) return;
+    this.stream?.end();
+    for (let i = file.maxFiles - 1; i > 0; i--) {
+      const from = join(file.dir, `nexus.${i - 1}.log`);
+      const to = join(file.dir, `nexus.${i}.log`);
+      if (existsSync(from)) renameSync(from, to);
+    }
+    renameSync(target, join(file.dir, 'nexus.0.log'));
+    this.currentSize = 0;
+    this.stream = createWriteStream(target, { flags: 'a' });
+  }
+
+  // Convenience level methods
+  trace(msg: string, data?: Record<string, unknown>): void { this.log('trace', msg, data); }
+  debug(msg: string, data?: Record<string, unknown>): void { this.log('debug', msg, data); }
+  info(msg: string, data?: Record<string, unknown>): void { this.log('info', msg, data); }
+  warn(msg: string, data?: Record<string, unknown>): void { this.log('warn', msg, data); }
+  error(msg: string, data?: Record<string, unknown>): void { this.log('error', msg, data); }
+  fatal(msg: string, data?: Record<string, unknown>): void { this.log('fatal', msg, data); }
+
+  /** Flush file transport. */
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.stream) this.stream.end(() => resolve());
+      else resolve();
+    });
+  }
+}
+
+/** A no-op file-less logger for tests / library contexts. */
+export function createLogger(opts?: LoggerOptions): Logger {
+  return new Logger({ console: false, ...opts });
+}

package/src/metrics/Metrics.ts

@@ -0,0 +1,123 @@
+/**
+ * Minimal inbuilt metrics registry: counters and histograms with labels.
+ * Exposes a JSON snapshot for an admin `/metrics` endpoint and a Prometheus
+ * text format for scraper compatibility.
+ */
+interface CounterState {
+  help: string;
+  values: Map<string, number>;
+}
+interface HistogramState {
+  help: string;
+  buckets: number[];
+  counts: Map<string, number[]>; // per-label bucket counts
+  sums: Map<string, number>;
+  totals: Map<string, number>;
+}
+
+export class MetricsRegistry {
+  private counters = new Map<string, CounterState>();
+  private histograms = new Map<string, HistogramState>();
+
+  counter(name: string, help = ''): CounterState {
+    let c = this.counters.get(name);
+    if (!c) {
+      c = { help, values: new Map() };
+      this.counters.set(name, c);
+    }
+    return c;
+  }
+
+  histogram(name: string, buckets: number[] = [0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10], help = ''): HistogramState {
+    let h = this.histograms.get(name);
+    if (!h) {
+      h = { help, buckets, counts: new Map(), sums: new Map(), totals: new Map() };
+      this.histograms.set(name, h);
+    }
+    return h;
+  }
+
+  inc(name: string, value = 1, labels: Record<string, string> = {}): void {
+    const key = labelKey(labels);
+    const c = this.counter(name);
+    c.values.set(key, (c.values.get(key) ?? 0) + value);
+  }
+
+  observe(name: string, value: number, labels: Record<string, string> = {}): void {
+    const key = labelKey(labels);
+    const h = this.histogram(name);
+    let counts = h.counts.get(key);
+    if (!counts) {
+      counts = new Array(h.buckets.length).fill(0);
+      h.counts.set(key, counts);
+    }
+    for (let i = 0; i < h.buckets.length; i++) if (value <= h.buckets[i]!) counts[i]!++;
+    h.sums.set(key, (h.sums.get(key) ?? 0) + value);
+    h.totals.set(key, (h.totals.get(key) ?? 0) + 1);
+  }
+
+  /** JSON snapshot for an admin endpoint. */
+  toJSON(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [name, c] of this.counters) {
+      out[name] = { type: 'counter', help: c.help, values: Object.fromEntries(c.values) };
+    }
+    for (const [name, h] of this.histograms) {
+      out[name] = {
+        type: 'histogram',
+        help: h.help,
+        buckets: h.buckets,
+        counts: Object.fromEntries(h.counts),
+        sums: Object.fromEntries(h.sums),
+        totals: Object.fromEntries(h.totals),
+      };
+    }
+    return out;
+  }
+
+  /** Prometheus text exposition format. */
+  toPrometheus(): string {
+    const lines: string[] = [];
+    for (const [name, c] of this.counters) {
+      if (c.help) lines.push(`# HELP ${name} ${c.help}`);
+      lines.push(`# TYPE ${name} counter`);
+      for (const [labels, val] of c.values) lines.push(`${name}${labels} ${val}`);
+    }
+    for (const [name, h] of this.histograms) {
+      if (h.help) lines.push(`# HELP ${name} ${h.help}`);
+      lines.push(`# TYPE ${name} histogram`);
+      for (const [labels, counts] of h.counts) {
+        let cumulative = 0;
+        for (let i = 0; i < h.buckets.length; i++) {
+          cumulative += counts[i]!;
+          const le = h.buckets[i]!;
+          lines.push(`${name}_bucket${withLabel(labels, 'le', String(le))} ${cumulative}`);
+        }
+        lines.push(`${name}_bucket${withLabel(labels, 'le', '+Inf')} ${h.totals.get(labels) ?? 0}`);
+        lines.push(`${name}_sum${labels} ${h.sums.get(labels) ?? 0}`);
+        lines.push(`${name}_count${labels} ${h.totals.get(labels) ?? 0}`);
+      }
+    }
+    return lines.join('\n') + '\n';
+  }
+
+  reset(): void {
+    this.counters.clear();
+    this.histograms.clear();
+  }
+}
+
+function labelKey(labels: Record<string, string>): string {
+  const keys = Object.keys(labels).sort();
+  if (keys.length === 0) return '';
+  return `{${keys.map((k) => `${k}="${escapeLabel(labels[k]!)}"`).join(',')}}`;
+}
+
+function withLabel(existing: string, name: string, value: string): string {
+  if (!existing) return `{${name}="${escapeLabel(value)}"}`;
+  return existing.slice(0, -1) + `,${name}="${escapeLabel(value)}"}`;
+}
+
+function escapeLabel(v: string): string {
+  return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}

package/src/trace.ts

@@ -0,0 +1,28 @@
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface TraceContext {
+  requestId: string;
+  traceId: string;
+}
+
+const traceStorage = new AsyncLocalStorage<TraceContext>();
+
+/** Start a trace context for the lifetime of `fn`, propagating request/trace ids. */
+export function withTrace<R>(fn: () => R, existing?: Partial<TraceContext>): R {
+  const ctx: TraceContext = {
+    requestId: existing?.requestId ?? randomUUID(),
+    traceId: existing?.traceId ?? randomUUID(),
+  };
+  return traceStorage.run(ctx, fn);
+}
+
+/** Current trace context, if any. */
+export function currentTrace(): TraceContext | undefined {
+  return traceStorage.getStore();
+}
+
+/** Generate a standalone id (for headers). */
+export function newRequestId(): string {
+  return randomUUID();
+}

package/tests/telemetry.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Logger, createLogger, MetricsRegistry, withTrace, currentTrace } from '../src/index.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+
+describe('Logger', () => {
+  it('respects level filtering (silent below threshold)', () => {
+    const sink: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk: string | Uint8Array) => { sink.push(String(chunk)); return true; };
+    try {
+      const log = createLogger({ level: 'warn', console: true });
+      log.info('should-not-appear');
+      log.warn('should-appear');
+    } finally {
+      process.stdout.write = orig;
+    }
+    expect(sink.join('')).not.toContain('should-not-appear');
+    expect(sink.join('')).toContain('should-appear');
+  });
+
+  it('redacts configured fields', () => {
+    const sink: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk: string | Uint8Array) => { sink.push(String(chunk)); return true; };
+    try {
+      const log = createLogger({ level: 'debug', console: true, redact: ['password'], format: 'json' });
+      log.info('login', { password: 'secret', user: 'alice' });
+    } finally {
+      process.stdout.write = orig;
+    }
+    const line = sink.join('');
+    expect(line).toContain('[REDACTED]');
+    expect(line).not.toContain('secret');
+    expect(line).toContain('alice');
+  });
+
+  it('writes to a rotating file transport', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'nexus-log-'));
+    try {
+      const log = new Logger({ level: 'info', console: false, file: { dir, maxFileSize: 1_000_000, maxFiles: 3 } });
+      log.info('file-message', { n: 1 });
+      await log.close();
+      // give the OS a tick to flush the final write
+      await new Promise((r) => setTimeout(r, 50));
+      const content = readFileSync(join(dir, 'nexus.log'), 'utf8');
+      expect(content).toContain('file-message');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('MetricsRegistry', () => {
+  let m: MetricsRegistry;
+  beforeEach(() => { m = new MetricsRegistry(); });
+
+  it('increments counters with labels', () => {
+    m.inc('http_requests', 1, { route: '/health', method: 'GET' });
+    m.inc('http_requests', 1, { route: '/health', method: 'GET' });
+    const json = m.toJSON()['http_requests'] as { values: Record<string, number> };
+    expect(json.values['{method="GET",route="/health"}']).toBe(2);
+  });
+
+  it('observes histograms into buckets', () => {
+    m.observe('latency', 0.02, { route: '/x' });
+    m.observe('latency', 0.5, { route: '/x' });
+    const prom = m.toPrometheus();
+    expect(prom).toContain('latency_bucket');
+    expect(prom).toContain('latency_sum');
+    expect(prom).toContain('latency_count');
+  });
+});
+
+describe('trace', () => {
+  it('propagates context through async locals', () => {
+    withTrace(() => {
+      expect(currentTrace()?.requestId).toMatch(/^[0-9a-f-]{36}$/i);
+    });
+    expect(currentTrace()).toBeUndefined();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "references": [{ "path": "../nexus-core" }]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+  },
+});

package/vitest.config.ts.timestamp-1786095205351-8114075f69fe9.mjs

@@ -0,0 +1,13 @@
+// packages/nexus-telemetry/vitest.config.ts
+import { defineProject } from "file:///C:/server/BhooAI/BhooAI-Nexus/BhooAI-Nexus/bhooai-nexus/node_modules/vitest/dist/config.js";
+var vitest_config_default = defineProject({
+  test: {
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    globals: false
+  }
+});
+export {
+  vitest_config_default as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsicGFja2FnZXMvbmV4dXMtdGVsZW1ldHJ5L3ZpdGVzdC5jb25maWcudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbImNvbnN0IF9fdml0ZV9pbmplY3RlZF9vcmlnaW5hbF9kaXJuYW1lID0gXCJDOlxcXFxzZXJ2ZXJcXFxcQmhvb0FJXFxcXEJob29BSS1OZXh1c1xcXFxCaG9vQUktTmV4dXNcXFxcYmhvb2FpLW5leHVzXFxcXHBhY2thZ2VzXFxcXG5leHVzLXRlbGVtZXRyeVwiO2NvbnN0IF9fdml0ZV9pbmplY3RlZF9vcmlnaW5hbF9maWxlbmFtZSA9IFwiQzpcXFxcc2VydmVyXFxcXEJob29BSVxcXFxCaG9vQUktTmV4dXNcXFxcQmhvb0FJLU5leHVzXFxcXGJob29haS1uZXh1c1xcXFxwYWNrYWdlc1xcXFxuZXh1cy10ZWxlbWV0cnlcXFxcdml0ZXN0LmNvbmZpZy50c1wiO2NvbnN0IF9fdml0ZV9pbmplY3RlZF9vcmlnaW5hbF9pbXBvcnRfbWV0YV91cmwgPSBcImZpbGU6Ly8vQzovc2VydmVyL0Job29BSS9CaG9vQUktTmV4dXMvQmhvb0FJLU5leHVzL2Job29haS1uZXh1cy9wYWNrYWdlcy9uZXh1cy10ZWxlbWV0cnkvdml0ZXN0LmNvbmZpZy50c1wiO2ltcG9ydCB7IGRlZmluZVByb2plY3QgfSBmcm9tICd2aXRlc3QvY29uZmlnJztcblxuZXhwb3J0IGRlZmF1bHQgZGVmaW5lUHJvamVjdCh7XG4gIHRlc3Q6IHtcbiAgICBlbnZpcm9ubWVudDogJ25vZGUnLFxuICAgIGluY2x1ZGU6IFsndGVzdHMvKiovKi50ZXN0LnRzJ10sXG4gICAgZ2xvYmFsczogZmFsc2UsXG4gIH0sXG59KTsiXSwKICAibWFwcGluZ3MiOiAiO0FBQXNiLFNBQVMscUJBQXFCO0FBRXBkLElBQU8sd0JBQVEsY0FBYztBQUFBLEVBQzNCLE1BQU07QUFBQSxJQUNKLGFBQWE7QUFBQSxJQUNiLFNBQVMsQ0FBQyxvQkFBb0I7QUFBQSxJQUM5QixTQUFTO0FBQUEsRUFDWDtBQUNGLENBQUM7IiwKICAibmFtZXMiOiBbXQp9Cg==