@zintrust/trace 0.4.82 → 0.4.83

package/README.md

@@ -29,6 +29,7 @@ You can still import the package migrations manually if you prefer to keep them
 ```env
 TRACE_ENABLED=true
 TRACE_DB_CONNECTION=d1        # optional — omit to inherit DB_CONNECTION
+TRACE_QUERY_CONNECTION=main   # optional — app DB to observe for SQL traces
 TRACE_PRUNE_HOURS=24          # how long entries are kept (default: 24)
 TRACE_SLOW_QUERY_MS=100       # slow-query threshold in ms (default: 100)
 TRACE_LOG_LEVEL=info          # minimum log level captured (default: info)
@@ -77,6 +78,7 @@ import type { TraceConfigOverrides } from '@zintrust/trace';
 export default {
   enabled: Env.getBool('TRACE_ENABLED', false),
   connection: Env.get('TRACE_DB_CONNECTION', '') || undefined,
+  observeConnection: Env.get('TRACE_QUERY_CONNECTION', '') || undefined,
   pruneAfterHours: Env.getInt('TRACE_PRUNE_HOURS', 24),
   slowQueryThreshold: Env.getInt('TRACE_SLOW_QUERY_MS', 100),
   logMinLevel: Env.get('TRACE_LOG_LEVEL', 'info') as TraceConfigOverrides['logMinLevel'],
@@ -102,6 +104,10 @@ export default {
 
 All include/exclude matching is contains-based, so a term like `report` matches `/reports/daily`, `monthly-report`, or any other trace content containing that fragment.
 
+When trace storage lives on a different connection than your application data, keep `TRACE_DB_CONNECTION` pointed at the trace tables and set `TRACE_QUERY_CONNECTION` to the app connection you want SQL traces to observe. If you omit `TRACE_QUERY_CONNECTION`, trace automatically falls back to the main `DB_CONNECTION` whenever the storage connection is different.
+
+When ZinTrust proxy runtimes also have trace enabled, proxy-executed SQL and SMTP operations are traced at the proxy boundary too. That means MySQL, PostgreSQL, SQL Server, and D1 proxy requests can still record the final SQL plus bound values, and the SMTP proxy can persist rendered mail text and HTML, even when the consumer application is talking to the proxy rather than executing the transport locally.
+
 ### 3. Mount the dashboard
 
 Register the dashboard explicitly in your route file when you want the UI. Restrict access with middleware — the trace does **not** apply auth automatically.

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.82",
-  "buildDate": "2026-04-08T15:23:56.210Z",
+  "version": "0.4.83",
+  "buildDate": "2026-04-08T17:13:19.081Z",
   "buildEnvironment": {
     "node": "v22.22.1",
     "platform": "darwin",
     "arch": "arm64"
   },
   "git": {
-    "commit": "54ac1e60",
+    "commit": "3c792064",
     "branch": "release"
   },
   "package": {
@@ -23,7 +23,7 @@
   "files": {
     "build-manifest.json": {
       "size": 14439,
-      "sha256": "b94e2cbd290c3992dabf8673fba6a501186ebe5386ee6bd2686a42f750881d00"
+      "sha256": "dab00c1ade5c0b5fe2b10b5eeeae31dfd9a017f198794e18e7c2b69cfb5560d8"
     },
     "cli-register.d.ts": {
       "size": 255,
@@ -38,8 +38,8 @@
       "sha256": "b034cbef0c71fb868071363624ef7a9f8d7acc20f8be8c895dd5db5a75e81f37"
     },
     "config.js": {
-      "size": 5927,
-      "sha256": "24f446c25ca4aae4ebc48ab54824c46e2042f1afbf41dd88b769fde4dced5886"
+      "size": 5961,
+      "sha256": "1402cf8ad7c850da99e429c8c937385b7b5cf401fa3714d972d4e6bd94f1663e"
     },
     "context.d.ts": {
       "size": 596,
@@ -79,7 +79,7 @@
     },
     "index.js": {
       "size": 3255,
-      "sha256": "ab97f252e49aa760657c10b96ea3fc0857d626c128d70cbb423cf6b72d6a67fb"
+      "sha256": "a293d38a9e56a2ab802f99143eb1eaebb18f854e610f29bc95878746ffe26326"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -134,8 +134,8 @@
       "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
     },
     "register.js": {
-      "size": 11496,
-      "sha256": "46a85cc9e9fd14a48c66c0cdf348a84608ffc628e731c0d2cc129fc38d1fa9b6"
+      "size": 12522,
+      "sha256": "66bccec7fac4d669702fa18e439788325d36ce17f228639005ffcde2cd968d70"
     },
     "storage/DebuggerStorage.d.ts": {
       "size": 517,
@@ -186,8 +186,8 @@
       "sha256": "d916e8e3abb1b1087f6b184851b0e6265e53380d7857b008e745d566aad15d44"
     },
     "types.d.ts": {
-      "size": 8416,
-      "sha256": "03c17d7f3759890062d36089311d3c464ff833d90c1048dd8c35a07a33388862"
+      "size": 8448,
+      "sha256": "de994120c04696e08afb428cff27a99fb2918f5c4277b8190b8fb3d36d139f0d"
     },
     "types.js": {
       "size": 696,
@@ -378,12 +378,12 @@
       "sha256": "b0ecc1df6a49dc8c5ffeb8dff0f1e3594ba016c4de3424dc8b5d7832e2f4cd11"
     },
     "watchers/QueryWatcher.d.ts": {
-      "size": 97,
-      "sha256": "6832a282b1658398264ede770d41c6aa86cb13625a3a87dac27fbaf7d2f7be6a"
+      "size": 240,
+      "sha256": "5d5046c65e5b683369c7709f1acd09b60aec3e7f44748fd1baeb35498836465b"
     },
     "watchers/QueryWatcher.js": {
-      "size": 2899,
-      "sha256": "a5bb991149846b67edf9658ce448172ec0b6f2f1bfb1cab25d9b2831a5e19a64"
+      "size": 2935,
+      "sha256": "577c6fec0282d2290db5c4b6c606b9b6ecdd64209af2b09f3205a15bf656bbef"
     },
     "watchers/RedisWatcher.d.ts": {
       "size": 294,

package/dist/config.js

@@ -76,6 +76,7 @@ const mergeWatchers = (base, override) => {
 const DEFAULTS = Object.freeze({
     enabled: false,
     connection: undefined,
+    observeConnection: undefined,
     pruneAfterHours: 24,
     ignoreRoutes: ['/trace', '/health', '/ping'],
     slowQueryThreshold: 100,

package/dist/register.js

@@ -64,6 +64,17 @@ const resolveTraceConnectionName = (env, configuredConnection) => {
     }
     return resolveDefaultConnection();
 };
+const resolveObservedConnectionName = (env, configuredObservedConnection, storageConnectionName) => {
+    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) => {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
@@ -146,6 +157,7 @@ if (!traceAlreadyInitialized && Env) {
     const enabled = startupOverrides?.enabled === true || Env.getBool('TRACE_ENABLED', false);
     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();
@@ -156,6 +168,7 @@ if (!traceAlreadyInitialized && Env) {
         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
             : Number.parseInt(pruneAfterHoursRaw, 10);
@@ -176,6 +189,7 @@ if (!traceAlreadyInitialized && Env) {
             ...startupOverrides,
             enabled,
             connection,
+            observeConnection,
             ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
                 ? { pruneAfterHours }
                 : {}),
@@ -188,9 +202,11 @@ if (!traceAlreadyInitialized && Env) {
             ...(redaction === undefined ? {} : { redaction }),
         });
         const resolvedConnectionName = resolveTraceConnectionName(Env, config.connection);
-        const db = core.useDatabase?.(undefined, resolvedConnectionName);
-        if (db) {
-            const storage = TraceWriteDiagnostics.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(db), config), config.redaction), {
+        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(storageDb), config), config.redaction), {
                 connectionName: resolvedConnectionName,
                 logger: core.Logger,
             });
@@ -219,7 +235,7 @@ if (!traceAlreadyInitialized && Env) {
                 import('./watchers/ViewWatcher.js'),
                 import('./watchers/HttpClientWatcher.js'),
             ]);
-            const watcherArgs = { storage, config, db };
+            const watcherArgs = { storage, config, db: observedDb };
             HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
             QueryWatcher.register(watcherArgs);
             LogWatcher.register(watcherArgs);

package/dist/types.d.ts

@@ -303,6 +303,7 @@ export type WatcherToggles = {
 export interface ITraceConfig {
     enabled: boolean;
     connection?: string;
+    observeConnection?: string;
     pruneAfterHours: number;
     ignoreRoutes: string[];
     slowQueryThreshold: number;

package/dist/watchers/QueryWatcher.d.ts

@@ -1,2 +1,6 @@
 import type { ITraceWatcher } from '../types';
-export declare const QueryWatcher: ITraceWatcher;
+declare const emit: (query: string, params: unknown[], duration: number, connection?: string) => void;
+export declare const QueryWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/QueryWatcher.js

@@ -6,6 +6,8 @@ import { TraceStorage } from '../storage/index.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
 import { RequestFilter } from '../utils/requestFilter.js';
+let _storage = null;
+let _config = null;
 const bindingsInterpolated = (sql, params) => {
     // Inline params for display only — safe, not for re-execution.
     let i = 0;
@@ -22,54 +24,64 @@ const isTraceStorageQuery = (sql) => {
     const normalized = sql.toLowerCase();
     return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
 };
+const emit = (query, params, duration, connection = 'default') => {
+    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 = {
+        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 = Object.freeze({
+    emit,
     register({ storage, config, db: injectedDb }) {
         if (config.watchers.query === false)
             return () => undefined;
         if (!injectedDb)
             return () => undefined; // no db available
+        _storage = storage;
+        _config = config;
         const db = injectedDb;
         const handler = (query, params, duration) => {
-            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 = {
-                connection: 'default',
-                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);
+            emit(query, params, duration);
         };
         db.onAfterQuery?.(handler);
         return () => {
+            _storage = null;
+            _config = null;
             db.offAfterQuery?.(handler);
         };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.82",
+  "version": "0.4.83",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",

package/src/config.ts

@@ -106,6 +106,7 @@ const mergeWatchers = (
 const DEFAULTS: ITraceConfig = Object.freeze({
   enabled: false,
   connection: undefined,
+  observeConnection: undefined,
   pruneAfterHours: 24,
   ignoreRoutes: ['/trace', '/health', '/ping'],
   slowQueryThreshold: 100,

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);
 };
@@ -206,6 +226,7 @@ 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();
@@ -217,6 +238,8 @@ if (!traceAlreadyInitialized && Env) {
     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
@@ -247,6 +270,7 @@ if (!traceAlreadyInitialized && Env) {
       ...startupOverrides,
       enabled,
       connection,
+      observeConnection,
       ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
         ? { pruneAfterHours }
         : {}),
@@ -260,12 +284,18 @@ if (!traceAlreadyInitialized && Env) {
     });
 
     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
         ),
         {
@@ -327,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

@@ -353,6 +353,7 @@ export type WatcherToggles = {
 export interface ITraceConfig {
   enabled: boolean;
   connection?: string;
+  observeConnection?: string;
   pruneAfterHours: number;
   ignoreRoutes: string[];
   slowQueryThreshold: number;

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,52 +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 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: 'default',
-        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);
+      emit(query, params, duration);
     };
 
     (
@@ -79,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;