@zintrust/trace 0.4.86 → 0.4.94

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.86",
-  "buildDate": "2026-04-09T08:08:55.865Z",
+  "version": "0.4.94",
+  "buildDate": "2026-04-11T09:24:47.024Z",
   "buildEnvironment": {
     "node": "v20.20.2",
     "platform": "linux",
     "arch": "x64"
   },
   "git": {
-    "commit": "a456e7ec",
+    "commit": "785d0351",
     "branch": "master"
   },
   "package": {
@@ -70,12 +70,12 @@
       "sha256": "2903901d8c0c5076118aa691727daa79be7abe87fdb393c5b389a2b1a8fce170"
     },
     "index.d.ts": {
-      "size": 2470,
-      "sha256": "99c28d43f79dbb2b372bf6a8b611841c131f59f5066702b499915b874e9fa2b8"
+      "size": 2537,
+      "sha256": "1707d26322dbad17f6bf85938ae6fe2477e84c7fed3333760ce8d6eadfaaffd2"
     },
     "index.js": {
-      "size": 3255,
-      "sha256": "faba7327d333f46340e9f6933510a88cb2439d14af9651cd8868a38782a44388"
+      "size": 3325,
+      "sha256": "0926788b00fc68f513ae20a508f2ef3c2f4e7e907fa32d70f146ce6e8b0ec812"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -130,8 +130,16 @@
       "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
     },
     "register.js": {
-      "size": 12522,
-      "sha256": "66bccec7fac4d669702fa18e439788325d36ce17f228639005ffcde2cd968d70"
+      "size": 14327,
+      "sha256": "efc9bb131b9eef7e81a6f85ea3338fd8ac74257f794aa0fc7c76efed636f99d8"
+    },
+    "storage/TraceContentBudget.d.ts": {
+      "size": 159,
+      "sha256": "d899a615e6cf2a5eea51f6200347cb81fbaae11979b801859f57135083aaf85b"
+    },
+    "storage/TraceContentBudget.js": {
+      "size": 4022,
+      "sha256": "4b1d4f0ad7da15caeaa1f9fe8b4edcd3000b0000c5bdc270601cd6db2eedce2e"
     },
     "storage/TraceContentRedaction.d.ts": {
       "size": 207,
@@ -330,8 +338,8 @@
       "sha256": "f3ddc5f8b58c6c86ac6b464dd48e5a55e79ab2bf2e735feacffc7480e4ccc0c4"
     },
     "watchers/LogWatcher.js": {
-      "size": 2026,
-      "sha256": "c5d2227cd76ce10162993ac31f474b2460cd41264c36f01b5130152f14a0ad21"
+      "size": 3126,
+      "sha256": "e0944661b48b682520d60ee9e98b3fa9f8ba4694743f134f98b04b8b2dd479e6"
     },
     "watchers/MailWatcher.d.ts": {
       "size": 244,
@@ -370,8 +378,8 @@
       "sha256": "5d5046c65e5b683369c7709f1acd09b60aec3e7f44748fd1baeb35498836465b"
     },
     "watchers/QueryWatcher.js": {
-      "size": 2935,
-      "sha256": "577c6fec0282d2290db5c4b6c606b9b6ecdd64209af2b09f3205a15bf656bbef"
+      "size": 3002,
+      "sha256": "c7131284e75ab2f0193597cdf3ef0aa7eab1a3872fe9193579a140a41fadb57e"
     },
     "watchers/RedisWatcher.d.ts": {
       "size": 294,

package/dist/index.d.ts

@@ -8,6 +8,7 @@
 export { TraceConfig } from './config';
 export { TraceStorage } from './storage';
 export type { ITraceStorage } from './storage';
+export { TraceContentBudget } from './storage/TraceContentBudget';
 export { TraceContentRedaction } from './storage/TraceContentRedaction';
 export { TraceContext } from './context';
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';

package/dist/index.js

@@ -14,6 +14,7 @@ export { TraceConfig } from './config.js';
 // Storage
 // ---------------------------------------------------------------------------
 export { TraceStorage } from './storage/index.js';
+export { TraceContentBudget } from './storage/TraceContentBudget.js';
 export { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 // ---------------------------------------------------------------------------
 // Context

package/dist/register.js

@@ -22,6 +22,7 @@
 import { TraceConfig } from './config.js';
 import { TraceContext } from './context.js';
 import { TraceStorage } from './storage/index.js';
+import { TraceContentBudget } from './storage/TraceContentBudget.js';
 import { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering.js';
 import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics.js';
@@ -39,6 +40,11 @@ const importCore = async () => {
         return {};
     }
 };
+const TRACE_REQUIRED_TABLES = [
+    'zin_trace_entries',
+    'zin_trace_entries_tags',
+    'zin_trace_monitoring',
+];
 const resolveRegisterMiddleware = () => {
     const globalMiddlewareRegistrarState = globalThis;
     return (middleware) => {
@@ -69,7 +75,7 @@ const resolveObservedConnectionName = (env, configuredObservedConnection, storag
         configuredObservedConnection.trim() !== '') {
         return resolveTraceConnectionName(env, configuredObservedConnection);
     }
-    const defaultConnectionName = resolveTraceConnectionName(env, undefined);
+    const defaultConnectionName = resolveTraceConnectionName(env);
     if (storageConnectionName !== defaultConnectionName) {
         return defaultConnectionName;
     }
@@ -150,6 +156,43 @@ const buildTraceRedactionOverrides = (input) => {
         ? redaction
         : undefined;
 };
+const createTraceConfigError = (coreApi, message, details) => {
+    if (coreApi.ErrorFactory?.createConfigError !== undefined) {
+        return coreApi.ErrorFactory.createConfigError(message, details);
+    }
+    const error = new globalThis.Error(message);
+    error.name = 'ConfigError';
+    error.code = 'CONFIG_ERROR';
+    error.statusCode = 500;
+    error.details = details;
+    return error;
+};
+function assertTraceConnectionResolved(coreApi, db, params) {
+    if (db !== undefined) {
+        return;
+    }
+    throw createTraceConfigError(coreApi, `Trace connection "${params.connectionName}" could not be resolved.`, {
+        connectionName: params.connectionName,
+        envKey: params.envKey,
+        hint: params.envKey === 'TRACE_DB_CONNECTION'
+            ? 'Configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.'
+            : 'Configure TRACE_QUERY_CONNECTION, or ensure DB_CONNECTION resolves to an existing database connection.',
+    });
+}
+const assertTraceStorageReady = async (coreApi, db, connectionName) => {
+    try {
+        await Promise.all(TRACE_REQUIRED_TABLES.map(async (table) => {
+            await db.queryOne(`SELECT 1 AS ok FROM ${table} LIMIT 1`, []);
+        }));
+    }
+    catch (error) {
+        throw createTraceConfigError(coreApi, `Trace storage connection "${connectionName}" is not ready. Create the database if needed and run \`zin migrate:trace\` before enabling TRACE_ENABLED.`, {
+            connectionName,
+            error,
+            requiredTables: [...TRACE_REQUIRED_TABLES],
+        });
+    }
+};
 const core = (await importCore());
 const Env = core.Env;
 const startupOverrides = resolveTraceStartupOverrides(core);
@@ -205,62 +248,65 @@ if (!traceAlreadyInitialized && Env) {
         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,
-            });
-            if (core.RequestContext) {
-                TraceContext.setRequestContextImpl(core.RequestContext);
-            }
-            const [{ HttpWatcher }, { QueryWatcher }, { LogWatcher }, { ExceptionWatcher }, { JobWatcher }, { CacheWatcher }, { ScheduleWatcher }, { MailWatcher }, { AuthWatcher }, { EventWatcher }, { ModelWatcher }, { NotificationWatcher }, { RedisWatcher }, { GateWatcher }, { MiddlewareWatcher }, { CommandWatcher }, { BatchWatcher }, { DumpWatcher }, { ViewWatcher }, { HttpClientWatcher },] = await Promise.all([
-                import('./watchers/HttpWatcher.js'),
-                import('./watchers/QueryWatcher.js'),
-                import('./watchers/LogWatcher.js'),
-                import('./watchers/ExceptionWatcher.js'),
-                import('./watchers/JobWatcher.js'),
-                import('./watchers/CacheWatcher.js'),
-                import('./watchers/ScheduleWatcher.js'),
-                import('./watchers/MailWatcher.js'),
-                import('./watchers/AuthWatcher.js'),
-                import('./watchers/EventWatcher.js'),
-                import('./watchers/ModelWatcher.js'),
-                import('./watchers/NotificationWatcher.js'),
-                import('./watchers/RedisWatcher.js'),
-                import('./watchers/GateWatcher.js'),
-                import('./watchers/MiddlewareWatcher.js'),
-                import('./watchers/CommandWatcher.js'),
-                import('./watchers/BatchWatcher.js'),
-                import('./watchers/DumpWatcher.js'),
-                import('./watchers/ViewWatcher.js'),
-                import('./watchers/HttpClientWatcher.js'),
-            ]);
-            const watcherArgs = { storage, config, db: observedDb };
-            HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
-            QueryWatcher.register(watcherArgs);
-            LogWatcher.register(watcherArgs);
-            ExceptionWatcher.register(watcherArgs);
-            JobWatcher.register(watcherArgs);
-            CacheWatcher.register(watcherArgs);
-            ScheduleWatcher.register(watcherArgs);
-            MailWatcher.register(watcherArgs);
-            AuthWatcher.register(watcherArgs);
-            EventWatcher.register(watcherArgs);
-            ModelWatcher.register(watcherArgs);
-            NotificationWatcher.register(watcherArgs);
-            RedisWatcher.register(watcherArgs);
-            GateWatcher.register(watcherArgs);
-            MiddlewareWatcher.register(watcherArgs);
-            CommandWatcher.register(watcherArgs);
-            BatchWatcher.register(watcherArgs);
-            DumpWatcher.register(watcherArgs);
-            ViewWatcher.register(watcherArgs);
-            HttpClientWatcher.register(watcherArgs);
-        }
-        else {
-            // eslint-disable-next-line no-console
-            console.warn('[trace] Could not resolve database connection - skipping init.');
+        assertTraceConnectionResolved(core, storageDb, {
+            connectionName: resolvedConnectionName,
+            envKey: 'TRACE_DB_CONNECTION',
+        });
+        assertTraceConnectionResolved(core, observedDb, {
+            connectionName: resolvedObservedConnectionName,
+            envKey: 'TRACE_QUERY_CONNECTION',
+        });
+        await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
+        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction)), {
+            connectionName: resolvedConnectionName,
+            logger: core.Logger,
+        });
+        if (core.RequestContext) {
+            TraceContext.setRequestContextImpl(core.RequestContext);
         }
+        const [{ HttpWatcher }, { QueryWatcher }, { LogWatcher }, { ExceptionWatcher }, { JobWatcher }, { CacheWatcher }, { ScheduleWatcher }, { MailWatcher }, { AuthWatcher }, { EventWatcher }, { ModelWatcher }, { NotificationWatcher }, { RedisWatcher }, { GateWatcher }, { MiddlewareWatcher }, { CommandWatcher }, { BatchWatcher }, { DumpWatcher }, { ViewWatcher }, { HttpClientWatcher },] = await Promise.all([
+            import('./watchers/HttpWatcher.js'),
+            import('./watchers/QueryWatcher.js'),
+            import('./watchers/LogWatcher.js'),
+            import('./watchers/ExceptionWatcher.js'),
+            import('./watchers/JobWatcher.js'),
+            import('./watchers/CacheWatcher.js'),
+            import('./watchers/ScheduleWatcher.js'),
+            import('./watchers/MailWatcher.js'),
+            import('./watchers/AuthWatcher.js'),
+            import('./watchers/EventWatcher.js'),
+            import('./watchers/ModelWatcher.js'),
+            import('./watchers/NotificationWatcher.js'),
+            import('./watchers/RedisWatcher.js'),
+            import('./watchers/GateWatcher.js'),
+            import('./watchers/MiddlewareWatcher.js'),
+            import('./watchers/CommandWatcher.js'),
+            import('./watchers/BatchWatcher.js'),
+            import('./watchers/DumpWatcher.js'),
+            import('./watchers/ViewWatcher.js'),
+            import('./watchers/HttpClientWatcher.js'),
+        ]);
+        const watcherArgs = { storage, config, db: observedDb };
+        HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
+        QueryWatcher.register(watcherArgs);
+        LogWatcher.register(watcherArgs);
+        ExceptionWatcher.register(watcherArgs);
+        JobWatcher.register(watcherArgs);
+        CacheWatcher.register(watcherArgs);
+        ScheduleWatcher.register(watcherArgs);
+        MailWatcher.register(watcherArgs);
+        AuthWatcher.register(watcherArgs);
+        EventWatcher.register(watcherArgs);
+        ModelWatcher.register(watcherArgs);
+        NotificationWatcher.register(watcherArgs);
+        RedisWatcher.register(watcherArgs);
+        GateWatcher.register(watcherArgs);
+        MiddlewareWatcher.register(watcherArgs);
+        CommandWatcher.register(watcherArgs);
+        BatchWatcher.register(watcherArgs);
+        DumpWatcher.register(watcherArgs);
+        ViewWatcher.register(watcherArgs);
+        HttpClientWatcher.register(watcherArgs);
     }
 }
 else if (!traceAlreadyInitialized) {

package/dist/storage/TraceContentBudget.d.ts

@@ -0,0 +1,4 @@
+import type { ITraceStorage } from '../types';
+export declare const TraceContentBudget: Readonly<{
+    wrapStorage(storage: ITraceStorage): ITraceStorage;
+}>;

package/dist/storage/TraceContentBudget.js

@@ -0,0 +1,114 @@
+const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024;
+const DEFAULT_MAX_STRING_BYTES = 16 * 1024;
+const DEFAULT_MAX_ARRAY_ITEMS = 25;
+const DEFAULT_MAX_OBJECT_ENTRIES = 40;
+const DEFAULT_MAX_DEPTH = 6;
+const DROPPED_FIELD_MESSAGE = '[trace] Value dropped because the field exceeded the trace storage size limit.';
+const COMPACTED_CONTENT_MESSAGE = '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+const encoder = new TextEncoder();
+const serializedSize = (value) => {
+    try {
+        return encoder.encode(JSON.stringify(value)).length;
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+};
+const describeValueType = (value) => {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    return typeof value;
+};
+const compactValue = (value, depth) => {
+    if (depth >= DEFAULT_MAX_DEPTH) {
+        return DROPPED_FIELD_MESSAGE;
+    }
+    if (typeof value === 'string') {
+        return serializedSize(value) > DEFAULT_MAX_STRING_BYTES ? DROPPED_FIELD_MESSAGE : value;
+    }
+    if (Array.isArray(value)) {
+        const next = value
+            .slice(0, DEFAULT_MAX_ARRAY_ITEMS)
+            .map((item) => compactValue(item, depth + 1));
+        if (value.length > DEFAULT_MAX_ARRAY_ITEMS) {
+            next.push(`[trace] ${String(value.length - DEFAULT_MAX_ARRAY_ITEMS)} additional items were dropped.`);
+        }
+        return next;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const entries = Object.entries(value);
+    const compactedEntries = entries
+        .slice(0, DEFAULT_MAX_OBJECT_ENTRIES)
+        .map(([key, entryValue]) => [key, compactValue(entryValue, depth + 1)]);
+    if (entries.length > DEFAULT_MAX_OBJECT_ENTRIES) {
+        compactedEntries.push([
+            '__traceNotice',
+            `[trace] ${String(entries.length - DEFAULT_MAX_OBJECT_ENTRIES)} additional fields were dropped.`,
+        ]);
+    }
+    return Object.fromEntries(compactedEntries);
+};
+const compactTopLevelObjectToBudget = (value) => {
+    const compacted = {
+        ...value,
+        __traceNotice: COMPACTED_CONTENT_MESSAGE,
+    };
+    const keysByDescendingSize = Object.keys(compacted)
+        .filter((key) => key !== '__traceNotice')
+        .sort((left, right) => serializedSize(compacted[right]) - serializedSize(compacted[left]));
+    for (const key of keysByDescendingSize) {
+        if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES)
+            break;
+        compacted[key] = DROPPED_FIELD_MESSAGE;
+    }
+    return compacted;
+};
+const fitContentToBudget = (content) => {
+    if (serializedSize(content) <= DEFAULT_MAX_ENTRY_BYTES) {
+        return content;
+    }
+    const compacted = compactValue(content, 0);
+    if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+        return compacted;
+    }
+    if (typeof compacted === 'object' && compacted !== null && !Array.isArray(compacted)) {
+        const topLevelCompacted = compactTopLevelObjectToBudget(compacted);
+        if (serializedSize(topLevelCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+            return topLevelCompacted;
+        }
+    }
+    return {
+        __traceNotice: COMPACTED_CONTENT_MESSAGE,
+        dropped: true,
+        valueType: describeValueType(content),
+    };
+};
+const fitEntryToBudget = (entry) => ({
+    ...entry,
+    content: fitContentToBudget(entry.content),
+});
+const fitPatchToBudget = (patch) => {
+    if (patch.content === undefined)
+        return patch;
+    return {
+        ...patch,
+        content: fitContentToBudget(patch.content),
+    };
+};
+export const TraceContentBudget = Object.freeze({
+    wrapStorage(storage) {
+        return Object.freeze({
+            ...storage,
+            writeEntry: async (entry) => {
+                await storage.writeEntry(fitEntryToBudget(entry));
+            },
+            updateEntry: async (uuid, patch) => {
+                await storage.updateEntry(uuid, fitPatchToBudget(patch));
+            },
+        });
+    },
+});

package/dist/watchers/LogWatcher.js

@@ -17,8 +17,37 @@ const TRACE_INFRASTRUCTURE_LOG_MESSAGES = new Set([
     '[MySQLProxyAdapter] Proxy request failed',
     '[trace] Trace storage write degraded',
 ]);
-const shouldSkipTraceInfrastructureLog = (message) => {
-    return TRACE_INFRASTRUCTURE_LOG_MESSAGES.has(message.trim());
+const TRACE_STORAGE_TABLE_NAMES = [
+    'zin_trace_entries',
+    'zin_trace_entries_tags',
+    'zin_trace_monitoring',
+];
+const isTraceStorageQuery = (sql) => {
+    const normalized = sql.toLowerCase();
+    return TRACE_STORAGE_TABLE_NAMES.some((tableName) => normalized.includes(tableName));
+};
+const extractSqlFromLog = (message, context) => {
+    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, context) => {
+    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, context) => {
+    return (TRACE_INFRASTRUCTURE_LOG_MESSAGES.has(message.trim()) ||
+        isTraceStorageQueryLog(message, context));
 };
 export const LogWatcher = Object.freeze({
     register({ storage, config }) {
@@ -34,7 +63,7 @@ export const LogWatcher = Object.freeze({
                 return;
             if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes))
                 return;
-            if (shouldSkipTraceInfrastructureLog(message))
+            if (shouldSkipTraceInfrastructureLog(message, context))
                 return;
             const content = {
                 level,

package/dist/watchers/QueryWatcher.js

@@ -22,7 +22,9 @@ const bindingsInterpolated = (sql, params) => {
 };
 const isTraceStorageQuery = (sql) => {
     const normalized = sql.toLowerCase();
-    return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
+    return (normalized.includes('zin_trace_entries') ||
+        normalized.includes('zin_trace_entries_tags') ||
+        normalized.includes('zin_trace_monitoring'));
 };
 const emit = (query, params, duration, connection = 'default') => {
     if (_storage === null || _config === null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.86",
+  "version": "0.4.94",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.84"
+    "@zintrust/core": "^0.4.93"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -18,6 +18,7 @@ export { TraceConfig } from './config';
 // ---------------------------------------------------------------------------
 export { TraceStorage } from './storage';
 export type { ITraceStorage } from './storage';
+export { TraceContentBudget } from './storage/TraceContentBudget';
 export { TraceContentRedaction } from './storage/TraceContentRedaction';
 
 // ---------------------------------------------------------------------------

package/src/register.ts

@@ -22,6 +22,7 @@
 import { TraceConfig } from './config';
 import { TraceContext } from './context';
 import { TraceStorage } from './storage';
+import { TraceContentBudget } from './storage/TraceContentBudget';
 import { TraceContentRedaction } from './storage/TraceContentRedaction';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering';
 import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics';
@@ -64,6 +65,9 @@ type CoreApi = {
   Logger?: {
     warn(message: string, context?: Record<string, unknown>): void;
   };
+  ErrorFactory?: {
+    createConfigError(message: string, details?: unknown): Error;
+  };
   StartupConfigFile?: {
     Trace?: string;
   };
@@ -72,6 +76,14 @@ type CoreApi = {
   };
 };
 
+type CoreDatabase = import('@zintrust/core').IDatabase;
+
+const TRACE_REQUIRED_TABLES = [
+  'zin_trace_entries',
+  'zin_trace_entries_tags',
+  'zin_trace_monitoring',
+] as const;
+
 type GlobalMiddlewareRegistrarState = {
   __zintrust_register_global_middleware__?: ITraceWatcherConfig['registerMiddleware'];
   __zintrust_pending_global_middlewares__?: Array<
@@ -125,7 +137,7 @@ const resolveObservedConnectionName = (
     return resolveTraceConnectionName(env, configuredObservedConnection);
   }
 
-  const defaultConnectionName = resolveTraceConnectionName(env, undefined);
+  const defaultConnectionName = resolveTraceConnectionName(env);
   if (storageConnectionName !== defaultConnectionName) {
     return defaultConnectionName;
   }
@@ -217,6 +229,71 @@ const buildTraceRedactionOverrides = (input: {
     : undefined;
 };
 
+const createTraceConfigError = (coreApi: CoreApi, message: string, details?: unknown): Error => {
+  if (coreApi.ErrorFactory?.createConfigError !== undefined) {
+    return coreApi.ErrorFactory.createConfigError(message, details);
+  }
+
+  const error = new globalThis.Error(message) as Error & {
+    code?: string;
+    details?: unknown;
+    name?: string;
+    statusCode?: number;
+  };
+  error.name = 'ConfigError';
+  error.code = 'CONFIG_ERROR';
+  error.statusCode = 500;
+  error.details = details;
+  return error;
+};
+
+function assertTraceConnectionResolved(
+  coreApi: CoreApi,
+  db: CoreDatabase | undefined,
+  params: { connectionName: string; envKey: 'TRACE_DB_CONNECTION' | 'TRACE_QUERY_CONNECTION' }
+): asserts db is CoreDatabase {
+  if (db !== undefined) {
+    return;
+  }
+
+  throw createTraceConfigError(
+    coreApi,
+    `Trace connection "${params.connectionName}" could not be resolved.`,
+    {
+      connectionName: params.connectionName,
+      envKey: params.envKey,
+      hint:
+        params.envKey === 'TRACE_DB_CONNECTION'
+          ? 'Configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.'
+          : 'Configure TRACE_QUERY_CONNECTION, or ensure DB_CONNECTION resolves to an existing database connection.',
+    }
+  );
+}
+
+const assertTraceStorageReady = async (
+  coreApi: CoreApi,
+  db: CoreDatabase,
+  connectionName: string
+): Promise<void> => {
+  try {
+    await Promise.all(
+      TRACE_REQUIRED_TABLES.map(async (table) => {
+        await db.queryOne(`SELECT 1 AS ok FROM ${table} LIMIT 1`, []);
+      })
+    );
+  } catch (error) {
+    throw createTraceConfigError(
+      coreApi,
+      `Trace storage connection "${connectionName}" is not ready. Create the database if needed and run \`zin migrate:trace\` before enabling TRACE_ENABLED.`,
+      {
+        connectionName,
+        error,
+        requiredTables: [...TRACE_REQUIRED_TABLES],
+      }
+    );
+  }
+};
+
 const core = (await importCore()) as CoreApi;
 const Env = core.Env;
 const startupOverrides = resolveTraceStartupOverrides(core);
@@ -292,98 +369,105 @@ if (!traceAlreadyInitialized && Env) {
     const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
     const observedDb = core.useDatabase?.(undefined, resolvedObservedConnectionName);
 
-    if (storageDb && observedDb) {
-      const storage = TraceWriteDiagnostics.wrapStorage(
+    assertTraceConnectionResolved(core, storageDb, {
+      connectionName: resolvedConnectionName,
+      envKey: 'TRACE_DB_CONNECTION',
+    });
+    assertTraceConnectionResolved(core, observedDb, {
+      connectionName: resolvedObservedConnectionName,
+      envKey: 'TRACE_QUERY_CONNECTION',
+    });
+    await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
+
+    const storage = TraceWriteDiagnostics.wrapStorage(
+      TraceContentBudget.wrapStorage(
         TraceContentRedaction.wrapStorage(
           TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config),
           config.redaction
-        ),
-        {
-          connectionName: resolvedConnectionName,
-          logger: core.Logger,
-        }
-      );
-
-      if (core.RequestContext) {
-        TraceContext.setRequestContextImpl(
-          core.RequestContext as {
-            current?: () => unknown;
-            peek?: () => unknown;
-          }
-        );
+        )
+      ),
+      {
+        connectionName: resolvedConnectionName,
+        logger: core.Logger,
       }
+    );
 
-      const [
-        { HttpWatcher },
-        { QueryWatcher },
-        { LogWatcher },
-        { ExceptionWatcher },
-        { JobWatcher },
-        { CacheWatcher },
-        { ScheduleWatcher },
-        { MailWatcher },
-        { AuthWatcher },
-        { EventWatcher },
-        { ModelWatcher },
-        { NotificationWatcher },
-        { RedisWatcher },
-        { GateWatcher },
-        { MiddlewareWatcher },
-        { CommandWatcher },
-        { BatchWatcher },
-        { DumpWatcher },
-        { ViewWatcher },
-        { HttpClientWatcher },
-      ] = await Promise.all([
-        import('./watchers/HttpWatcher'),
-        import('./watchers/QueryWatcher'),
-        import('./watchers/LogWatcher'),
-        import('./watchers/ExceptionWatcher'),
-        import('./watchers/JobWatcher'),
-        import('./watchers/CacheWatcher'),
-        import('./watchers/ScheduleWatcher'),
-        import('./watchers/MailWatcher'),
-        import('./watchers/AuthWatcher'),
-        import('./watchers/EventWatcher'),
-        import('./watchers/ModelWatcher'),
-        import('./watchers/NotificationWatcher'),
-        import('./watchers/RedisWatcher'),
-        import('./watchers/GateWatcher'),
-        import('./watchers/MiddlewareWatcher'),
-        import('./watchers/CommandWatcher'),
-        import('./watchers/BatchWatcher'),
-        import('./watchers/DumpWatcher'),
-        import('./watchers/ViewWatcher'),
-        import('./watchers/HttpClientWatcher'),
-      ]);
-
-      const watcherArgs = { storage, config, db: observedDb };
-
-      HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
-
-      QueryWatcher.register(watcherArgs);
-      LogWatcher.register(watcherArgs);
-      ExceptionWatcher.register(watcherArgs);
-      JobWatcher.register(watcherArgs);
-      CacheWatcher.register(watcherArgs);
-      ScheduleWatcher.register(watcherArgs);
-      MailWatcher.register(watcherArgs);
-      AuthWatcher.register(watcherArgs);
-      EventWatcher.register(watcherArgs);
-      ModelWatcher.register(watcherArgs);
-      NotificationWatcher.register(watcherArgs);
-      RedisWatcher.register(watcherArgs);
-      GateWatcher.register(watcherArgs);
-      MiddlewareWatcher.register(watcherArgs);
-      CommandWatcher.register(watcherArgs);
-      BatchWatcher.register(watcherArgs);
-      DumpWatcher.register(watcherArgs);
-      ViewWatcher.register(watcherArgs);
-      HttpClientWatcher.register(watcherArgs);
-    } else {
-      // eslint-disable-next-line no-console
-      console.warn('[trace] Could not resolve database connection - skipping init.');
+    if (core.RequestContext) {
+      TraceContext.setRequestContextImpl(
+        core.RequestContext as {
+          current?: () => unknown;
+          peek?: () => unknown;
+        }
+      );
     }
+
+    const [
+      { HttpWatcher },
+      { QueryWatcher },
+      { LogWatcher },
+      { ExceptionWatcher },
+      { JobWatcher },
+      { CacheWatcher },
+      { ScheduleWatcher },
+      { MailWatcher },
+      { AuthWatcher },
+      { EventWatcher },
+      { ModelWatcher },
+      { NotificationWatcher },
+      { RedisWatcher },
+      { GateWatcher },
+      { MiddlewareWatcher },
+      { CommandWatcher },
+      { BatchWatcher },
+      { DumpWatcher },
+      { ViewWatcher },
+      { HttpClientWatcher },
+    ] = await Promise.all([
+      import('./watchers/HttpWatcher'),
+      import('./watchers/QueryWatcher'),
+      import('./watchers/LogWatcher'),
+      import('./watchers/ExceptionWatcher'),
+      import('./watchers/JobWatcher'),
+      import('./watchers/CacheWatcher'),
+      import('./watchers/ScheduleWatcher'),
+      import('./watchers/MailWatcher'),
+      import('./watchers/AuthWatcher'),
+      import('./watchers/EventWatcher'),
+      import('./watchers/ModelWatcher'),
+      import('./watchers/NotificationWatcher'),
+      import('./watchers/RedisWatcher'),
+      import('./watchers/GateWatcher'),
+      import('./watchers/MiddlewareWatcher'),
+      import('./watchers/CommandWatcher'),
+      import('./watchers/BatchWatcher'),
+      import('./watchers/DumpWatcher'),
+      import('./watchers/ViewWatcher'),
+      import('./watchers/HttpClientWatcher'),
+    ]);
+
+    const watcherArgs = { storage, config, db: observedDb };
+
+    HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
+
+    QueryWatcher.register(watcherArgs);
+    LogWatcher.register(watcherArgs);
+    ExceptionWatcher.register(watcherArgs);
+    JobWatcher.register(watcherArgs);
+    CacheWatcher.register(watcherArgs);
+    ScheduleWatcher.register(watcherArgs);
+    MailWatcher.register(watcherArgs);
+    AuthWatcher.register(watcherArgs);
+    EventWatcher.register(watcherArgs);
+    ModelWatcher.register(watcherArgs);
+    NotificationWatcher.register(watcherArgs);
+    RedisWatcher.register(watcherArgs);
+    GateWatcher.register(watcherArgs);
+    MiddlewareWatcher.register(watcherArgs);
+    CommandWatcher.register(watcherArgs);
+    BatchWatcher.register(watcherArgs);
+    DumpWatcher.register(watcherArgs);
+    ViewWatcher.register(watcherArgs);
+    HttpClientWatcher.register(watcherArgs);
   }
 } else if (!traceAlreadyInitialized) {
   // Running outside a ZinTrust project - skip init silently.

package/src/storage/TraceContentBudget.ts

@@ -0,0 +1,145 @@
+import type { ITraceEntry, ITraceStorage } from '../types';
+
+const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024;
+const DEFAULT_MAX_STRING_BYTES = 16 * 1024;
+const DEFAULT_MAX_ARRAY_ITEMS = 25;
+const DEFAULT_MAX_OBJECT_ENTRIES = 40;
+const DEFAULT_MAX_DEPTH = 6;
+
+const DROPPED_FIELD_MESSAGE =
+  '[trace] Value dropped because the field exceeded the trace storage size limit.';
+const COMPACTED_CONTENT_MESSAGE =
+  '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+
+const encoder = new TextEncoder();
+
+const serializedSize = (value: unknown): number => {
+  try {
+    return encoder.encode(JSON.stringify(value)).length;
+  } catch {
+    return Number.MAX_SAFE_INTEGER;
+  }
+};
+
+const describeValueType = (value: unknown): string => {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+};
+
+const compactValue = (value: unknown, depth: number): unknown => {
+  if (depth >= DEFAULT_MAX_DEPTH) {
+    return DROPPED_FIELD_MESSAGE;
+  }
+
+  if (typeof value === 'string') {
+    return serializedSize(value) > DEFAULT_MAX_STRING_BYTES ? DROPPED_FIELD_MESSAGE : value;
+  }
+
+  if (Array.isArray(value)) {
+    const next = value
+      .slice(0, DEFAULT_MAX_ARRAY_ITEMS)
+      .map((item) => compactValue(item, depth + 1));
+
+    if (value.length > DEFAULT_MAX_ARRAY_ITEMS) {
+      next.push(
+        `[trace] ${String(value.length - DEFAULT_MAX_ARRAY_ITEMS)} additional items were dropped.`
+      );
+    }
+
+    return next;
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+
+  const entries = Object.entries(value);
+  const compactedEntries = entries
+    .slice(0, DEFAULT_MAX_OBJECT_ENTRIES)
+    .map(([key, entryValue]) => [key, compactValue(entryValue, depth + 1)]);
+
+  if (entries.length > DEFAULT_MAX_OBJECT_ENTRIES) {
+    compactedEntries.push([
+      '__traceNotice',
+      `[trace] ${String(entries.length - DEFAULT_MAX_OBJECT_ENTRIES)} additional fields were dropped.`,
+    ]);
+  }
+
+  return Object.fromEntries(compactedEntries);
+};
+
+const compactTopLevelObjectToBudget = (value: Record<string, unknown>): Record<string, unknown> => {
+  const compacted: Record<string, unknown> = {
+    ...value,
+    __traceNotice: COMPACTED_CONTENT_MESSAGE,
+  };
+
+  const keysByDescendingSize = Object.keys(compacted)
+    .filter((key) => key !== '__traceNotice')
+    .sort((left, right) => serializedSize(compacted[right]) - serializedSize(compacted[left]));
+
+  for (const key of keysByDescendingSize) {
+    if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) break;
+    compacted[key] = DROPPED_FIELD_MESSAGE;
+  }
+
+  return compacted;
+};
+
+const fitContentToBudget = (content: unknown): unknown => {
+  if (serializedSize(content) <= DEFAULT_MAX_ENTRY_BYTES) {
+    return content;
+  }
+
+  const compacted = compactValue(content, 0);
+  if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+    return compacted;
+  }
+
+  if (typeof compacted === 'object' && compacted !== null && !Array.isArray(compacted)) {
+    const topLevelCompacted = compactTopLevelObjectToBudget(compacted as Record<string, unknown>);
+    if (serializedSize(topLevelCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+      return topLevelCompacted;
+    }
+  }
+
+  return {
+    __traceNotice: COMPACTED_CONTENT_MESSAGE,
+    dropped: true,
+    valueType: describeValueType(content),
+  };
+};
+
+const fitEntryToBudget = (entry: ITraceEntry): ITraceEntry => ({
+  ...entry,
+  content: fitContentToBudget(entry.content),
+});
+
+const fitPatchToBudget = (
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+): Partial<Pick<ITraceEntry, 'content' | 'isLatest'>> => {
+  if (patch.content === undefined) return patch;
+
+  return {
+    ...patch,
+    content: fitContentToBudget(patch.content),
+  };
+};
+
+export const TraceContentBudget = Object.freeze({
+  wrapStorage(storage: ITraceStorage): ITraceStorage {
+    return Object.freeze({
+      ...storage,
+      writeEntry: async (entry: ITraceEntry): Promise<void> => {
+        await storage.writeEntry(fitEntryToBudget(entry));
+      },
+      updateEntry: async (
+        uuid: string,
+        patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+      ): Promise<void> => {
+        await storage.updateEntry(uuid, fitPatchToBudget(patch));
+      },
+    });
+  },
+});

package/src/watchers/LogWatcher.ts

@@ -21,8 +21,50 @@ const TRACE_INFRASTRUCTURE_LOG_MESSAGES = new Set<string>([
   '[trace] Trace storage write degraded',
 ]);
 
-const shouldSkipTraceInfrastructureLog = (message: string): boolean => {
-  return TRACE_INFRASTRUCTURE_LOG_MESSAGES.has(message.trim());
+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 => {
+  return (
+    TRACE_INFRASTRUCTURE_LOG_MESSAGES.has(message.trim()) ||
+    isTraceStorageQueryLog(message, context)
+  );
 };
 
 export const LogWatcher: ITraceWatcher = Object.freeze({
@@ -41,7 +83,7 @@ export const LogWatcher: ITraceWatcher = Object.freeze({
       (level: string, message: string, context?: Record<string, unknown>) => {
         if ((LEVEL_PRIORITY[level] ?? 0) < minPriority) return;
         if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes)) return;
-        if (shouldSkipTraceInfrastructureLog(message)) return;
+        if (shouldSkipTraceInfrastructureLog(message, context)) return;
 
         const content: LogContent = {
           level,

package/src/watchers/QueryWatcher.ts

@@ -24,7 +24,11 @@ const bindingsInterpolated = (sql: string, params: unknown[]): string => {
 
 const isTraceStorageQuery = (sql: string): boolean => {
   const normalized = sql.toLowerCase();
-  return normalized.includes('zin_trace_entries') || normalized.includes('zin_trace_monitoring');
+  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 => {