@zintrust/trace 1.5.2 → 1.6.1

package/src/register.ts

@@ -199,344 +199,461 @@ const buildTraceRedactionOverrides = (input: {
     : undefined;
 };
 
-const core = (await importCore()) as CoreApi;
-const Env = core.Env;
-const startupOverrides = await resolveTraceStartupOverrides(core);
+type TraceEnvApi = NonNullable<CoreApi['Env']>;
+
+type TraceEnvValues = {
+  connectionRaw: string;
+  observeConnectionRaw: string;
+  pruneAfterHoursRaw: string;
+  slowQueryThresholdRaw: string;
+  logMinLevelRaw: string;
+  traceProxyRaw: string;
+  traceProxyUrlRaw: string;
+  traceProxyPathRaw: string;
+  traceProxyKeyIdRaw: string;
+  traceProxySecretRaw: string;
+  traceProxyTimeoutRaw: string;
+  traceServiceTagRaw: string;
+  appNameRaw: string;
+  appKeyRaw: string;
+  captureCachePayloadsRaw: string;
+  captureQueryBindingsRaw: string;
+  contentDispatchDriverRaw: string;
+  contentDispatchQueueRaw: string;
+  contentDispatchEnqueueTimeoutRaw: string;
+  contentDispatchWorkerEnabledRaw: string;
+  contentDispatchWorkerIntervalRaw: string;
+  contentDispatchWorkerDurationRaw: string;
+  contentDispatchWorkerConcurrencyRaw: string;
+  redactionKeys?: string[];
+  redactionHeaders?: string[];
+  redactionBody?: string[];
+  redactionQuery?: string[];
+};
 
-if (!traceAlreadyInitialized && Env) {
-  const enabled = startupOverrides?.enabled === true || Env.getBool('TRACE_ENABLED', false);
+const readTraceEnvValues = (Env: TraceEnvApi): TraceEnvValues => {
+  return {
+    connectionRaw: Env.get('TRACE_DB_CONNECTION', '').trim(),
+    observeConnectionRaw: Env.get('TRACE_QUERY_CONNECTION', '').trim(),
+    pruneAfterHoursRaw: Env.get('TRACE_PRUNE_HOURS', '').trim(),
+    slowQueryThresholdRaw: Env.get('TRACE_SLOW_QUERY_MS', '').trim(),
+    logMinLevelRaw: Env.get('TRACE_LOG_LEVEL', '').trim(),
+    traceProxyRaw: Env.get('TRACE_PROXY', '').trim(),
+    traceProxyUrlRaw: Env.get('TRACE_PROXY_URL', '').trim(),
+    traceProxyPathRaw: Env.get('TRACE_PROXY_PATH', '').trim(),
+    traceProxyKeyIdRaw: Env.get('TRACE_PROXY_KEY_ID', '').trim(),
+    traceProxySecretRaw: Env.get('TRACE_PROXY_SECRET', '').trim(),
+    traceProxyTimeoutRaw: Env.get('TRACE_PROXY_TIMEOUT_MS', '').trim(),
+    traceServiceTagRaw: Env.get('TRACE_SERVICE_TAG', '').trim(),
+    appNameRaw: Env.get('APP_NAME', '').trim(),
+    appKeyRaw: Env.get('APP_KEY', '').trim(),
+    captureCachePayloadsRaw: Env.get('TRACE_CACHE_PAYLOADS', '').trim(),
+    captureQueryBindingsRaw: Env.get('TRACE_QUERY_BINDINGS', '').trim(),
+    contentDispatchDriverRaw: Env.get('TRACE_CONTENT_QUEUE_DRIVER', '').trim(),
+    contentDispatchQueueRaw: Env.get('TRACE_CONTENT_QUEUE_NAME', '').trim(),
+    contentDispatchEnqueueTimeoutRaw: Env.get('TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS', '').trim(),
+    contentDispatchWorkerEnabledRaw: Env.get('TRACE_CONTENT_QUEUE_WORKER_ENABLED', '').trim(),
+    contentDispatchWorkerIntervalRaw: Env.get('TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS', '').trim(),
+    contentDispatchWorkerDurationRaw: Env.get('TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS', '').trim(),
+    contentDispatchWorkerConcurrencyRaw: Env.get('TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY', '').trim(),
+    redactionKeys: parseEnvList(Env.get('TRACE_REDACT_KEYS', '')),
+    redactionHeaders: parseEnvList(Env.get('TRACE_REDACT_HEADERS', '')),
+    redactionBody: parseEnvList(Env.get('TRACE_REDACT_BODY', '')),
+    redactionQuery: parseEnvList(Env.get('TRACE_REDACT_QUERY', '')),
+  };
+};
 
-  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 traceProxyRaw = Env.get('TRACE_PROXY', '').trim();
-    const traceProxyUrlRaw = Env.get('TRACE_PROXY_URL', '').trim();
-    const traceProxyPathRaw = Env.get('TRACE_PROXY_PATH', '').trim();
-    const traceProxyKeyIdRaw = Env.get('TRACE_PROXY_KEY_ID', '').trim();
-    const traceProxySecretRaw = Env.get('TRACE_PROXY_SECRET', '').trim();
-    const traceProxyTimeoutRaw = Env.get('TRACE_PROXY_TIMEOUT_MS', '').trim();
-    const traceServiceTagRaw = Env.get('TRACE_SERVICE_TAG', '').trim();
-    const appNameRaw = Env.get('APP_NAME', '').trim();
-    const appKeyRaw = Env.get('APP_KEY', '').trim();
-    const captureCachePayloadsRaw = Env.get('TRACE_CACHE_PAYLOADS', '').trim();
-    const captureQueryBindingsRaw = Env.get('TRACE_QUERY_BINDINGS', '').trim();
-    const contentDispatchDriverRaw = Env.get('TRACE_CONTENT_QUEUE_DRIVER', '').trim();
-    const contentDispatchQueueRaw = Env.get('TRACE_CONTENT_QUEUE_NAME', '').trim();
-    const contentDispatchEnqueueTimeoutRaw = Env.get(
-      'TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS',
-      ''
-    ).trim();
-    const contentDispatchWorkerEnabledRaw = Env.get(
-      'TRACE_CONTENT_QUEUE_WORKER_ENABLED',
-      ''
-    ).trim();
-    const contentDispatchWorkerIntervalRaw = Env.get(
-      'TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS',
-      ''
-    ).trim();
-    const contentDispatchWorkerDurationRaw = Env.get(
-      'TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS',
-      ''
-    ).trim();
-    const contentDispatchWorkerConcurrencyRaw = Env.get(
-      'TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY',
-      ''
-    ).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
-        : 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 captureCachePayloads =
-      parseEnvBool(captureCachePayloadsRaw) ?? startupOverrides?.captureCachePayloads;
-    const captureQueryBindings =
-      parseEnvBool(captureQueryBindingsRaw) ?? startupOverrides?.captureQueryBindings;
-    const traceProxyEnabled = parseEnvBool(traceProxyRaw) ?? startupOverrides?.proxy?.enabled;
-    const traceProxyUrl = traceProxyUrlRaw === '' ? startupOverrides?.proxy?.url : traceProxyUrlRaw;
-    const traceProxyPath =
-      traceProxyPathRaw === '' ? startupOverrides?.proxy?.path : traceProxyPathRaw;
-    const traceProxyKeyId =
-      traceProxyKeyIdRaw === ''
-        ? (startupOverrides?.proxy?.keyId ?? appNameRaw)
-        : traceProxyKeyIdRaw;
-    const traceProxySecret =
-      traceProxySecretRaw === ''
-        ? (startupOverrides?.proxy?.secret ?? appKeyRaw)
-        : traceProxySecretRaw;
-    const traceProxyTimeout =
-      traceProxyTimeoutRaw === ''
-        ? startupOverrides?.proxy?.timeoutMs
-        : Number.parseInt(traceProxyTimeoutRaw, 10);
-    const traceServiceTag =
-      traceServiceTagRaw === ''
-        ? (startupOverrides?.serviceTag ?? appNameRaw).trim() || undefined
-        : traceServiceTagRaw;
-    const contentDispatchDriver =
-      contentDispatchDriverRaw === ''
-        ? startupOverrides?.contentDispatch?.driver
-        : contentDispatchDriverRaw;
-    const contentDispatchQueueName =
-      contentDispatchQueueRaw === ''
-        ? startupOverrides?.contentDispatch?.queueName
-        : contentDispatchQueueRaw;
-    const contentDispatchEnqueueTimeout =
-      contentDispatchEnqueueTimeoutRaw === ''
-        ? startupOverrides?.contentDispatch?.enqueueTimeoutMs
-        : Number.parseInt(contentDispatchEnqueueTimeoutRaw, 10);
-    const contentDispatchWorkerEnabled =
-      parseEnvBool(contentDispatchWorkerEnabledRaw) ??
-      startupOverrides?.contentDispatch?.worker?.enabled;
-    const contentDispatchWorkerInterval =
-      contentDispatchWorkerIntervalRaw === ''
-        ? startupOverrides?.contentDispatch?.worker?.intervalMs
-        : Number.parseInt(contentDispatchWorkerIntervalRaw, 10);
-    const contentDispatchWorkerDuration =
-      contentDispatchWorkerDurationRaw === ''
-        ? startupOverrides?.contentDispatch?.worker?.maxDurationMs
-        : Number.parseInt(contentDispatchWorkerDurationRaw, 10);
-    const contentDispatchWorkerConcurrency =
-      contentDispatchWorkerConcurrencyRaw === ''
-        ? startupOverrides?.contentDispatch?.worker?.concurrency
-        : Number.parseInt(contentDispatchWorkerConcurrencyRaw, 10);
-    const redaction = buildTraceRedactionOverrides({
-      startupOverrides,
-      redactionBody,
-      redactionHeaders,
-      redactionKeys,
-      redactionQuery,
-    });
-    const defaultContentDispatch = TraceConfig.defaults().contentDispatch;
-    const startupContentDispatch = startupOverrides?.contentDispatch;
-    const startupContentDispatchWorker = startupContentDispatch?.worker;
-
-    const config = TraceConfig.merge({
-      ...startupOverrides,
-      enabled,
-      connection,
-      observeConnection,
-      ...(typeof traceServiceTag === 'string' && traceServiceTag !== ''
-        ? { serviceTag: traceServiceTag }
-        : {}),
-      proxy: {
-        ...TraceConfig.defaults().proxy,
-        ...startupOverrides?.proxy,
-        ...(typeof traceProxyEnabled === 'boolean' ? { enabled: traceProxyEnabled } : {}),
-        ...(typeof traceProxyUrl === 'string' && traceProxyUrl !== ''
-          ? { url: traceProxyUrl }
-          : {}),
-        ...(typeof traceProxyPath === 'string' && traceProxyPath !== ''
-          ? { path: traceProxyPath }
-          : {}),
-        ...(typeof traceProxyKeyId === 'string' && traceProxyKeyId !== ''
-          ? { keyId: traceProxyKeyId }
-          : {}),
-        ...(typeof traceProxySecret === 'string' && traceProxySecret !== ''
-          ? { secret: traceProxySecret }
-          : {}),
-        ...(typeof traceProxyTimeout === 'number' && Number.isFinite(traceProxyTimeout)
-          ? { timeoutMs: traceProxyTimeout }
-          : {}),
-      },
-      ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
-        ? { pruneAfterHours }
-        : {}),
-      ...(typeof slowQueryThreshold === 'number' && Number.isFinite(slowQueryThreshold)
-        ? { slowQueryThreshold }
-        : {}),
-      ...(typeof captureCachePayloads === 'boolean' ? { captureCachePayloads } : {}),
-      ...(typeof captureQueryBindings === 'boolean' ? { captureQueryBindings } : {}),
-      contentDispatch: {
-        ...defaultContentDispatch,
-        ...startupContentDispatch,
-        ...(typeof contentDispatchDriver === 'string' && contentDispatchDriver !== ''
-          ? { driver: contentDispatchDriver }
-          : {}),
-        ...(typeof contentDispatchQueueName === 'string' && contentDispatchQueueName !== ''
-          ? { queueName: contentDispatchQueueName }
-          : {}),
-        ...(typeof contentDispatchEnqueueTimeout === 'number' &&
-        Number.isFinite(contentDispatchEnqueueTimeout)
-          ? { enqueueTimeoutMs: contentDispatchEnqueueTimeout }
-          : {}),
-        worker: {
-          ...defaultContentDispatch.worker,
-          ...startupContentDispatchWorker,
-          enabled:
-            typeof contentDispatchWorkerEnabled === 'boolean'
-              ? contentDispatchWorkerEnabled
-              : (startupContentDispatchWorker?.enabled ?? defaultContentDispatch.worker.enabled),
-          intervalMs:
-            typeof contentDispatchWorkerInterval === 'number' &&
-            Number.isFinite(contentDispatchWorkerInterval)
-              ? contentDispatchWorkerInterval
-              : (startupContentDispatchWorker?.intervalMs ??
-                defaultContentDispatch.worker.intervalMs),
-          maxDurationMs:
-            typeof contentDispatchWorkerDuration === 'number' &&
-            Number.isFinite(contentDispatchWorkerDuration)
-              ? contentDispatchWorkerDuration
-              : (startupContentDispatchWorker?.maxDurationMs ??
-                defaultContentDispatch.worker.maxDurationMs),
-          concurrency:
-            typeof contentDispatchWorkerConcurrency === 'number' &&
-            Number.isFinite(contentDispatchWorkerConcurrency)
-              ? contentDispatchWorkerConcurrency
-              : (startupContentDispatchWorker?.concurrency ??
-                defaultContentDispatch.worker.concurrency),
-        },
-      },
-      logMinLevel,
-      ...(redaction === undefined ? {} : { redaction }),
-    });
-
-    const resolvedConnectionName = resolveTraceConnectionName(Env, config.connection);
-    const resolvedObservedConnectionName = resolveObservedConnectionName(
-      Env,
-      config.observeConnection,
-      resolvedConnectionName
-    );
-    globalTraceRegisterState.__zintrust_system_trace_connection_name__ = resolvedConnectionName;
-    globalTraceRegisterState.__zintrust_system_trace_observe_connection_name__ =
-      resolvedObservedConnectionName;
-    const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
-    const observedDb = core.useDatabase?.(undefined, resolvedObservedConnectionName);
+const resolveStringOverride = (rawValue: string, fallback: string | undefined): string | undefined => {
+  return rawValue === '' ? fallback : rawValue;
+};
 
-    assertTraceConnectionResolved(core, storageDb, {
-      connectionName: resolvedConnectionName,
-      envKey: 'TRACE_DB_CONNECTION',
-    });
-    assertTraceConnectionResolved(core, observedDb, {
-      connectionName: resolvedObservedConnectionName,
-      envKey: 'TRACE_QUERY_CONNECTION',
-    });
-    await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
-
-    const resolvedStorage = config.proxy.enabled
-      ? ProxyTraceStorage.create({
-          baseUrl: config.proxy.url ?? '',
-          path: config.proxy.path,
-          keyId: config.proxy.keyId ?? '',
-          secret: config.proxy.secret ?? '',
-          timeoutMs: config.proxy.timeoutMs,
-        })
-      : TraceStorage.resolveStorage(storageDb);
-
-    const storage = TraceWriteDiagnostics.wrapStorage(
-      TraceContentBudget.wrapStorage(
-        TraceContentRedaction.wrapStorage(
-          TraceEntryFiltering.wrapStorage(
-            TraceServiceTag.wrapStorage(resolvedStorage, config),
-            config
-          ),
-          config.redaction
-        ),
-        config
+const resolveNumberOverride = (rawValue: string, fallback: number | undefined): number | undefined => {
+  return rawValue === '' ? fallback : Number.parseInt(rawValue, 10);
+};
+
+const resolveBooleanOverride = (
+  rawValue: string,
+  fallback: boolean | undefined
+): boolean | undefined => {
+  return parseEnvBool(rawValue) ?? fallback;
+};
+
+const resolveTraceProxyKeyId = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): string | undefined => {
+  return resolveStringOverride(values.traceProxyKeyIdRaw, startupOverrides?.proxy?.keyId ?? values.appNameRaw);
+};
+
+const resolveTraceProxySecret = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): string | undefined => {
+  return resolveStringOverride(values.traceProxySecretRaw, startupOverrides?.proxy?.secret ?? values.appKeyRaw);
+};
+
+const withStringProperty = (key: string, value: string | undefined): Record<string, string> => {
+  return typeof value === 'string' && value !== '' ? { [key]: value } : {};
+};
+
+const withNumberProperty = (key: string, value: number | undefined): Record<string, number> => {
+  return typeof value === 'number' && Number.isFinite(value) ? { [key]: value } : {};
+};
+
+const withBooleanProperty = (
+  key: string,
+  value: boolean | undefined
+): Record<string, boolean> => {
+  return typeof value === 'boolean' ? { [key]: value } : {};
+};
+
+const resolveTraceServiceTag = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): string | undefined => {
+  const fallback = (startupOverrides?.serviceTag ?? values.appNameRaw).trim() || undefined;
+  return resolveStringOverride(values.traceServiceTagRaw, fallback);
+};
+
+const resolveContentDispatchWorkerEnabled = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): boolean | undefined => {
+  return resolveBooleanOverride(
+    values.contentDispatchWorkerEnabledRaw,
+    startupOverrides?.contentDispatch?.worker?.enabled
+  );
+};
+
+const resolveContentDispatchWorkerInterval = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): number | undefined => {
+  return resolveNumberOverride(
+    values.contentDispatchWorkerIntervalRaw,
+    startupOverrides?.contentDispatch?.worker?.intervalMs
+  );
+};
+
+const resolveContentDispatchWorkerDuration = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): number | undefined => {
+  return resolveNumberOverride(
+    values.contentDispatchWorkerDurationRaw,
+    startupOverrides?.contentDispatch?.worker?.maxDurationMs
+  );
+};
+
+const resolveContentDispatchWorkerConcurrency = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): number | undefined => {
+  return resolveNumberOverride(
+    values.contentDispatchWorkerConcurrencyRaw,
+    startupOverrides?.contentDispatch?.worker?.concurrency
+  );
+};
+
+const buildTraceContentDispatchWorkerConfig = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): NonNullable<NonNullable<TraceConfigOverrides['contentDispatch']>['worker']> => {
+  const defaultWorker = TraceConfig.defaults().contentDispatch.worker;
+  const startupWorker = startupOverrides?.contentDispatch?.worker;
+  const contentDispatchWorkerEnabled = resolveContentDispatchWorkerEnabled(startupOverrides, values);
+  const contentDispatchWorkerInterval = resolveContentDispatchWorkerInterval(startupOverrides, values);
+  const contentDispatchWorkerDuration = resolveContentDispatchWorkerDuration(startupOverrides, values);
+  const contentDispatchWorkerConcurrency = resolveContentDispatchWorkerConcurrency(
+    startupOverrides,
+    values
+  );
+
+  return {
+    ...defaultWorker,
+    ...startupWorker,
+    enabled: contentDispatchWorkerEnabled ?? startupWorker?.enabled ?? defaultWorker.enabled,
+    intervalMs: contentDispatchWorkerInterval ?? startupWorker?.intervalMs ?? defaultWorker.intervalMs,
+    maxDurationMs:
+      contentDispatchWorkerDuration ?? startupWorker?.maxDurationMs ?? defaultWorker.maxDurationMs,
+    concurrency:
+      contentDispatchWorkerConcurrency ?? startupWorker?.concurrency ?? defaultWorker.concurrency,
+  };
+};
+
+const buildTraceProxyConfig = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): TraceConfigOverrides['proxy'] => {
+  const traceProxyEnabled = resolveBooleanOverride(values.traceProxyRaw, startupOverrides?.proxy?.enabled);
+  const traceProxyUrl = resolveStringOverride(values.traceProxyUrlRaw, startupOverrides?.proxy?.url);
+  const traceProxyPath = resolveStringOverride(values.traceProxyPathRaw, startupOverrides?.proxy?.path);
+  const traceProxyKeyId = resolveTraceProxyKeyId(startupOverrides, values);
+  const traceProxySecret = resolveTraceProxySecret(startupOverrides, values);
+  const traceProxyTimeout = resolveNumberOverride(
+    values.traceProxyTimeoutRaw,
+    startupOverrides?.proxy?.timeoutMs
+  );
+
+  return {
+    ...TraceConfig.defaults().proxy,
+    ...startupOverrides?.proxy,
+    ...withBooleanProperty('enabled', traceProxyEnabled),
+    ...withStringProperty('url', traceProxyUrl),
+    ...withStringProperty('path', traceProxyPath),
+    ...withStringProperty('keyId', traceProxyKeyId),
+    ...withStringProperty('secret', traceProxySecret),
+    ...withNumberProperty('timeoutMs', traceProxyTimeout),
+  };
+};
+
+const buildTraceContentDispatchConfig = (
+  startupOverrides: TraceConfigOverrides | undefined,
+  values: TraceEnvValues
+): NonNullable<TraceConfigOverrides['contentDispatch']> => {
+  const defaultContentDispatch = TraceConfig.defaults().contentDispatch;
+  const startupContentDispatch = startupOverrides?.contentDispatch;
+  const contentDispatchDriver = resolveStringOverride(
+    values.contentDispatchDriverRaw,
+    startupContentDispatch?.driver
+  );
+  const contentDispatchQueueName = resolveStringOverride(
+    values.contentDispatchQueueRaw,
+    startupContentDispatch?.queueName
+  );
+  const contentDispatchEnqueueTimeout = resolveNumberOverride(
+    values.contentDispatchEnqueueTimeoutRaw,
+    startupContentDispatch?.enqueueTimeoutMs
+  );
+
+  return {
+    ...defaultContentDispatch,
+    ...startupContentDispatch,
+    ...withStringProperty('driver', contentDispatchDriver),
+    ...withStringProperty('queueName', contentDispatchQueueName),
+    ...withNumberProperty('enqueueTimeoutMs', contentDispatchEnqueueTimeout),
+    worker: buildTraceContentDispatchWorkerConfig(startupOverrides, values),
+  };
+};
+
+const buildTraceRuntimeConfig = (
+  Env: TraceEnvApi,
+  startupOverrides: TraceConfigOverrides | undefined
+): ReturnType<typeof TraceConfig.merge> => {
+  const values = readTraceEnvValues(Env);
+  const enabled = startupOverrides?.enabled === true || Env.getBool('TRACE_ENABLED', false);
+  const connection = resolveStringOverride(values.connectionRaw, startupOverrides?.connection);
+  const observeConnection = resolveStringOverride(
+    values.observeConnectionRaw,
+    startupOverrides?.observeConnection
+  );
+  const pruneAfterHours = resolveNumberOverride(
+    values.pruneAfterHoursRaw,
+    startupOverrides?.pruneAfterHours
+  );
+  const slowQueryThreshold = resolveNumberOverride(
+    values.slowQueryThresholdRaw,
+    startupOverrides?.slowQueryThreshold
+  );
+  const logMinLevel = (
+    values.logMinLevelRaw === '' ? startupOverrides?.logMinLevel : values.logMinLevelRaw
+  ) as 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  const captureCachePayloads = resolveBooleanOverride(
+    values.captureCachePayloadsRaw,
+    startupOverrides?.captureCachePayloads
+  );
+  const captureQueryBindings = resolveBooleanOverride(
+    values.captureQueryBindingsRaw,
+    startupOverrides?.captureQueryBindings
+  );
+  const traceServiceTag = resolveTraceServiceTag(startupOverrides, values);
+  const redaction = buildTraceRedactionOverrides({
+    startupOverrides,
+    redactionBody: values.redactionBody,
+    redactionHeaders: values.redactionHeaders,
+    redactionKeys: values.redactionKeys,
+    redactionQuery: values.redactionQuery,
+  });
+
+  return TraceConfig.merge({
+    ...startupOverrides,
+    enabled,
+    connection,
+    observeConnection,
+    ...withStringProperty('serviceTag', traceServiceTag),
+    proxy: buildTraceProxyConfig(startupOverrides, values),
+    ...withNumberProperty('pruneAfterHours', pruneAfterHours),
+    ...withNumberProperty('slowQueryThreshold', slowQueryThreshold),
+    ...withBooleanProperty('captureCachePayloads', captureCachePayloads),
+    ...withBooleanProperty('captureQueryBindings', captureQueryBindings),
+    contentDispatch: buildTraceContentDispatchConfig(startupOverrides, values),
+    logMinLevel,
+    ...(redaction === undefined ? {} : { redaction }),
+  });
+};
+
+const createTraceWatcherArgs = async (
+  core: CoreApi,
+  Env: TraceEnvApi,
+  config: ReturnType<typeof TraceConfig.merge>
+): Promise<Pick<ITraceWatcherConfig, 'storage' | 'config' | 'db'>> => {
+  const resolvedConnectionName = resolveTraceConnectionName(Env, config.connection);
+  const resolvedObservedConnectionName = resolveObservedConnectionName(
+    Env,
+    config.observeConnection,
+    resolvedConnectionName
+  );
+  globalTraceRegisterState.__zintrust_system_trace_connection_name__ = resolvedConnectionName;
+  globalTraceRegisterState.__zintrust_system_trace_observe_connection_name__ =
+    resolvedObservedConnectionName;
+
+  const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
+  const observedDb = core.useDatabase?.(undefined, resolvedObservedConnectionName);
+
+  assertTraceConnectionResolved(core, storageDb, {
+    connectionName: resolvedConnectionName,
+    envKey: 'TRACE_DB_CONNECTION',
+  });
+  assertTraceConnectionResolved(core, observedDb, {
+    connectionName: resolvedObservedConnectionName,
+    envKey: 'TRACE_QUERY_CONNECTION',
+  });
+  await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
+
+  const resolvedStorage = config.proxy.enabled
+    ? ProxyTraceStorage.create({
+        baseUrl: config.proxy.url ?? '',
+        path: config.proxy.path,
+        keyId: config.proxy.keyId ?? '',
+        secret: config.proxy.secret ?? '',
+        timeoutMs: config.proxy.timeoutMs,
+      })
+    : TraceStorage.resolveStorage(storageDb);
+
+  const storage = TraceWriteDiagnostics.wrapStorage(
+    TraceContentBudget.wrapStorage(
+      TraceContentRedaction.wrapStorage(
+        TraceEntryFiltering.wrapStorage(TraceServiceTag.wrapStorage(resolvedStorage, config), config),
+        config.redaction
       ),
-      {
-        connectionName: resolvedConnectionName,
-        logger: core.Logger,
+      config
+    ),
+    {
+      connectionName: resolvedConnectionName,
+      logger: core.Logger,
+    }
+  );
+
+  return { storage, config, db: observedDb };
+};
+
+const registerTraceWatchers = async (
+  watcherArgs: Pick<ITraceWatcherConfig, 'storage' | 'config' | 'db'>
+): Promise<void> => {
+  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'),
+  ]);
+
+  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);
+};
+
+const activateTrace = async (
+  core: CoreApi,
+  Env: TraceEnvApi,
+  startupOverrides: TraceConfigOverrides | undefined
+): Promise<void> => {
+  const config = buildTraceRuntimeConfig(Env, startupOverrides);
+  if (!config.enabled) return;
+
+  const watcherArgs = await createTraceWatcherArgs(core, Env, config);
+
+  if (core.RequestContext) {
+    TraceContext.setRequestContextImpl(
+      core.RequestContext as {
+        current?: () => unknown;
+        peek?: () => unknown;
       }
     );
+  }
 
-    if (core.RequestContext) {
-      TraceContext.setRequestContextImpl(
-        core.RequestContext as {
-          current?: () => unknown;
-          peek?: () => unknown;
-        }
-      );
-    }
+  await registerTraceWatchers(watcherArgs);
+};
+
+const initializeTraceRegister = async (): Promise<void> => {
+  const core = (await importCore()) as CoreApi;
+  const Env = core.Env;
+  const startupOverrides = await resolveTraceStartupOverrides(core);
 
-    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);
+  if (!traceAlreadyInitialized && Env) {
+    await activateTrace(core, Env, startupOverrides);
+
+    return;
   }
-} else if (!traceAlreadyInitialized) {
-  // Running outside a ZinTrust project - skip init silently.
-  // eslint-disable-next-line no-console
-  console.warn('[trace] @zintrust/core not found - trace will not be activated.');
-}
+
+  if (!traceAlreadyInitialized) {
+    // Running outside a ZinTrust project - skip init silently.
+    // eslint-disable-next-line no-console
+    console.warn('[trace] @zintrust/core not found - trace will not be activated.');
+  }
+};
+
+export const registerTraceReady = initializeTraceRegister();