@zintrust/trace 1.6.6 → 1.6.7

package/src/watchers/JobWatcher.ts

@@ -1,124 +0,0 @@
-/**
- * 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 type { ITraceWatcher, ITraceWatcherConfig, JobContent } from '../types';
-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: ITraceWatcherConfig['storage'] | null = null;
-let _ignoreRoutes: string[] = [];
-let _ignorePaths: string[] = [];
-const MAX_TRACKED_JOBS = 1000;
-
-type PendingJob = { uuid: string; content: JobContent };
-
-const pendingJobs = new Map<string, PendingJob[]>();
-
-const trackPendingJob = (name: string, job: PendingJob): void => {
-  const jobs = pendingJobs.get(name) ?? [];
-  jobs.push(job);
-  if (jobs.length > MAX_TRACKED_JOBS) {
-    jobs.shift();
-  }
-  pendingJobs.set(name, jobs);
-};
-
-const takePendingJob = (name: string): PendingJob | null => {
-  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: string, queue: string, connection: string, data?: unknown): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const uuid = crypto.randomUUID();
-  const content: JobContent = {
-    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: string): void => {
-  if (!_storage) return;
-  const pendingJob = takePendingJob(name);
-  if (pendingJob === null) return;
-
-  const patch: JobContent = { ...pendingJob.content, status: 'processed' };
-  void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
-};
-
-const emitFailed = (name: string, error: Error): void => {
-  if (!_storage) return;
-  const pendingJob = takePendingJob(name);
-  if (pendingJob === null) return;
-
-  const patch: JobContent = {
-    ...pendingJob.content,
-    status: 'failed',
-    exception: {
-      message: error.message,
-      trace: (error.stack ?? '')
-        .split('\n')
-        .slice(1)
-        .map(parseStackFrameLine)
-        .filter((trace): trace is { file: string; line: number } => trace !== null)
-        .slice(0, 10),
-    },
-  };
-
-  void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
-};
-
-export const JobWatcher: ITraceWatcher & {
-  onDispatch: typeof emitDispatch;
-  onProcessed: typeof emitProcessed;
-  onFailed: typeof emitFailed;
-} = Object.freeze({
-  onDispatch: emitDispatch,
-  onProcessed: emitProcessed,
-  onFailed: emitFailed,
-
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.job === false) return () => undefined;
-    _storage = storage;
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-      pendingJobs.clear();
-    };
-  },
-});

package/src/watchers/LogWatcher.ts

@@ -1,120 +0,0 @@
-/**
- * LogWatcher — captures Logger output via Logger.addSink().
- */
-import { Logger } from '@zintrust/core';
-import { TraceContext } from '../context';
-import type { ITraceWatcher, ITraceWatcherConfig, LogContent } from '../types';
-import { EntryType } from '../types';
-import { AuthTag } from '../utils/authTag';
-import { RequestFilter } from '../utils/requestFilter';
-
-const LEVEL_PRIORITY: Record<string, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  fatal: 4,
-};
-
-const TRACE_INFRASTRUCTURE_LOG_MESSAGES = new Set<string>([
-  '[MySQLProxyAdapter] Proxy request failed',
-  '[trace] Trace storage write degraded',
-]);
-
-const TRACE_STORAGE_TABLE_NAMES = [
-  'zin_trace_entries',
-  'zin_trace_entries_tags',
-  'zin_trace_monitoring',
-];
-
-const isTraceStorageQuery = (sql: string): boolean => {
-  const normalized = sql.toLowerCase();
-  return TRACE_STORAGE_TABLE_NAMES.some((tableName) => normalized.includes(tableName));
-};
-
-const extractSqlFromLog = (
-  message: string,
-  context?: Record<string, unknown>
-): string | undefined => {
-  const contextSql = context?.['sql'];
-  if (typeof contextSql === 'string') return contextSql;
-
-  const trimmed = message.trim();
-  const rawPrefix = 'Raw SQL Query executed:';
-  if (trimmed.startsWith(rawPrefix)) {
-    const sql = trimmed.slice(rawPrefix.length).trim();
-    return sql === '' ? undefined : sql;
-  }
-
-  return undefined;
-};
-
-const isTraceStorageQueryLog = (message: string, context?: Record<string, unknown>): boolean => {
-  const normalizedMessage = message.trim().toLowerCase();
-  if (!normalizedMessage.includes('query executed')) return false;
-
-  const sql = extractSqlFromLog(message, context);
-  return typeof sql === 'string' && isTraceStorageQuery(sql);
-};
-
-const shouldSkipTraceInfrastructureLog = (
-  message: string,
-  context?: Record<string, unknown>
-): boolean => {
-  const loggerWithTraceSkip = Logger as typeof Logger & {
-    shouldSkipTraceLogContext?: (ctx?: Record<string, unknown>) => boolean;
-  };
-
-  if (loggerWithTraceSkip.shouldSkipTraceLogContext?.(context) === true) {
-    return true;
-  }
-
-  return (
-    TRACE_INFRASTRUCTURE_LOG_MESSAGES.has(message.trim()) ||
-    isTraceStorageQueryLog(message, context)
-  );
-};
-
-export const LogWatcher: ITraceWatcher = Object.freeze({
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    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: string, message: string, context?: Record<string, unknown>) => {
-        if ((LEVEL_PRIORITY[level] ?? 0) < minPriority) return;
-        if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes, config.ignorePaths))
-          return;
-        if (shouldSkipTraceInfrastructureLog(message, context)) return;
-
-        const content: LogContent = {
-          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/src/watchers/MailWatcher.ts

@@ -1,65 +0,0 @@
-/**
- * MailWatcher — records mail dispatch intent and rendered content.
- */
-import { TraceContext } from '../context';
-import type { ITraceWatcher, ITraceWatcherConfig, MailContent } from '../types';
-import { EntryType } from '../types';
-import { redactUnknown } from '../utils/redact';
-import { RequestFilter } from '../utils/requestFilter';
-
-let _storage: ITraceWatcherConfig['storage'] | null = null;
-let _redactionFields: string[] = [];
-let _ignoreRoutes: string[] = [];
-let _ignorePaths: string[] = [];
-
-const emit = (
-  to: string,
-  subject: string,
-  template?: string,
-  text?: string,
-  html?: string
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const content: MailContent = {
-    to,
-    subject,
-    template,
-    ...(typeof text === 'string' && text !== ''
-      ? { text: redactUnknown(text, _redactionFields) as string }
-      : {}),
-    ...(typeof html === 'string' && html !== ''
-      ? { html: redactUnknown(html, _redactionFields) as string }
-      : {}),
-    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
-  emit,
-
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.mail === false) return () => undefined;
-    _storage = storage;
-    _redactionFields = [...config.redaction.keys, ...config.redaction.body];
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _redactionFields = [];
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/MiddlewareWatcher.ts

@@ -1,54 +0,0 @@
-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[] = [];
-let _ignorePaths: string[] = [];
-
-type GlobalMiddlewareTraceState = {
-  __zintrust_trace_middleware_emit__?: typeof emit;
-};
-
-const emit = (name: string, event: MiddlewareContent['event'], duration?: number): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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;
-    _ignorePaths = config.ignorePaths;
-    (globalThis as unknown as GlobalMiddlewareTraceState).__zintrust_trace_middleware_emit__ = emit;
-    return () => {
-      const globalState = globalThis as unknown as GlobalMiddlewareTraceState;
-      if (globalState.__zintrust_trace_middleware_emit__ === emit) {
-        delete globalState.__zintrust_trace_middleware_emit__;
-      }
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/ModelWatcher.ts

@@ -1,60 +0,0 @@
-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[] = [];
-let _ignorePaths: string[] = [];
-
-type GlobalModelTraceState = {
-  __zintrust_trace_model_emit__?: typeof emit;
-};
-
-const emit = (
-  action: ModelContent['action'],
-  model: string,
-  id?: string | number,
-  changes?: Record<string, unknown>
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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;
-    _ignorePaths = config.ignorePaths;
-    (globalThis as unknown as GlobalModelTraceState).__zintrust_trace_model_emit__ = emit;
-    return () => {
-      const globalState = globalThis as unknown as GlobalModelTraceState;
-      if (globalState.__zintrust_trace_model_emit__ === emit) {
-        delete globalState.__zintrust_trace_model_emit__;
-      }
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/NotificationWatcher.ts

@@ -1,60 +0,0 @@
-import { TraceContext } from '../context';
-import type { ITraceWatcher, ITraceWatcherConfig, NotificationContent } from '../types';
-import { EntryType } from '../types';
-import { AuthTag } from '../utils/authTag';
-import { redactUnknown } from '../utils/redact';
-import { RequestFilter } from '../utils/requestFilter';
-
-let _storage: ITraceWatcherConfig['storage'] | null = null;
-let _redactionFields: string[] = [];
-let _ignoreRoutes: string[] = [];
-let _ignorePaths: string[] = [];
-
-const emit = (
-  notification: string,
-  channels: string[],
-  notifiable?: string,
-  message?: string,
-  payload?: unknown
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const content: NotificationContent = {
-    notification,
-    channels,
-    notifiable,
-    ...(typeof message === 'string' && message !== ''
-      ? { message: redactUnknown(message, _redactionFields) as string }
-      : {}),
-    ...(payload === undefined ? {} : { payload: redactUnknown(payload, _redactionFields) }),
-    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;
-    _redactionFields = [...config.redaction.keys, ...config.redaction.body];
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _redactionFields = [];
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/QueryWatcher.ts

@@ -1,105 +0,0 @@
-/**
- * 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';
-
-let _storage: ITraceWatcherConfig['storage'] | null = null;
-let _config: ITraceWatcherConfig['config'] | null = null;
-
-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_entries_tags') ||
-    normalized.includes('zin_trace_monitoring')
-  );
-};
-
-const emit = (query: string, params: unknown[], duration: number, connection = 'default'): void => {
-  if (_storage === null || _config === null) return;
-  if (isTraceStorageQuery(query)) return;
-
-  const batchId = TraceContext.getBatchId();
-  const includeBindings = _config.captureQueryBindings !== false;
-  const sql = includeBindings ? bindingsInterpolated(query, params) : query;
-  const roundedDuration = Math.round(duration * 100) / 100;
-  const hash = TraceStorage.familyHash(query);
-  const slow = roundedDuration >= _config.slowQueryThreshold;
-
-  const content: QueryContent = {
-    connection,
-    sql,
-    statement: query,
-    ...(includeBindings ? { bindings: [...params] } : {}),
-    bindingsIncluded: includeBindings,
-    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);
-};
-
-export const QueryWatcher: ITraceWatcher & { emit: typeof emit } = Object.freeze({
-  emit,
-
-  register({ storage, config, db: injectedDb }: ITraceWatcherConfig): () => void {
-    if (config.watchers.query === false) return () => undefined;
-    if (!injectedDb) return () => undefined; // no db available
-
-    _storage = storage;
-    _config = config;
-    const db = injectedDb;
-
-    const handler = (query: string, params: unknown[], duration: number): void => {
-      emit(query, params, duration);
-    };
-
-    (
-      db as {
-        onAfterQuery?: (h: (sql: string, params: unknown[], duration: number) => void) => void;
-      }
-    ).onAfterQuery?.(handler);
-
-    return () => {
-      _storage = null;
-      _config = null;
-      (
-        db as {
-          offAfterQuery?: (h: (sql: string, params: unknown[], duration: number) => void) => void;
-        }
-      ).offAfterQuery?.(handler);
-    };
-  },
-});

package/src/watchers/RedisWatcher.ts

@@ -1,42 +0,0 @@
-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[] = [];
-let _ignorePaths: 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, _ignorePaths)) 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;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/ScheduleWatcher.ts

@@ -1,57 +0,0 @@
-/**
- * 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[] = [];
-let _ignorePaths: string[] = [];
-
-const emit = (
-  name: string,
-  expression: string,
-  status: ScheduleContent['status'],
-  duration: number,
-  output?: string
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});