@zintrust/trace 0.4.76 → 0.4.79

package/src/storage/TraceWriteDiagnostics.ts

@@ -0,0 +1,174 @@
+import type { EntryTypeValue, ITraceEntry, ITraceStorage } from '../types';
+
+type TraceLogger = {
+  warn: (message: string, context?: Record<string, unknown>) => void;
+};
+
+type TraceWriteFailureContext = {
+  connectionName: string;
+  error: unknown;
+  operation: string;
+  watcherType?: EntryTypeValue;
+};
+
+type TraceWriteDiagnosticsSnapshot = {
+  degraded: boolean;
+  lastErrorMessage: string | null;
+  lastFailureAt: number | null;
+  totalFailures: number;
+};
+
+type TraceWriteDiagnosticsState = TraceWriteDiagnosticsSnapshot & {
+  lastLoggedAtByFingerprint: Map<string, number>;
+};
+
+const LOG_WINDOW_MS = 30_000;
+
+const diagnosticsState: TraceWriteDiagnosticsState = {
+  degraded: false,
+  lastErrorMessage: null,
+  lastFailureAt: null,
+  lastLoggedAtByFingerprint: new Map<string, number>(),
+  totalFailures: 0,
+};
+
+const getErrorMessage = (error: unknown): string => {
+  if (error instanceof Error && error.message.trim() !== '') return error.message;
+  if (typeof error === 'string' && error.trim() !== '') return error;
+
+  try {
+    const serialized = JSON.stringify(error);
+    if (typeof serialized === 'string' && serialized !== '') return serialized;
+  } catch {
+    // ignore serialization failures
+  }
+
+  return 'Unknown trace storage error';
+};
+
+const buildFingerprint = (context: TraceWriteFailureContext): string => {
+  return [
+    context.connectionName,
+    context.operation,
+    context.watcherType ?? 'unknown',
+    getErrorMessage(context.error),
+  ].join('|');
+};
+
+const reportFailure = (
+  logger: TraceLogger | undefined,
+  context: TraceWriteFailureContext
+): void => {
+  const now = Date.now();
+  const errorMessage = getErrorMessage(context.error);
+  const fingerprint = buildFingerprint(context);
+  const lastLoggedAt = diagnosticsState.lastLoggedAtByFingerprint.get(fingerprint);
+
+  diagnosticsState.degraded = true;
+  diagnosticsState.lastErrorMessage = errorMessage;
+  diagnosticsState.lastFailureAt = now;
+  diagnosticsState.totalFailures += 1;
+
+  if (!logger) return;
+  if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS) return;
+
+  diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
+  logger.warn('[trace] Trace storage write degraded', {
+    connectionName: context.connectionName,
+    error: errorMessage,
+    lastFailureAt: now,
+    operation: context.operation,
+    totalFailures: diagnosticsState.totalFailures,
+    watcherType: context.watcherType ?? null,
+  });
+};
+
+const wrapStorageMethod = <TArgs extends unknown[], TResult>(
+  method: (...args: TArgs) => Promise<TResult>,
+  describeFailure: (...args: TArgs) => Omit<TraceWriteFailureContext, 'connectionName' | 'error'>,
+  connectionName: string,
+  logger?: TraceLogger
+): ((...args: TArgs) => Promise<TResult>) => {
+  return async (...args: TArgs): Promise<TResult> => {
+    try {
+      return await method(...args);
+    } catch (error) {
+      reportFailure(logger, {
+        ...describeFailure(...args),
+        connectionName,
+        error,
+      });
+      throw error;
+    }
+  };
+};
+
+export const TraceWriteDiagnostics = Object.freeze({
+  getSnapshot(): TraceWriteDiagnosticsSnapshot {
+    return {
+      degraded: diagnosticsState.degraded,
+      lastErrorMessage: diagnosticsState.lastErrorMessage,
+      lastFailureAt: diagnosticsState.lastFailureAt,
+      totalFailures: diagnosticsState.totalFailures,
+    };
+  },
+
+  reset(): void {
+    diagnosticsState.degraded = false;
+    diagnosticsState.lastErrorMessage = null;
+    diagnosticsState.lastFailureAt = null;
+    diagnosticsState.totalFailures = 0;
+    diagnosticsState.lastLoggedAtByFingerprint.clear();
+  },
+
+  wrapStorage(
+    storage: ITraceStorage,
+    options: { connectionName: string; logger?: TraceLogger }
+  ): ITraceStorage {
+    return Object.freeze({
+      ...storage,
+      writeEntry: wrapStorageMethod(
+        storage.writeEntry.bind(storage),
+        (entry: ITraceEntry) => ({ operation: 'writeEntry', watcherType: entry.type }),
+        options.connectionName,
+        options.logger
+      ),
+      updateEntry: wrapStorageMethod(
+        storage.updateEntry.bind(storage),
+        (_uuid: string, _patch) => ({ operation: 'updateEntry' }),
+        options.connectionName,
+        options.logger
+      ),
+      markFamilyStale: wrapStorageMethod(
+        storage.markFamilyStale.bind(storage),
+        (_familyHash: string, _exceptUuid: string) => ({ operation: 'markFamilyStale' }),
+        options.connectionName,
+        options.logger
+      ),
+      prune: wrapStorageMethod(
+        storage.prune.bind(storage),
+        (_olderThanMs: number, _keepExceptions?: boolean) => ({ operation: 'prune' }),
+        options.connectionName,
+        options.logger
+      ),
+      clear: wrapStorageMethod(
+        storage.clear.bind(storage),
+        () => ({ operation: 'clear' }),
+        options.connectionName,
+        options.logger
+      ),
+      addMonitoring: wrapStorageMethod(
+        storage.addMonitoring.bind(storage),
+        (_tag: string) => ({ operation: 'addMonitoring' }),
+        options.connectionName,
+        options.logger
+      ),
+      removeMonitoring: wrapStorageMethod(
+        storage.removeMonitoring.bind(storage),
+        (_tag: string) => ({ operation: 'removeMonitoring' }),
+        options.connectionName,
+        options.logger
+      ),
+    });
+  },
+});

package/src/types.ts

@@ -41,9 +41,10 @@ export interface RequestContent {
   method: string;
   uri: string;
   headers: Record<string, string>;
-  payload: Record<string, unknown>;
+  payload: unknown;
   responseStatus: number;
   responseHeaders: Record<string, string>;
+  responseBody?: unknown;
   duration: number;
   memory: number | null;
   middleware: string[];
@@ -275,32 +276,51 @@ export interface ITraceWatcher {
 // ---------------------------------------------------------------------------
 
 export type RedactionConfig = {
+  keys: string[];
   headers: string[];
   body: string[];
   query: string[];
 };
 
+export type TraceFilterRule = {
+  enabled?: boolean;
+  include?: string[];
+  exclude?: string[];
+};
+
+export type TraceRequestWatcherConfig = TraceFilterRule & {
+  all?: TraceFilterRule;
+  get?: TraceFilterRule;
+  post?: TraceFilterRule;
+  put?: TraceFilterRule;
+  patch?: TraceFilterRule;
+  delete?: TraceFilterRule;
+};
+
+export type TraceWatcherToggle = boolean | TraceFilterRule;
+export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
+
 export type WatcherToggles = {
-  request?: boolean;
-  query?: boolean;
-  exception?: boolean;
-  log?: boolean;
-  job?: boolean;
-  cache?: boolean;
-  schedule?: boolean;
-  mail?: boolean;
-  auth?: boolean;
-  event?: boolean;
-  model?: boolean;
-  notification?: boolean;
-  redis?: boolean;
-  gate?: boolean;
-  middleware?: boolean;
-  command?: boolean;
-  batch?: boolean;
-  dump?: boolean;
-  view?: boolean;
-  clientRequest?: boolean;
+  request?: TraceRequestWatcherToggle;
+  query?: TraceWatcherToggle;
+  exception?: TraceWatcherToggle;
+  log?: TraceWatcherToggle;
+  job?: TraceWatcherToggle;
+  cache?: TraceWatcherToggle;
+  schedule?: TraceWatcherToggle;
+  mail?: TraceWatcherToggle;
+  auth?: TraceWatcherToggle;
+  event?: TraceWatcherToggle;
+  model?: TraceWatcherToggle;
+  notification?: TraceWatcherToggle;
+  redis?: TraceWatcherToggle;
+  gate?: TraceWatcherToggle;
+  middleware?: TraceWatcherToggle;
+  command?: TraceWatcherToggle;
+  batch?: TraceWatcherToggle;
+  dump?: TraceWatcherToggle;
+  view?: TraceWatcherToggle;
+  clientRequest?: TraceWatcherToggle;
 };
 
 export interface ITraceConfig {

package/src/utils/entryFilter.ts

@@ -0,0 +1,108 @@
+import type {
+  ITraceConfig,
+  ITraceEntry,
+  TraceFilterRule,
+  TraceRequestWatcherConfig,
+  WatcherToggles,
+} from '../types';
+import { EntryType } from '../types';
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const normalizeTerms = (terms?: string[]): string[] => {
+  if (!Array.isArray(terms)) return [];
+
+  return terms
+    .filter((term): term is string => typeof term === 'string')
+    .map((term) => term.trim().toLowerCase())
+    .filter((term) => term !== '');
+};
+
+const matchesRule = (haystack: string, rule?: TraceFilterRule): boolean => {
+  if (!rule) return true;
+
+  const include = normalizeTerms(rule.include);
+  const exclude = normalizeTerms(rule.exclude);
+
+  if (exclude.some((term) => haystack.includes(term))) return false;
+  if (include.length === 0) return true;
+
+  return include.some((term) => haystack.includes(term));
+};
+
+const toSearchableText = (entry: ITraceEntry): string => {
+  const sections = [entry.type, entry.batchId, ...(entry.tags ?? [])];
+
+  try {
+    sections.push(JSON.stringify(entry.content) ?? '');
+  } catch {
+    sections.push(String(entry.content ?? ''));
+  }
+
+  return sections.join(' ').toLowerCase();
+};
+
+const watcherKeyByEntryType: Record<ITraceEntry['type'], keyof WatcherToggles> = {
+  [EntryType.REQUEST]: 'request',
+  [EntryType.QUERY]: 'query',
+  [EntryType.EXCEPTION]: 'exception',
+  [EntryType.LOG]: 'log',
+  [EntryType.JOB]: 'job',
+  [EntryType.CACHE]: 'cache',
+  [EntryType.SCHEDULE]: 'schedule',
+  [EntryType.MAIL]: 'mail',
+  [EntryType.AUTH]: 'auth',
+  [EntryType.EVENT]: 'event',
+  [EntryType.MODEL]: 'model',
+  [EntryType.NOTIFICATION]: 'notification',
+  [EntryType.REDIS]: 'redis',
+  [EntryType.GATE]: 'gate',
+  [EntryType.MIDDLEWARE]: 'middleware',
+  [EntryType.COMMAND]: 'command',
+  [EntryType.BATCH]: 'batch',
+  [EntryType.DUMP]: 'dump',
+  [EntryType.VIEW]: 'view',
+  [EntryType.CLIENT_REQUEST]: 'clientRequest',
+};
+
+const getRequestMethodRule = (
+  watcher: TraceRequestWatcherConfig,
+  entry: ITraceEntry
+): TraceFilterRule | undefined => {
+  if (entry.type !== EntryType.REQUEST) return undefined;
+
+  const content = isObjectValue(entry.content) ? entry.content : undefined;
+  const methodValue = content?.['method'];
+  const method = typeof methodValue === 'string' ? methodValue.trim().toLowerCase() : '';
+
+  if (method === 'get') return watcher.get;
+  if (method === 'post') return watcher.post;
+  if (method === 'put') return watcher.put;
+  if (method === 'patch') return watcher.patch;
+  if (method === 'delete' || method === 'del') return watcher.delete;
+
+  return watcher.all;
+};
+
+export const TraceEntryFilter = Object.freeze({
+  shouldCapture(entry: ITraceEntry, config: ITraceConfig): boolean {
+    const watcherKey = watcherKeyByEntryType[entry.type];
+    const watcher = config.watchers[watcherKey];
+    if (watcher === false) return false;
+    if (!isObjectValue(watcher)) return true;
+
+    const haystack = toSearchableText(entry);
+    if (!matchesRule(haystack, watcher)) return false;
+
+    if (watcherKey === 'request') {
+      const requestWatcher = watcher as TraceRequestWatcherConfig;
+      const methodRule = getRequestMethodRule(requestWatcher, entry);
+      if (!matchesRule(haystack, requestWatcher.all)) return false;
+      if (!matchesRule(haystack, methodRule)) return false;
+    }
+
+    return true;
+  },
+});

package/src/utils/redact.ts

@@ -2,7 +2,55 @@
  * Redaction helpers for @zintrust/trace watchers.
  */
 
-const REDACTED = '[REDACTED]';
+const REDACTED = '****';
+
+const isArrayValue = (value: unknown): value is unknown[] => Array.isArray(value);
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const normalizeFields = (fields: string[]): Set<string> => {
+  const normalized = new Set<string>();
+
+  for (const field of fields) {
+    if (typeof field !== 'string') continue;
+    const key = field.trim().toLowerCase();
+    if (key !== '') normalized.add(key);
+  }
+
+  return normalized;
+};
+
+const redactUnknownValue = (
+  value: unknown,
+  fields: Set<string>,
+  seen: WeakSet<object>
+): unknown => {
+  if (isArrayValue(value)) {
+    return value.map((item) => redactUnknownValue(item, fields, seen));
+  }
+
+  if (!isObjectValue(value)) {
+    return value;
+  }
+
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+
+  seen.add(value);
+  const out: Record<string, unknown> = {};
+
+  for (const [key, entryValue] of Object.entries(value)) {
+    out[key] = fields.has(key.toLowerCase())
+      ? REDACTED
+      : redactUnknownValue(entryValue, fields, seen);
+  }
+
+  seen.delete(value);
+  return out;
+};
 
 const redactQuerySegment = (segment: string, fields: Set<string>): string => {
   const separatorIndex = segment.indexOf('=');
@@ -19,7 +67,7 @@ export const redactHeaders = (
   headers: Record<string, string>,
   fields: string[]
 ): Record<string, string> => {
-  const lower = new Set(fields.map((f) => f.toLowerCase()));
+  const lower = normalizeFields(fields);
   const out: Record<string, string> = {};
   for (const [k, v] of Object.entries(headers)) {
     out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
@@ -27,20 +75,20 @@ export const redactHeaders = (
   return out;
 };
 
+export const redactUnknown = (value: unknown, fields: string[]): unknown => {
+  return redactUnknownValue(value, normalizeFields(fields), new WeakSet<object>());
+};
+
 export const redactObject = (
   obj: Record<string, unknown>,
   fields: string[]
 ): Record<string, unknown> => {
-  const lower = new Set(fields.map((f) => f.toLowerCase()));
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(obj)) {
-    out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
-  }
-  return out;
+  const redacted = redactUnknown(obj, fields);
+  return isObjectValue(redacted) ? redacted : {};
 };
 
 export const redactString = (value: string, fields: string[]): string => {
-  const lower = new Set(fields.map((f) => f.toLowerCase()));
+  const lower = normalizeFields(fields);
   if (value === '') return value;
 
   let output = '';

package/src/watchers/CommandWatcher.ts

@@ -45,7 +45,7 @@ export const CommandWatcher: ITraceWatcher & { emit: typeof emit } = Object.free
   register({ storage, config }: ITraceWatcherConfig): () => void {
     if (config.watchers.command === false) return () => undefined;
     _storage = storage;
-    _redactKeys = config.redaction?.body ?? [];
+    _redactKeys = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;

package/src/watchers/ExceptionWatcher.ts

@@ -12,11 +12,18 @@ import { familyHash } from '../utils/familyHash';
 import { RequestFilter } from '../utils/requestFilter';
 import { parseStackFrameLine } from '../utils/stackFrame';
 
+type ExceptionCaptureContext = {
+  batchId?: string;
+  hostname?: string;
+  path?: string;
+  userId?: string;
+};
+
 const getLinePreview = (_file: string, _line: number): Record<string, string> => {
   return {};
 };
 
-const buildContent = (err: Error): ExceptionContent => {
+const buildContent = (err: Error, context?: ExceptionCaptureContext): ExceptionContent => {
   const stack = err.stack ?? '';
   const trace: ExceptionContent['trace'] = stack
     .split('\n')
@@ -35,8 +42,8 @@ const buildContent = (err: Error): ExceptionContent => {
     trace,
     linePreview: firstFrame ? getLinePreview(firstFrame.file, firstFrame.line) : {},
     occurrences: 1,
-    hostname: TraceContext.getHostname(),
-    userId: TraceContext.getUserId(),
+    hostname: context?.hostname ?? TraceContext.getHostname(),
+    userId: context?.userId ?? TraceContext.getUserId(),
   };
 };
 
@@ -64,20 +71,24 @@ const unregisterProcessListeners = (): void => {
   process.off('unhandledRejection', handleUnhandledRejection);
 };
 
-const captureException = (err: unknown): void => {
+const captureException = (err: unknown, context?: ExceptionCaptureContext): void => {
   const storage = _storage;
   if (!storage) return;
   if (!(err instanceof Error)) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  if (context?.path !== undefined) {
+    if (RequestFilter.matchesIgnoredPath(context.path, _ignoreRoutes)) return;
+  } else if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) {
+    return;
+  }
 
-  const content = buildContent(err);
+  const content = buildContent(err, context);
   const hash = familyHash(`${content.class}:${content.file}:${content.line}`);
   const uuid = crypto.randomUUID();
 
   storage
     .writeEntry({
       uuid,
-      batchId: TraceContext.getBatchId(),
+      batchId: context?.batchId ?? TraceContext.getBatchId(),
       familyHash: hash,
       type: EntryType.EXCEPTION,
       content,
@@ -89,7 +100,9 @@ const captureException = (err: unknown): void => {
     .catch(() => undefined);
 };
 
-export const ExceptionWatcher: ITraceWatcher & { capture: (err: unknown) => void } = Object.freeze({
+export const ExceptionWatcher: ITraceWatcher & {
+  capture: (err: unknown, context?: ExceptionCaptureContext) => void;
+} = Object.freeze({
   capture: captureException,
 
   register({ storage, config }: ITraceWatcherConfig): () => void {

package/src/watchers/HttpClientWatcher.ts

@@ -46,7 +46,7 @@ export const HttpClientWatcher: ITraceWatcher & { emit: typeof emit } = Object.f
   register({ storage, config }: ITraceWatcherConfig): () => void {
     if (config.watchers.clientRequest === false) return () => undefined;
     _storage = storage;
-    _redactHeaderNames = config.redaction?.headers ?? [];
+    _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;