@spinajs/log-common 2.0.480 → 2.0.482

package/lib/mjs/index.js

@@ -9,7 +9,15 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { Autoinject, Container, DI, SyncService } from "@spinajs/di";
 import _ from "lodash";
-import * as util from "util";
+import { format } from "./format.js";
+import { applySerializers } from "./serializers.js";
+import { persistLevel, clearPersistedLevel } from "./persistence.js";
+export * from "./serializers.js";
+export * from "./filters/filter.js";
+export * from "./filters/whenRepeated.js";
+export * from "./BatchQueue.js";
+export * from "./persistence.js";
+export * from "./perf.js";
 export var LogLevel;
 (function (LogLevel) {
     LogLevel[LogLevel["Security"] = 999] = "Security";
@@ -31,6 +39,29 @@ export const StrToLogLevel = {
     fatal: LogLevel.Fatal,
     security: LogLevel.Security,
 };
+/**
+ * Sentinel level sitting one ABOVE {@link LogLevel.Security} ( SpinaJS's highest
+ * real level ). Used by `Log.disableAll()` as the runtime override so even a
+ * `security()` call is gated out - `isEnabled` compares numerically, so nothing
+ * ever reaches it.
+ */
+export const SILENT_LEVEL = LogLevel.Security + 1;
+/**
+ * Normalises a level given either as a {@link LogLevel} number or a level name
+ * ( "trace" | "debug" | ... ) to its numeric value. Single validation choke
+ * point: an unknown name throws a clear error. Numbers pass straight through
+ * ( so {@link SILENT_LEVEL } and other synthetic values are accepted ).
+ */
+export function normalizeLevel(level) {
+    if (typeof level === "number") {
+        return level;
+    }
+    const resolved = StrToLogLevel[level];
+    if (resolved === undefined) {
+        throw new Error(`Invalid log level: ${level}`);
+    }
+    return resolved;
+}
 export const LogLevelStrings = {
     [LogLevel.Debug]: "debug",
     [LogLevel.Error]: "error",
@@ -41,11 +72,37 @@ export const LogLevelStrings = {
     [LogLevel.Trace]: "trace",
     [LogLevel.Warn]: "warn",
 };
+/**
+ * Maps SpinaJS log levels onto the OpenTelemetry SeverityNumber scale ( 1..24 ),
+ * so structured logs can be severity-ranked/filtered by any OTel-aware backend
+ * ( Grafana, Datadog, Elastic, OTLP pipelines ). Anchored on the OTel bands:
+ * TRACE 1-4, DEBUG 5-8, INFO 9-12, WARN 13-16, ERROR 17-20, FATAL 21-24.
+ * Success sits in the INFO band ( above plain info ); Security is mapped to the
+ * top of the FATAL band as SpinaJS's highest severity.
+ */
+export const LogLevelToSeverityNumber = {
+    [LogLevel.Trace]: 1,
+    [LogLevel.Debug]: 5,
+    [LogLevel.Info]: 9,
+    [LogLevel.Success]: 11,
+    [LogLevel.Warn]: 13,
+    [LogLevel.Error]: 17,
+    [LogLevel.Fatal]: 21,
+    [LogLevel.Security]: 23,
+};
 export class LogTarget extends SyncService {
     constructor(options) {
         super();
         this.HasError = false;
         this.Error = null;
+        /**
+         * Drop-hook. Set by a wrapper ( eg. {@link FallbackGroupTarget} ) to receive
+         * entries this target GAVE UP on ( buffer overflow or a non-retryable delivery
+         * failure ), so a durable fallback can catch EXACTLY what was not delivered —
+         * no duplicates. `null` ( the default ) means nobody is listening and dropped
+         * entries are simply discarded, as before.
+         */
+        this.OnDropped = null;
         if (options) {
             this.Options = _.merge(_.merge(this.Options, {
                 enabled: true,
@@ -59,20 +116,37 @@ export class LogTarget extends SyncService {
             };
         }
     }
+    /** Flush any buffered entries to the underlying sink. Default no-op; buffered targets override. */
+    forceFlush() {
+        return Promise.resolve();
+    }
 }
 export function createLogMessageObject(err, message, level, logger, variables, ...args) {
     const sMsg = err instanceof Error || !err ? message : err;
-    const tMsg = args.length !== 0 ? util.format(sMsg, ...args) : sMsg;
+    const tMsg = args.length !== 0 ? format(sMsg, ...args) : sMsg;
     const lName = logger ?? message;
+    // Ambient async-context fields ( lowest precedence, must never throw ). The
+    // computed core fields below and any explicit per-call / logger `variables`
+    // OVERRIDE these — ambient context only FILLS IN fields nobody else set.
+    let ctx = {};
+    try {
+        ctx = logContextProvider() ?? {};
+    }
+    catch {
+        ctx = {};
+    }
+    const theVars = {
+        ...ctx,
+        error: err instanceof Error ? err : undefined,
+        level: LogLevelStrings[`${level}`].toUpperCase(),
+        logger: lName,
+        message: tMsg,
+        ...variables,
+    };
+    applySerializers(theVars);
     return {
         Level: level,
-        Variables: {
-            error: err instanceof Error ? err : undefined,
-            level: LogLevelStrings[`${level}`].toUpperCase(),
-            logger: lName,
-            message: tMsg,
-            ...variables,
-        },
+        Variables: theVars,
     };
 }
 export class Log extends SyncService {
@@ -80,9 +154,87 @@ export class Log extends SyncService {
         super(...arguments);
         this.Timers = new Map();
         this.Variables = {};
+        /**
+         * Lowest level any of this logger's targets accepts ( the MIN across its
+         * matched rules ). Set by FrameworkLogger.resolve(); default Trace = allow
+         * all. A call below this level would be dropped by every target anyway, so the
+         * per-method guard can safely short-circuit on it.
+         */
+        this.MinLevel = LogLevel.Trace;
+        /**
+         * Runtime level override ( loglevel-style ). `null` means "no override, use
+         * MinLevel". Set via setLevel/enableAll/disableAll, cleared via resetLevel.
+         */
+        this.LevelOverride = null;
+    }
+    /** Effective minimum level: the runtime override if set, otherwise MinLevel. */
+    getLevel() {
+        return this.LevelOverride ?? this.MinLevel;
+    }
+    /** True when a call at `level` should be emitted given the effective level. */
+    isEnabled(level) {
+        return level >= this.getLevel();
+    }
+    /**
+     * Set a runtime level override. Accepts a {@link LogLevel} or a level name.
+     * When `persist` ( default true ) the choice is stored so it survives a
+     * browser reload ( no-op on Node ).
+     */
+    setLevel(level, persist = true) {
+        this.LevelOverride = normalizeLevel(level);
+        if (persist) {
+            persistLevel(this.Name, this.LevelOverride);
+        }
+    }
+    /**
+     * Set the override ONLY if nothing is currently applied ( loglevel semantics:
+     * a default must never clobber a user's explicit / persisted choice ). Never
+     * persists.
+     */
+    setDefaultLevel(level) {
+        if (this.LevelOverride === null) {
+            this.LevelOverride = normalizeLevel(level);
+        }
+    }
+    /** Drop the runtime override ( back to MinLevel ) and clear any persisted value. */
+    resetLevel() {
+        this.LevelOverride = null;
+        clearPersistedLevel(this.Name);
+    }
+    /** Enable every level ( Trace and up ). */
+    enableAll(persist = true) {
+        this.setLevel(LogLevel.Trace, persist);
+    }
+    /**
+     * Disable every level - even {@link LogLevel.Security} - by raising the
+     * override to {@link SILENT_LEVEL} ( one above Security ).
+     */
+    disableAll(persist = true) {
+        this.setLevel(SILENT_LEVEL, persist);
+    }
+    /**
+     * Force-drain THIS logger's targets' buffers ( eg. File / Loki / OTLP batch
+     * queues ) so buffered entries are written out. Does NOT close / dispose the
+     * target - handle & timer teardown remains the DI container's job. Calling
+     * `forceFlush()` on a non-buffered target is a harmless no-op. Guarded so a
+     * logger that failed to resolve ( no `Targets` ) is a safe no-op.
+     */
+    flush() {
+        if (!this.Targets || this.Targets.length === 0) {
+            return Promise.resolve();
+        }
+        return Promise.allSettled(this.Targets.map((t) => t.instance.forceFlush())).then(() => undefined);
+    }
+    /** Flush every registered logger ( best-effort; never rejects ). */
+    static flushAll() {
+        return Promise.allSettled([...Log.Loggers.values()].map((l) => l.flush())).then(() => undefined);
     }
     static clearLoggers() {
-        return Promise.all([...Log.Loggers.values()].map((l) => l.dispose()))
+        // Flush buffered entries out BEFORE tearing loggers down so File / Loki /
+        // OTLP data is not lost when teardown does not go through DI container
+        // disposal of the target singletons.
+        return Log.flushAll()
+            .then(() => Promise.all([...Log.Loggers.values()].map((l) => l.dispose())))
             .then(() => {
             Log.Loggers.clear();
         })
@@ -119,6 +271,28 @@ export class Log extends SyncService {
             this,
         ]);
     }
+    /**
+     * Attach a sink to THIS logger AT RUNTIME ( bunyan `addStream` style ),
+     * without going through config. Returns the resolved target instance, or
+     * `undefined` when nothing was attached ( eg. `def.enabled === false` ).
+     *
+     * Default is a safe no-op ( returns `undefined` ) so `Log`-typed references
+     * and bootstrap proxies compile; {@link FrameworkLogger } overrides it with
+     * the real target-descriptor build + gate recompute.
+     */
+    addTarget(_def, _opts) {
+        return undefined;
+    }
+    /**
+     * Detach a runtime sink by its target `name`, flushing its buffered entries
+     * first ( it is NOT disposed - the instance may be DI-owned / shared ).
+     * No-op when no target with that name is attached.
+     *
+     * Default resolves immediately; {@link FrameworkLogger } overrides it.
+     */
+    removeTarget(_name) {
+        return Promise.resolve();
+    }
 }
 Log.Loggers = new Map();
 Log.InternalLoggers = new Map();
@@ -157,4 +331,21 @@ export function Logger(name, variables) {
         });
     };
 }
+/**
+ * Ambient log-context provider seam. A Node-side consumer ( @spinajs/log's
+ * LogContext ) registers a function returning the current async-context store;
+ * `createLogMessageObject` merges its result at LOWEST precedence so every log
+ * entry inherits ambient fields ( eg. requestId ) without threading them by hand.
+ *
+ * Kept here ( not in @spinajs/log ) so the seam is browser-safe: log-common must
+ * stay free of `node:async_hooks`. The default provider returns an empty object;
+ * the browser build wires a synchronous fallback instead.
+ */
+let logContextProvider = () => ({});
+/**
+ * Registers the ambient log-context provider. See {@link logContextProvider}.
+ */
+export function setLogContextProvider(fn) {
+    logContextProvider = fn;
+}
 //# sourceMappingURL=index.js.map

package/lib/mjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/lib/mjs/perf.d.ts

@@ -0,0 +1,109 @@
+import { SyncService } from "@spinajs/di";
+/** Kind of a single measurement. */
+export type PerfKind = "span" | "counter" | "value";
+/** One unit of instrumentation, emitted to every registered {@link PerfSink}. */
+export interface IPerfMetric {
+    name: string;
+    kind: PerfKind;
+    /** span duration in ms ( monotonic ). */
+    durationMs?: number;
+    /** counter delta / recorded value. */
+    value?: number;
+    /** LOW-cardinality dimensions ( safe as prom labels ). */
+    labels?: Record<string, string | number | boolean>;
+    /** rich payload for logs only ( sql text, bindings, rows ). Never a prom label. */
+    fields?: Record<string, unknown>;
+    /** epoch ms when the measurement started. */
+    startedAt?: number;
+    /** correlation id from the active request scope, when any. */
+    requestId?: string;
+    /** set when the measured block threw. */
+    error?: unknown;
+}
+/** Per-name aggregate inside a {@link IPerfRollup}. */
+export interface IPerfRollupEntry {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+/** One per-request summary, handed to {@link PerfSink.onScopeEnd}. */
+export interface IPerfRollup {
+    requestId?: string;
+    labels?: Record<string, string | number | boolean>;
+    totalMs: number;
+    byName: Record<string, IPerfRollupEntry>;
+}
+/** The mutable accumulator kept on the async request store. */
+export interface IPerfScope {
+    requestId?: string;
+    byName: Record<string, IPerfRollupEntry>;
+}
+/**
+ * A receiver of perf measurements. Register a concrete subclass with
+ * `@Injectable(PerfSink)` and it is discovered via `Array.ofType(PerfSink)`.
+ * `SyncService` ( same base as LogTarget ) so resolution stays synchronous.
+ */
+export declare abstract class PerfSink extends SyncService {
+    /** Receive one measurement. MUST NOT throw ( the facade guards it ). */
+    abstract collect(metric: IPerfMetric): void;
+    /** Optional: receive the per-request rollup at scope end. */
+    onScopeEnd?(rollup: IPerfRollup): void;
+}
+/** Options accepted by {@link Perf.measure} / {@link Perf.start}. */
+export interface IMeasureOpts {
+    labels?: Record<string, string | number | boolean>;
+    fields?: Record<string, unknown>;
+}
+/** Handle returned by {@link Perf.start}. */
+export interface IPerfSpan {
+    end(fields?: Record<string, unknown>): void;
+}
+/**
+ * Seam for the per-request scope. The node `@spinajs/log` package wires this to
+ * its AsyncLocalStorage-backed LogContext; the default returns `null` so the
+ * facade works ( sans rollups ) with no host — eg. on the browser.
+ */
+export interface IPerfScopeBackend {
+    get(): IPerfScope | null;
+}
+/** Install the per-request scope backend. See {@link IPerfScopeBackend}. */
+export declare function setPerfScopeBackend(backend: IPerfScopeBackend): void;
+declare class PerfImpl {
+    /** Global kill-switch; when false measure/start/count/value are pass-throughs. */
+    Enabled: boolean;
+    private sinks;
+    /** Drop the memoized sink list so the next emit re-resolves ( tests / late registration ). */
+    refreshSinks(): void;
+    private resolveSinks;
+    private emit;
+    private accumulate;
+    private record;
+    /**
+     * Time `fn` ( sync or async ), emit a span, and return `fn`'s result. On a
+     * thrown error the span is still emitted ( with `error` set ) and the error is
+     * rethrown.
+     */
+    measure<T>(name: string, fn: () => Promise<T> | T, opts?: IMeasureOpts): Promise<T> | T;
+    /** Open a manual span; call `end()` where timing stops ( start/end may be far apart ). */
+    start(name: string, opts?: IMeasureOpts): IPerfSpan;
+    /** Increment a per-request counter ( eg. query count ) and emit a counter metric. */
+    count(name: string, delta?: number, labels?: Record<string, string | number | boolean>): void;
+    /** Record an absolute value ( gauge-like ) and emit a value metric. */
+    value(name: string, n: number, labels?: Record<string, string | number | boolean>): void;
+    /**
+     * Emit the per-request rollup for `scope` to every sink's `onScopeEnd`. The
+     * caller ( http ) passes the scope it read off `req.storage`; `extra` carries
+     * request labels and total wall time. No-op when `scope` is null.
+     */
+    flushScope(scope: IPerfScope | null | undefined, extra?: {
+        labels?: Record<string, string | number | boolean>;
+        totalMs?: number;
+    }): void;
+}
+/**
+ * Shared perf-instrumentation facade. Emits measurements to every registered
+ * {@link PerfSink}. See the plan / design doc for usage.
+ */
+export declare const Perf: PerfImpl;
+export {};
+//# sourceMappingURL=perf.d.ts.map

package/lib/mjs/perf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":"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"}

package/lib/mjs/perf.js

@@ -0,0 +1,157 @@
+import { DI, SyncService } from "@spinajs/di";
+/**
+ * A receiver of perf measurements. Register a concrete subclass with
+ * `@Injectable(PerfSink)` and it is discovered via `Array.ofType(PerfSink)`.
+ * `SyncService` ( same base as LogTarget ) so resolution stays synchronous.
+ */
+export class PerfSink extends SyncService {
+}
+const NOOP_BACKEND = { get: () => null };
+let perfScopeBackend = NOOP_BACKEND;
+/** Install the per-request scope backend. See {@link IPerfScopeBackend}. */
+export function setPerfScopeBackend(backend) {
+    perfScopeBackend = backend ?? NOOP_BACKEND;
+}
+class PerfImpl {
+    constructor() {
+        /** Global kill-switch; when false measure/start/count/value are pass-throughs. */
+        this.Enabled = true;
+        this.sinks = null;
+    }
+    /** Drop the memoized sink list so the next emit re-resolves ( tests / late registration ). */
+    refreshSinks() {
+        this.sinks = null;
+    }
+    resolveSinks() {
+        if (this.sinks === null) {
+            // PerfSink extends SyncService => resolve returns synchronously.
+            this.sinks = DI.resolve(Array.ofType(PerfSink)) ?? [];
+        }
+        return this.sinks;
+    }
+    emit(metric) {
+        for (const s of this.resolveSinks()) {
+            try {
+                s.collect(metric);
+            }
+            catch {
+                /* a sink must never break the measured code or sibling sinks */
+            }
+        }
+    }
+    accumulate(name, durationMs, scope) {
+        if (!scope)
+            return;
+        const e = scope.byName[name] ?? (scope.byName[name] = { count: 0, totalMs: 0, maxMs: 0 });
+        e.count += 1;
+        e.totalMs += durationMs;
+        if (durationMs > e.maxMs)
+            e.maxMs = durationMs;
+    }
+    record(name, startedAt, durationMs, opts, error) {
+        const scope = perfScopeBackend.get();
+        this.accumulate(name, durationMs, scope);
+        this.emit({
+            name,
+            kind: "span",
+            durationMs,
+            labels: opts?.labels,
+            fields: error !== undefined ? { ...(opts?.fields ?? {}), error } : opts?.fields,
+            startedAt,
+            requestId: scope?.requestId,
+            error,
+        });
+    }
+    /**
+     * Time `fn` ( sync or async ), emit a span, and return `fn`'s result. On a
+     * thrown error the span is still emitted ( with `error` set ) and the error is
+     * rethrown.
+     */
+    measure(name, fn, opts) {
+        if (!this.Enabled)
+            return fn();
+        const startedAt = Date.now();
+        const t0 = performance.now();
+        let out;
+        try {
+            out = fn();
+        }
+        catch (err) {
+            this.record(name, startedAt, performance.now() - t0, opts, err);
+            throw err;
+        }
+        if (out !== null && typeof out?.then === "function") {
+            return out.then((v) => {
+                this.record(name, startedAt, performance.now() - t0, opts, undefined);
+                return v;
+            }, (err) => {
+                this.record(name, startedAt, performance.now() - t0, opts, err);
+                throw err;
+            });
+        }
+        this.record(name, startedAt, performance.now() - t0, opts, undefined);
+        return out;
+    }
+    /** Open a manual span; call `end()` where timing stops ( start/end may be far apart ). */
+    start(name, opts) {
+        const startedAt = Date.now();
+        const t0 = performance.now();
+        let ended = false;
+        return {
+            end: (fields) => {
+                if (ended)
+                    return;
+                ended = true;
+                const merged = fields ? { labels: opts?.labels, fields: { ...(opts?.fields ?? {}), ...fields } } : opts ?? {};
+                this.record(name, startedAt, performance.now() - t0, merged, undefined);
+            },
+        };
+    }
+    /** Increment a per-request counter ( eg. query count ) and emit a counter metric. */
+    count(name, delta = 1, labels) {
+        if (!this.Enabled)
+            return;
+        const scope = perfScopeBackend.get();
+        if (scope) {
+            const e = scope.byName[name] ?? (scope.byName[name] = { count: 0, totalMs: 0, maxMs: 0 });
+            e.count += delta;
+        }
+        this.emit({ name, kind: "counter", value: delta, labels, requestId: scope?.requestId });
+    }
+    /** Record an absolute value ( gauge-like ) and emit a value metric. */
+    value(name, n, labels) {
+        if (!this.Enabled)
+            return;
+        const scope = perfScopeBackend.get();
+        this.emit({ name, kind: "value", value: n, labels, requestId: scope?.requestId });
+    }
+    /**
+     * Emit the per-request rollup for `scope` to every sink's `onScopeEnd`. The
+     * caller ( http ) passes the scope it read off `req.storage`; `extra` carries
+     * request labels and total wall time. No-op when `scope` is null.
+     */
+    flushScope(scope, extra) {
+        if (!scope)
+            return;
+        const rollup = {
+            requestId: scope.requestId,
+            labels: extra?.labels,
+            totalMs: extra?.totalMs ?? 0,
+            byName: scope.byName,
+        };
+        for (const sink of this.resolveSinks()) {
+            try {
+                sink.onScopeEnd?.(rollup);
+            }
+            catch {
+                /* isolate */
+            }
+        }
+    }
+}
+/**
+ * Shared perf-instrumentation facade. Emits measurements to every registered
+ * {@link PerfSink}. See the plan / design doc for usage.
+ */
+export const Perf = new PerfImpl();
+//# sourceMappingURL=perf.js.map

package/lib/mjs/perf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":"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"}

package/lib/mjs/persistence.d.ts

@@ -0,0 +1,19 @@
+import type { LogLevel } from "./index.js";
+/**
+ * Persist `level` for `loggerName`. Browser only - writes `String(level)` to
+ * localStorage under `spinajs:log:level:<loggerName>`, falling back to a cookie
+ * when storage throws. No-op on Node.
+ */
+export declare function persistLevel(loggerName: string, level: LogLevel): void;
+/**
+ * Read back the persisted level for `loggerName` ( localStorage then cookie ).
+ * Returns a finite {@link LogLevel} number, or `undefined` when nothing valid is
+ * stored. Always `undefined` on Node.
+ */
+export declare function readPersistedLevel(loggerName: string): LogLevel | undefined;
+/**
+ * Remove any persisted level for `loggerName` ( localStorage + cookie ). No-op
+ * on Node.
+ */
+export declare function clearPersistedLevel(loggerName: string): void;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/mjs/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmE3C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAmBtE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA0B3E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAgB5D"}