@zintrust/trace 0.4.75

package/src/watchers/MiddlewareWatcher.ts

@@ -0,0 +1,42 @@
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, MiddlewareContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (name: string, event: MiddlewareContent['event'], duration?: number): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: MiddlewareContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.middleware === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/ModelWatcher.ts

@@ -0,0 +1,48 @@
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, ModelContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  action: ModelContent['action'],
+  model: string,
+  id?: string | number,
+  changes?: Record<string, unknown>
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: ModelContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.model === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/NotificationWatcher.ts

@@ -0,0 +1,43 @@
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, NotificationContent } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (notification: string, channels: string[], notifiable?: string): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: NotificationContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.notification === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/QueryWatcher.ts

@@ -0,0 +1,85 @@
+/**
+ * QueryWatcher — hooks into Database.onAfterQuery to record SQL entries.
+ */
+import { TraceContext } from '../context';
+import { TraceStorage } from '../storage';
+import type { ITraceWatcher, ITraceWatcherConfig, QueryContent } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+
+const bindingsInterpolated = (sql: string, params: unknown[]): string => {
+  // 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: string): boolean => {
+  const normalized = sql.toLowerCase();
+  return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
+};
+
+export const QueryWatcher: ITraceWatcher = Object.freeze({
+  register({ storage, config, db: injectedDb }: ITraceWatcherConfig): () => void {
+    if (config.watchers.query === false) return () => undefined;
+    if (!injectedDb) return () => undefined; // no db available
+
+    const db = injectedDb;
+
+    const handler = (query: string, params: unknown[], duration: number): void => {
+      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: QueryContent = {
+        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 as {
+        onAfterQuery?: (h: (sql: string, params: unknown[], duration: number) => void) => void;
+      }
+    ).onAfterQuery?.(handler);
+
+    return () => {
+      (
+        db as {
+          offAfterQuery?: (h: (sql: string, params: unknown[], duration: number) => void) => void;
+        }
+      ).offAfterQuery?.(handler);
+    };
+  },
+});

package/src/watchers/RedisWatcher.ts

@@ -0,0 +1,39 @@
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, RedisContent } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+/** Emit a redis command trace. Key/value payload is intentionally omitted for security. */
+const emit = (command: string, duration: number): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: RedisContent = { 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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.redis === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/ScheduleWatcher.ts

@@ -0,0 +1,54 @@
+/**
+ * ScheduleWatcher — records scheduled task runs and outcomes.
+ */
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, ScheduleContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  name: string,
+  expression: string,
+  status: ScheduleContent['status'],
+  duration: number,
+  output?: string
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: ScheduleContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.schedule === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/ViewWatcher.ts

@@ -0,0 +1,37 @@
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, ViewContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (template: string, duration: number): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: ViewContent = { 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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.view === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});