@zintrust/trace 0.4.75

package/dist/watchers/JobWatcher.js

@@ -0,0 +1,108 @@
+/**
+ * JobWatcher — records job dispatch, completion, and failure.
+ * Subsystems must call JobWatcher.onDispatch / onProcess / onFail from
+ * within their queue implementation for full tracking.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+import { parseStackFrameLine } from '../utils/stackFrame';
+// Module-level storage ref so emit helpers can be called from outside.
+let _storage = null;
+let _ignoreRoutes = [];
+const MAX_TRACKED_JOBS = 1000;
+const pendingJobs = new Map();
+const trackPendingJob = (name, job) => {
+    const jobs = pendingJobs.get(name) ?? [];
+    jobs.push(job);
+    if (jobs.length > MAX_TRACKED_JOBS) {
+        jobs.shift();
+    }
+    pendingJobs.set(name, jobs);
+};
+const takePendingJob = (name) => {
+    const jobs = pendingJobs.get(name);
+    if (!jobs || jobs.length === 0)
+        return null;
+    const job = jobs.shift() ?? null;
+    if (jobs.length === 0) {
+        pendingJobs.delete(name);
+    }
+    else {
+        pendingJobs.set(name, jobs);
+    }
+    return job;
+};
+const emitDispatch = (name, queue, connection, data) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const uuid = crypto.randomUUID();
+    const content = {
+        status: 'pending',
+        connection,
+        queue,
+        name,
+        data,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid,
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.JOB,
+        content,
+        tags: [name],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+    trackPendingJob(name, { uuid, content });
+};
+const emitProcessed = (name) => {
+    if (!_storage)
+        return;
+    const pendingJob = takePendingJob(name);
+    if (pendingJob === null)
+        return;
+    const patch = { ...pendingJob.content, status: 'processed' };
+    void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
+};
+const emitFailed = (name, error) => {
+    if (!_storage)
+        return;
+    const pendingJob = takePendingJob(name);
+    if (pendingJob === null)
+        return;
+    const patch = {
+        ...pendingJob.content,
+        status: 'failed',
+        exception: {
+            message: error.message,
+            trace: (error.stack ?? '')
+                .split('\n')
+                .slice(1)
+                .map(parseStackFrameLine)
+                .filter((trace) => trace !== null)
+                .slice(0, 10),
+        },
+    };
+    void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
+};
+export const JobWatcher = Object.freeze({
+    onDispatch: emitDispatch,
+    onProcessed: emitProcessed,
+    onFailed: emitFailed,
+    register({ storage, config }) {
+        if (config.watchers.job === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+            pendingJobs.clear();
+        };
+    },
+});

package/dist/watchers/LogWatcher.d.ts

@@ -0,0 +1,2 @@
+import type { ITraceWatcher } from '../types';
+export declare const LogWatcher: ITraceWatcher;

package/dist/watchers/LogWatcher.js

@@ -0,0 +1,50 @@
+/**
+ * LogWatcher — captures Logger output via Logger.addSink().
+ */
+import { Logger } from '@zintrust/core';
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+export const LogWatcher = Object.freeze({
+    register({ storage, config }) {
+        if (config.watchers.log === false)
+            return () => undefined;
+        const minPriority = LEVEL_PRIORITY[config.logMinLevel] ?? 1;
+        const loggerWithSink = Logger;
+        if (typeof loggerWithSink.addSink !== 'function') {
+            return () => undefined;
+        }
+        const unsubscribe = loggerWithSink.addSink((level, message, context) => {
+            if ((LEVEL_PRIORITY[level] ?? 0) < minPriority)
+                return;
+            if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes))
+                return;
+            const content = {
+                level,
+                message,
+                context: context ?? undefined,
+                hostname: TraceContext.getHostname(),
+            };
+            storage
+                .writeEntry({
+                uuid: crypto.randomUUID(),
+                batchId: TraceContext.getBatchId(),
+                type: EntryType.LOG,
+                content,
+                tags: AuthTag.append([]),
+                isLatest: true,
+                createdAt: TraceContext.now(),
+            })
+                .catch(() => undefined);
+        });
+        return unsubscribe;
+    },
+});

package/dist/watchers/MailWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (to: string, subject: string, template?: string) => void;
+export declare const MailWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/MailWatcher.js

@@ -0,0 +1,45 @@
+/**
+ * MailWatcher — records mail dispatch intent.
+ * Body is never captured; only to/subject/template.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (to, subject, template) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        to,
+        subject,
+        template,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.MAIL,
+        content,
+        tags: [],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const MailWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.mail === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/MiddlewareWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher, MiddlewareContent } from '../types';
+declare const emit: (name: string, event: MiddlewareContent["event"], duration?: number) => void;
+export declare const MiddlewareWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/MiddlewareWatcher.js

@@ -0,0 +1,41 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (name, event, duration) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        name,
+        event,
+        duration,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.MIDDLEWARE,
+        content,
+        tags: [name, event],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const MiddlewareWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.middleware === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/ModelWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher, ModelContent } from '../types';
+declare const emit: (action: ModelContent["action"], model: string, id?: string | number, changes?: Record<string, unknown>) => void;
+export declare const ModelWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/ModelWatcher.js

@@ -0,0 +1,42 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (action, model, id, changes) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        action,
+        model,
+        id,
+        changes,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.MODEL,
+        content,
+        tags: [model],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const ModelWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.model === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/NotificationWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (notification: string, channels: string[], notifiable?: string) => void;
+export declare const NotificationWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/NotificationWatcher.js

@@ -0,0 +1,42 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (notification, channels, notifiable) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        notification,
+        channels,
+        notifiable,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.NOTIFICATION,
+        content,
+        tags: AuthTag.append([notification, ...channels]),
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const NotificationWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.notification === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/QueryWatcher.d.ts

@@ -0,0 +1,2 @@
+import type { ITraceWatcher } from '../types';
+export declare const QueryWatcher: ITraceWatcher;

package/dist/watchers/QueryWatcher.js

@@ -0,0 +1,72 @@
+/**
+ * QueryWatcher — hooks into Database.onAfterQuery to record SQL entries.
+ */
+import { TraceContext } from '../context';
+import { TraceStorage } from '../storage';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+const bindingsInterpolated = (sql, params) => {
+    // Inline params for display only — safe, not for re-execution.
+    let i = 0;
+    return sql.replaceAll('?', () => {
+        const val = params[i++];
+        if (val === null || val === undefined)
+            return 'NULL';
+        if (typeof val === 'string')
+            return `'${val.replaceAll("'", "''")}'`;
+        return String(val);
+    });
+};
+const isTraceStorageQuery = (sql) => {
+    const normalized = sql.toLowerCase();
+    return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
+};
+export const QueryWatcher = Object.freeze({
+    register({ storage, config, db: injectedDb }) {
+        if (config.watchers.query === false)
+            return () => undefined;
+        if (!injectedDb)
+            return () => undefined; // no db available
+        const db = injectedDb;
+        const handler = (query, params, duration) => {
+            if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes))
+                return;
+            if (isTraceStorageQuery(query))
+                return;
+            const batchId = TraceContext.getBatchId();
+            const sql = bindingsInterpolated(query, params);
+            const roundedDuration = Math.round(duration * 100) / 100;
+            const hash = TraceStorage.familyHash(query);
+            const slow = roundedDuration >= config.slowQueryThreshold;
+            const content = {
+                connection: 'default',
+                sql,
+                time: roundedDuration,
+                duration: roundedDuration,
+                slow,
+                hash,
+                hostname: TraceContext.getHostname(),
+            };
+            const tags = AuthTag.append([]);
+            if (slow)
+                tags.push('slow');
+            storage
+                .writeEntry({
+                uuid: crypto.randomUUID(),
+                batchId,
+                familyHash: hash,
+                type: EntryType.QUERY,
+                content,
+                tags,
+                isLatest: true,
+                createdAt: TraceContext.now(),
+            })
+                .catch(() => undefined);
+        };
+        db.onAfterQuery?.(handler);
+        return () => {
+            db.offAfterQuery?.(handler);
+        };
+    },
+});

package/dist/watchers/RedisWatcher.d.ts

@@ -0,0 +1,7 @@
+import type { ITraceWatcher } from '../types';
+/** Emit a redis command trace. Key/value payload is intentionally omitted for security. */
+declare const emit: (command: string, duration: number) => void;
+export declare const RedisWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/RedisWatcher.js

@@ -0,0 +1,38 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+/** Emit a redis command trace. Key/value payload is intentionally omitted for security. */
+const emit = (command, duration) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = { command, duration, hostname: TraceContext.getHostname() };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.REDIS,
+        content,
+        tags: AuthTag.append([command.toUpperCase()]),
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const RedisWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.redis === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/ScheduleWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher, ScheduleContent } from '../types';
+declare const emit: (name: string, expression: string, status: ScheduleContent["status"], duration: number, output?: string) => void;
+export declare const ScheduleWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/ScheduleWatcher.js

@@ -0,0 +1,46 @@
+/**
+ * ScheduleWatcher — records scheduled task runs and outcomes.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (name, expression, status, duration, output) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        name,
+        expression,
+        status,
+        duration,
+        output,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.SCHEDULE,
+        content,
+        tags: status === 'failed' ? ['failed'] : [],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const ScheduleWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.schedule === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/ViewWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (template: string, duration: number) => void;
+export declare const ViewWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/ViewWatcher.js

@@ -0,0 +1,36 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (template, duration) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = { template, duration, hostname: TraceContext.getHostname() };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.VIEW,
+        content,
+        tags: [template],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const ViewWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.view === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@zintrust/trace",
+  "version": "0.4.75",
+  "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "default": "./dist/ui.js"
+    },
+    "./cli-register": {
+      "types": "./dist/cli-register.d.ts",
+      "default": "./dist/cli-register.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@zintrust/core": "^0.4.74"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zintrust",
+    "trace",
+    "observability",
+    "tracing",
+    "telescope"
+  ],
+  "scripts": {
+    "build": "npx lint-staged",
+    "prepublishOnly": "npm run build"
+  }
+}