@zintrust/trace 0.4.81 → 0.4.83

package/src/register.ts

@@ -113,6 +113,26 @@ const resolveTraceConnectionName = (
   return resolveDefaultConnection();
 };
 
+const resolveObservedConnectionName = (
+  env: Pick<NonNullable<CoreApi['Env']>, 'get'> | undefined,
+  configuredObservedConnection: string | undefined,
+  storageConnectionName: string
+): string => {
+  if (
+    typeof configuredObservedConnection === 'string' &&
+    configuredObservedConnection.trim() !== ''
+  ) {
+    return resolveTraceConnectionName(env, configuredObservedConnection);
+  }
+
+  const defaultConnectionName = resolveTraceConnectionName(env, undefined);
+  if (storageConnectionName !== defaultConnectionName) {
+    return defaultConnectionName;
+  }
+
+  return storageConnectionName;
+};
+
 const isObjectValue = (value: unknown): value is Record<string, unknown> => {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
@@ -141,6 +161,14 @@ const parseEnvList = (rawValue: string): string[] | undefined => {
     .filter((entry) => entry !== '');
 };
 
+const parseEnvBool = (rawValue: string): boolean | undefined => {
+  const value = rawValue.trim().toLowerCase();
+  if (value === '') return undefined;
+  if (['1', 'true', 'yes', 'on'].includes(value)) return true;
+  if (['0', 'false', 'no', 'off'].includes(value)) return false;
+  return undefined;
+};
+
 const resolveTraceStartupOverrides = (core: CoreApi): TraceConfigOverrides | undefined => {
   const traceConfigFile = core.StartupConfigFile?.Trace;
   if (typeof traceConfigFile !== 'string' || traceConfigFile.trim() === '') return undefined;
@@ -198,15 +226,20 @@ if (!traceAlreadyInitialized && Env) {
 
   if (enabled) {
     const connectionRaw = Env.get('TRACE_DB_CONNECTION', '').trim();
+    const observeConnectionRaw = Env.get('TRACE_QUERY_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 captureCachePayloadsRaw = Env.get('TRACE_CACHE_PAYLOADS', '').trim();
+    const captureQueryBindingsRaw = Env.get('TRACE_QUERY_BINDINGS', '').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 observeConnection =
+      observeConnectionRaw === '' ? startupOverrides?.observeConnection : observeConnectionRaw;
     const pruneAfterHours =
       pruneAfterHoursRaw === ''
         ? startupOverrides?.pruneAfterHours
@@ -221,6 +254,10 @@ if (!traceAlreadyInitialized && Env) {
       | 'warn'
       | 'error'
       | 'fatal';
+    const captureCachePayloads =
+      parseEnvBool(captureCachePayloadsRaw) ?? startupOverrides?.captureCachePayloads;
+    const captureQueryBindings =
+      parseEnvBool(captureQueryBindingsRaw) ?? startupOverrides?.captureQueryBindings;
     const redaction = buildTraceRedactionOverrides({
       startupOverrides,
       redactionBody,
@@ -233,23 +270,32 @@ if (!traceAlreadyInitialized && Env) {
       ...startupOverrides,
       enabled,
       connection,
+      observeConnection,
       ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
         ? { pruneAfterHours }
         : {}),
       ...(typeof slowQueryThreshold === 'number' && Number.isFinite(slowQueryThreshold)
         ? { slowQueryThreshold }
         : {}),
+      ...(typeof captureCachePayloads === 'boolean' ? { captureCachePayloads } : {}),
+      ...(typeof captureQueryBindings === 'boolean' ? { captureQueryBindings } : {}),
       logMinLevel,
       ...(redaction === undefined ? {} : { redaction }),
     });
 
     const resolvedConnectionName = resolveTraceConnectionName(Env, config.connection);
-    const db = core.useDatabase?.(undefined, resolvedConnectionName);
-
-    if (db) {
+    const resolvedObservedConnectionName = resolveObservedConnectionName(
+      Env,
+      config.observeConnection,
+      resolvedConnectionName
+    );
+    const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
+    const observedDb = core.useDatabase?.(undefined, resolvedObservedConnectionName);
+
+    if (storageDb && observedDb) {
       const storage = TraceWriteDiagnostics.wrapStorage(
         TraceContentRedaction.wrapStorage(
-          TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(db), config),
+          TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config),
           config.redaction
         ),
         {
@@ -311,7 +357,7 @@ if (!traceAlreadyInitialized && Env) {
         import('./watchers/HttpClientWatcher'),
       ]);
 
-      const watcherArgs = { storage, config, db };
+      const watcherArgs = { storage, config, db: observedDb };
 
       HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
 

package/src/types.ts

@@ -55,6 +55,9 @@ export interface RequestContent {
 export interface QueryContent {
   connection: string;
   sql: string;
+  statement?: string;
+  bindings?: unknown[];
+  bindingsIncluded?: boolean;
   time: number;
   duration: number;
   slow: boolean;
@@ -97,6 +100,10 @@ export interface CacheContent {
   operation: 'get' | 'set' | 'delete' | 'clear' | 'has';
   key: string;
   hit?: boolean;
+  store?: string;
+  payload?: unknown;
+  payloadLogged?: boolean;
+  ttl?: number;
   duration: number;
   hostname: string;
 }
@@ -114,6 +121,8 @@ export interface MailContent {
   to: string;
   subject: string;
   template?: string;
+  text?: string;
+  html?: string;
   hostname: string;
 }
 
@@ -142,6 +151,8 @@ export interface NotificationContent {
   channels: string[];
   notifiable?: string;
   notification: string;
+  message?: string;
+  payload?: unknown;
   hostname: string;
 }
 
@@ -201,11 +212,27 @@ export interface ClientRequestContent {
   method: string;
   url: string;
   requestHeaders: Record<string, string>;
-  responseStatus: number;
+  requestBody?: unknown;
+  responseStatus?: number;
+  responseHeaders?: Record<string, string>;
+  responseBody?: unknown;
+  error?: string;
   duration: number;
   hostname: string;
 }
 
+export interface ClientRequestTraceInput {
+  method: string;
+  url: string;
+  requestHeaders: Record<string, string>;
+  responseStatus?: number;
+  duration: number;
+  requestBody?: unknown;
+  responseHeaders?: Record<string, string>;
+  responseBody?: unknown;
+  error?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Core domain records
 // ---------------------------------------------------------------------------
@@ -326,9 +353,12 @@ export type WatcherToggles = {
 export interface ITraceConfig {
   enabled: boolean;
   connection?: string;
+  observeConnection?: string;
   pruneAfterHours: number;
   ignoreRoutes: string[];
   slowQueryThreshold: number;
+  captureCachePayloads: boolean;
+  captureQueryBindings: boolean;
   logMinLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
   watchers: WatcherToggles;
   redaction: RedactionConfig;

package/src/watchers/CacheWatcher.ts

@@ -6,10 +6,11 @@ import { TraceContext } from '../context';
 import type { CacheContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
 import { EntryType } from '../types';
 import { AuthTag } from '../utils/authTag';
-import { redactString } from '../utils/redact';
+import { redactString, redactUnknown } from '../utils/redact';
 import { RequestFilter } from '../utils/requestFilter';
 
 let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _config: ITraceWatcherConfig['config'] | null = null;
 let _redactionFields: string[] = [];
 let _ignoreRoutes: string[] = [];
 
@@ -17,15 +18,23 @@ const emit = (
   operation: CacheContent['operation'],
   key: string,
   duration: number,
-  hit?: boolean
+  hit?: boolean,
+  payload?: unknown,
+  store?: string,
+  ttl?: number
 ): void => {
   if (!_storage) return;
   if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
   const safeKey = redactString(key, _redactionFields);
+  const shouldLogPayload = _config?.captureCachePayloads === true;
   const content: CacheContent = {
     operation,
     key: safeKey,
     hit,
+    ...(typeof store === 'string' && store !== '' ? { store } : {}),
+    ...(typeof ttl === 'number' ? { ttl } : {}),
+    payloadLogged: shouldLogPayload,
+    ...(shouldLogPayload ? { payload: redactUnknown(payload, _redactionFields) } : {}),
     duration,
     hostname: TraceContext.getHostname(),
   };
@@ -48,10 +57,12 @@ export const CacheWatcher: ITraceWatcher & { emit: typeof emit } = Object.freeze
   register({ storage, config }: ITraceWatcherConfig): () => void {
     if (config.watchers.cache === false) return () => undefined;
     _storage = storage;
+    _config = config;
     _redactionFields = config.redaction.query;
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;
+      _config = null;
       _ignoreRoutes = [];
     };
   },

package/src/watchers/HttpClientWatcher.ts

@@ -1,30 +1,50 @@
 import { TraceContext } from '../context';
-import type { ClientRequestContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import type {
+  ClientRequestContent,
+  ClientRequestTraceInput,
+  ITraceWatcher,
+  ITraceWatcherConfig,
+} from '../types';
 import { EntryType } from '../types';
 import { AuthTag } from '../utils/authTag';
-import { redactHeaders } from '../utils/redact';
+import { redactHeaders, redactUnknown } from '../utils/redact';
 import { RequestFilter } from '../utils/requestFilter';
 
 let _storage: ITraceWatcherConfig['storage'] | null = null;
 let _redactHeaderNames: string[] = [];
+let _redactBodyFields: string[] = [];
 let _ignoreRoutes: string[] = [];
 
-const emit = (
-  method: string,
-  url: string,
-  requestHeaders: Record<string, string>,
-  responseStatus: number,
-  duration: number
-): void => {
+const emit = ({
+  method,
+  url,
+  requestHeaders,
+  responseStatus,
+  duration,
+  requestBody,
+  responseHeaders,
+  responseBody,
+  error,
+}: ClientRequestTraceInput): void => {
   if (!_storage) return;
   if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
   const tags = AuthTag.append([method.toUpperCase()]);
-  if (responseStatus >= 400) tags.push('failed');
+  if ((responseStatus ?? 0) >= 400 || error) tags.push('failed');
   const content: ClientRequestContent = {
     method: method.toUpperCase(),
     url,
     requestHeaders: redactHeaders(requestHeaders, _redactHeaderNames),
-    responseStatus,
+    ...(requestBody === undefined
+      ? {}
+      : { requestBody: redactUnknown(requestBody, _redactBodyFields) }),
+    ...(responseStatus === undefined ? {} : { responseStatus }),
+    ...(responseHeaders === undefined
+      ? {}
+      : { responseHeaders: redactHeaders(responseHeaders, _redactHeaderNames) }),
+    ...(responseBody === undefined
+      ? {}
+      : { responseBody: redactUnknown(responseBody, _redactBodyFields) }),
+    ...(typeof error === 'string' && error !== '' ? { error } : {}),
     duration,
     hostname: TraceContext.getHostname(),
   };
@@ -47,9 +67,11 @@ export const HttpClientWatcher: ITraceWatcher & { emit: typeof emit } = Object.f
     if (config.watchers.clientRequest === false) return () => undefined;
     _storage = storage;
     _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
+    _redactBodyFields = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;
+      _redactBodyFields = [];
       _ignoreRoutes = [];
     };
   },

package/src/watchers/MailWatcher.ts

@@ -1,22 +1,35 @@
 /**
- * MailWatcher — records mail dispatch intent.
- * Body is never captured; only to/subject/template.
+ * 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[] = [];
 
-const emit = (to: string, subject: string, template?: string): void => {
+const emit = (
+  to: string,
+  subject: string,
+  template?: string,
+  text?: string,
+  html?: string
+): void => {
   if (!_storage) return;
   if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) 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
@@ -38,9 +51,11 @@ export const MailWatcher: ITraceWatcher & { emit: typeof emit } = Object.freeze(
   register({ storage, config }: ITraceWatcherConfig): () => void {
     if (config.watchers.mail === false) return () => undefined;
     _storage = storage;
+    _redactionFields = [...config.redaction.keys, ...config.redaction.body];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;
+      _redactionFields = [];
       _ignoreRoutes = [];
     };
   },

package/src/watchers/NotificationWatcher.ts

@@ -2,18 +2,30 @@ 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[] = [];
 
-const emit = (notification: string, channels: string[], notifiable?: string): void => {
+const emit = (
+  notification: string,
+  channels: string[],
+  notifiable?: string,
+  message?: string,
+  payload?: unknown
+): void => {
   if (!_storage) return;
   if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) 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
@@ -34,9 +46,11 @@ export const NotificationWatcher: ITraceWatcher & { emit: typeof emit } = Object
   register({ storage, config }: ITraceWatcherConfig): () => void {
     if (config.watchers.notification === false) return () => undefined;
     _storage = storage;
+    _redactionFields = [...config.redaction.keys, ...config.redaction.body];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;
+      _redactionFields = [];
       _ignoreRoutes = [];
     };
   },

package/src/watchers/QueryWatcher.ts

@@ -8,6 +8,9 @@ import { EntryType } from '../types';
 import { AuthTag } from '../utils/authTag';
 import { RequestFilter } from '../utils/requestFilter';
 
+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;
@@ -24,48 +27,61 @@ const isTraceStorageQuery = (sql: string): boolean => {
   return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
 };
 
-export const QueryWatcher: ITraceWatcher = Object.freeze({
+const emit = (query: string, params: unknown[], duration: number, connection = 'default'): void => {
+  if (_storage === null || _config === null) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_config.ignoreRoutes)) 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 => {
-      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);
+      emit(query, params, duration);
     };
 
     (
@@ -75,6 +91,8 @@ export const QueryWatcher: ITraceWatcher = Object.freeze({
     ).onAfterQuery?.(handler);
 
     return () => {
+      _storage = null;
+      _config = null;
       (
         db as {
           offAfterQuery?: (h: (sql: string, params: unknown[], duration: number) => void) => void;