@zintrust/trace 0.4.76 → 0.4.77

package/src/register.ts

@@ -22,7 +22,10 @@
 import { TraceConfig } from './config';
 import { TraceContext } from './context';
 import { TraceStorage } from './storage';
-import type { ITraceWatcherConfig } from './types';
+import { TraceContentRedaction } from './storage/TraceContentRedaction';
+import { TraceEntryFiltering } from './storage/TraceEntryFiltering';
+import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics';
+import type { ITraceWatcherConfig, TraceConfigOverrides } from './types';
 
 export type {}; // side-effect ESM module
 
@@ -58,6 +61,15 @@ type CoreApi = {
   RequestContext?: {
     current(): unknown;
   };
+  Logger?: {
+    warn(message: string, context?: Record<string, unknown>): void;
+  };
+  StartupConfigFile?: {
+    Trace?: string;
+  };
+  StartupConfigFileRegistry?: {
+    get<T>(file: string): T | undefined;
+  };
 };
 
 type GlobalMiddlewareRegistrarState = {
@@ -101,35 +113,150 @@ const resolveTraceConnectionName = (
   return resolveDefaultConnection();
 };
 
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const parseEnvList = (rawValue: string): string[] | undefined => {
+  const value = rawValue.trim();
+  if (value === '') return undefined;
+
+  if (value.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      if (Array.isArray(parsed)) {
+        return parsed
+          .filter((entry): entry is string => typeof entry === 'string')
+          .map((entry) => entry.trim())
+          .filter((entry) => entry !== '');
+      }
+    } catch {
+      // fall through to CSV parsing
+    }
+  }
+
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '');
+};
+
+const resolveTraceStartupOverrides = (core: CoreApi): TraceConfigOverrides | undefined => {
+  const traceConfigFile = core.StartupConfigFile?.Trace;
+  if (typeof traceConfigFile !== 'string' || traceConfigFile.trim() === '') return undefined;
+
+  const overrides = core.StartupConfigFileRegistry?.get<unknown>(traceConfigFile);
+  return isObjectValue(overrides) ? (overrides as TraceConfigOverrides) : undefined;
+};
+
+const buildTraceRedactionOverrides = (input: {
+  startupOverrides?: TraceConfigOverrides;
+  redactionBody?: string[];
+  redactionHeaders?: string[];
+  redactionKeys?: string[];
+  redactionQuery?: string[];
+}): TraceConfigOverrides['redaction'] | undefined => {
+  const redaction: Partial<NonNullable<TraceConfigOverrides['redaction']>> = {
+    ...(isObjectValue(input.startupOverrides?.redaction) ? input.startupOverrides?.redaction : {}),
+  };
+
+  if (input.redactionKeys === undefined) {
+    // no-op
+  } else {
+    redaction.keys = input.redactionKeys;
+  }
+
+  if (input.redactionHeaders === undefined) {
+    // no-op
+  } else {
+    redaction.headers = input.redactionHeaders;
+  }
+
+  if (input.redactionBody === undefined) {
+    // no-op
+  } else {
+    redaction.body = input.redactionBody;
+  }
+
+  if (input.redactionQuery === undefined) {
+    // no-op
+  } else {
+    redaction.query = input.redactionQuery;
+  }
+
+  return Object.keys(redaction).length > 0
+    ? (redaction as NonNullable<TraceConfigOverrides['redaction']>)
+    : undefined;
+};
+
 const core = (await importCore()) as CoreApi;
 const Env = core.Env;
+const startupOverrides = resolveTraceStartupOverrides(core);
 
 if (!traceAlreadyInitialized && Env) {
-  const enabled = Env.getBool('TRACE_ENABLED', false);
+  const enabled = startupOverrides?.enabled === true || Env.getBool('TRACE_ENABLED', false);
 
   if (enabled) {
-    const connection = Env.get('TRACE_DB_CONNECTION', '') || undefined;
-    const pruneAfterHours = Env.getInt('TRACE_PRUNE_HOURS', 24);
-    const slowQueryThreshold = Env.getInt('TRACE_SLOW_QUERY_MS', 100);
-    const logMinLevel = Env.get('TRACE_LOG_LEVEL', 'info') as
+    const connectionRaw = Env.get('TRACE_DB_CONNECTION', '').trim();
+    const pruneAfterHoursRaw = Env.get('TRACE_PRUNE_HOURS', '').trim();
+    const slowQueryThresholdRaw = Env.get('TRACE_SLOW_QUERY_MS', '').trim();
+    const logMinLevelRaw = Env.get('TRACE_LOG_LEVEL', '').trim();
+    const redactionKeys = parseEnvList(Env.get('TRACE_REDACT_KEYS', ''));
+    const redactionHeaders = parseEnvList(Env.get('TRACE_REDACT_HEADERS', ''));
+    const redactionBody = parseEnvList(Env.get('TRACE_REDACT_BODY', ''));
+    const redactionQuery = parseEnvList(Env.get('TRACE_REDACT_QUERY', ''));
+
+    const connection = connectionRaw === '' ? startupOverrides?.connection : connectionRaw;
+    const pruneAfterHours =
+      pruneAfterHoursRaw === ''
+        ? startupOverrides?.pruneAfterHours
+        : Number.parseInt(pruneAfterHoursRaw, 10);
+    const slowQueryThreshold =
+      slowQueryThresholdRaw === ''
+        ? startupOverrides?.slowQueryThreshold
+        : Number.parseInt(slowQueryThresholdRaw, 10);
+    const logMinLevel = (logMinLevelRaw === '' ? startupOverrides?.logMinLevel : logMinLevelRaw) as
       | 'debug'
       | 'info'
       | 'warn'
       | 'error'
       | 'fatal';
+    const redaction = buildTraceRedactionOverrides({
+      startupOverrides,
+      redactionBody,
+      redactionHeaders,
+      redactionKeys,
+      redactionQuery,
+    });
 
     const config = TraceConfig.merge({
+      ...startupOverrides,
       enabled,
       connection,
-      pruneAfterHours,
-      slowQueryThreshold,
+      ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
+        ? { pruneAfterHours }
+        : {}),
+      ...(typeof slowQueryThreshold === 'number' && Number.isFinite(slowQueryThreshold)
+        ? { slowQueryThreshold }
+        : {}),
       logMinLevel,
+      ...(redaction === undefined ? {} : { redaction }),
     });
 
-    const db = core.useDatabase?.(undefined, resolveTraceConnectionName(Env, connection));
+    const resolvedConnectionName = resolveTraceConnectionName(Env, config.connection);
+    const db = core.useDatabase?.(undefined, resolvedConnectionName);
 
     if (db) {
-      const storage = TraceStorage.resolveStorage(db);
+      const storage = TraceWriteDiagnostics.wrapStorage(
+        TraceContentRedaction.wrapStorage(
+          TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(db), config),
+          config.redaction
+        ),
+        {
+          connectionName: resolvedConnectionName,
+          logger: core.Logger,
+        }
+      );
 
       if (core.RequestContext) {
         TraceContext.setRequestContextImpl(

package/src/storage/TraceContentRedaction.ts

@@ -0,0 +1,44 @@
+import type { ITraceEntry, ITraceStorage, RedactionConfig } from '../types';
+import { redactUnknown } from '../utils/redact';
+
+const collectRedactionFields = (redaction: RedactionConfig): string[] => {
+  return [
+    ...new Set([...redaction.keys, ...redaction.headers, ...redaction.body, ...redaction.query]),
+  ];
+};
+
+const redactTraceEntry = (entry: ITraceEntry, redaction: RedactionConfig): ITraceEntry => {
+  return {
+    ...entry,
+    content: redactUnknown(entry.content, collectRedactionFields(redaction)),
+  };
+};
+
+const redactTracePatch = (
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>,
+  redaction: RedactionConfig
+): Partial<Pick<ITraceEntry, 'content' | 'isLatest'>> => {
+  if (patch.content === undefined) return patch;
+
+  return {
+    ...patch,
+    content: redactUnknown(patch.content, collectRedactionFields(redaction)),
+  };
+};
+
+export const TraceContentRedaction = Object.freeze({
+  wrapStorage(storage: ITraceStorage, redaction: RedactionConfig): ITraceStorage {
+    return Object.freeze({
+      ...storage,
+      writeEntry: async (entry: ITraceEntry): Promise<void> => {
+        await storage.writeEntry(redactTraceEntry(entry, redaction));
+      },
+      updateEntry: async (
+        uuid: string,
+        patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+      ): Promise<void> => {
+        await storage.updateEntry(uuid, redactTracePatch(patch, redaction));
+      },
+    });
+  },
+});

package/src/storage/TraceEntryFiltering.ts

@@ -0,0 +1,14 @@
+import type { ITraceConfig, ITraceEntry, ITraceStorage } from '../types';
+import { TraceEntryFilter } from '../utils/entryFilter';
+
+export const TraceEntryFiltering = Object.freeze({
+  wrapStorage(storage: ITraceStorage, config: ITraceConfig): ITraceStorage {
+    return Object.freeze({
+      ...storage,
+      async writeEntry(entry: ITraceEntry) {
+        if (!TraceEntryFilter.shouldCapture(entry, config)) return;
+        await storage.writeEntry(entry);
+      },
+    });
+  },
+});

package/src/storage/TraceStorage.ts

@@ -26,6 +26,54 @@ type EntryRow = {
 
 type TagRow = { entry_uuid: string; tag: string };
 
+type DatabaseWithDriver = IDatabase & {
+  getType?: () => string;
+};
+
+const buildIgnoreInsert = (
+  db: IDatabase,
+  table: string,
+  columns: string[],
+  conflictColumns: string[]
+): string => {
+  const columnList = columns.join(', ');
+  const placeholders = columns.map(() => '?').join(', ');
+  const driver = (db as DatabaseWithDriver).getType?.() ?? 'sqlite';
+
+  if (driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote') {
+    return `INSERT OR IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+  }
+
+  if (driver === 'mysql') {
+    return `INSERT IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+  }
+
+  if (driver === 'postgresql') {
+    return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.join(', ')}) DO NOTHING`;
+  }
+
+  if (driver === 'sqlserver') {
+    const sourceColumns = columns.map((_, index) => `v${index + 1}`);
+    const selectClause = sourceColumns.map((name) => `? AS ${name}`).join(', ');
+    const conflictClause = conflictColumns
+      .map((column) => `target.${column} = source.${column}`)
+      .join(' AND ');
+    const insertValues = columns.map((column) => `source.${column}`).join(', ');
+    const sourceProjection = columns
+      .map((column, index) => `${sourceColumns[index]} AS ${column}`)
+      .join(', ');
+
+    return [
+      `MERGE INTO ${table} WITH (HOLDLOCK) AS target`,
+      `USING (SELECT ${sourceProjection} FROM (SELECT ${selectClause}) seed) AS source`,
+      `ON ${conflictClause}`,
+      `WHEN NOT MATCHED THEN INSERT (${columnList}) VALUES (${insertValues});`,
+    ].join(' ');
+  }
+
+  return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders})`;
+};
+
 const rowToEntry = (row: EntryRow, tags: string[]): ITraceEntry => ({
   uuid: row.uuid,
   batchId: row.batch_id,
@@ -40,12 +88,11 @@ const rowToEntry = (row: EntryRow, tags: string[]): ITraceEntry => ({
 const insertTags = async (db: IDatabase, uuid: string, tags: string[]): Promise<void> => {
   if (tags.length === 0) return;
 
+  const sql = buildIgnoreInsert(db, TABLE_TAGS, ['entry_uuid', 'tag'], ['entry_uuid', 'tag']);
+
   await Promise.all(
     tags.map(async (tag) => {
-      await db.execute(`INSERT OR IGNORE INTO ${TABLE_TAGS} (entry_uuid, tag) VALUES (?, ?)`, [
-        uuid,
-        tag,
-      ]);
+      await db.execute(sql, [uuid, tag]);
     })
   );
 };
@@ -258,7 +305,7 @@ const createStorage = (db: IDatabase): ITraceStorage => {
   };
 
   const addMonitoring = async (tag: string): Promise<void> => {
-    await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
+    await db.execute(buildIgnoreInsert(db, TABLE_MONITORING, ['tag'], ['tag']), [tag]);
   };
 
   const removeMonitoring = async (tag: string): Promise<void> => {

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

@@ -44,6 +44,7 @@ export interface RequestContent {
   payload: Record<string, 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;
+  },
+});