[SEA-NodeJS] Retarget kernel log level on runtime logger.setLevel()

Follow-up to the unified-logging wiring: a runtime `logger.setLevel(...)` now
retargets the kernel-side bridge too, not just the driver's own transports —
keeping kernel verbosity in lock-step with the driver's at runtime, not only at
connect.

- `IDBSQLLogger` gains an optional `onLevelChange(listener) => unsubscribe`;
  `DBSQLLogger` implements it (fires subscribers from `setLevel`, swallowing a
  throwing listener so it can't break level setting).
- `installKernelLogBridge` now returns an unsubscribe handle and, when both the
  logger can notify (`onLevelChange`) and the binding can retarget
  (`setKernelLogLevel`), subscribes to forward level changes to the kernel.
- `SeaBackend` stores the handle and drops it on `close()` (no stale listener;
  the process-global kernel sink follows the existing last-writer-wins model).

Backend-agnostic: `DBSQLLogger` never references the SEA binding — the SEA layer
subscribes via the interface. Loggers without `onLevelChange` keep the
connect-time level; older bindings without `setKernelLogLevel` simply don't
subscribe.

Verified: tsc / eslint / prettier clean; unit suite 1183 passing incl. new
`DBSQLLogger` level-subscription tests + `SeaLogging` runtime-retarget tests
(retarget, unsubscribe, no-notify logger, no-retarget binding). Live: with the
logger started at `warn`, a healthy SELECT logged 0 kernel lines; after
`logger.setLevel('debug')` mid-session the next SELECT logged 12
`[kernel databricks::sql::kernel]` lines — proving the kernel was retargeted.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/DBSQLLogger.ts

@@ -9,6 +9,10 @@ export default class DBSQLLogger implements IDBSQLLogger {
     file?: winston.transports.FileTransportInstance;
   };
 
+  // Subscribers notified on `setLevel(...)` — used by the SEA/kernel backend to
+  // keep the kernel-side log bridge's verbosity in lock-step with this logger.
+  private levelListeners: Array<(level: LogLevel) => void> = [];
+
   constructor({ level = LogLevel.info, filepath }: LoggerOptions = {}) {
     this.transports = {
       console: new winston.transports.Console({ handleExceptions: true, level }),
@@ -30,10 +34,28 @@ export default class DBSQLLogger implements IDBSQLLogger {
     return (this.transports.console.level as LogLevel) ?? LogLevel.info;
   }
 
+  onLevelChange(listener: (level: LogLevel) => void): () => void {
+    this.levelListeners.push(listener);
+    return () => {
+      const index = this.levelListeners.indexOf(listener);
+      if (index >= 0) {
+        this.levelListeners.splice(index, 1);
+      }
+    };
+  }
+
   setLevel(level: LogLevel) {
     this.transports.console.level = level;
     if (this.transports.file) {
       this.transports.file.level = level;
     }
+    for (const listener of this.levelListeners) {
+      // A subscriber must never break level setting for the rest.
+      try {
+        listener(level);
+      } catch {
+        // swallow — level-change notification is advisory
+      }
+    }
   }
 }

lib/contracts/IDBSQLLogger.ts

@@ -14,6 +14,16 @@ export default interface IDBSQLLogger {
    * bridge at its `info` default.
    */
   getLevel?(): LogLevel;
+
+  /**
+   * Optional: subscribe to runtime level changes. When implemented, the
+   * SEA/kernel backend subscribes so a runtime `setLevel(...)` retargets the
+   * kernel-side log bridge too (not just the driver's own transports) — keeping
+   * kernel verbosity in lock-step with the driver's. Returns an unsubscribe
+   * function. Loggers that don't implement it still get the connect-time level;
+   * only *runtime* retargeting of the kernel is unavailable.
+   */
+  onLevelChange?(listener: (level: LogLevel) => void): () => void;
 }
 
 export enum LogLevel {

lib/sea/SeaBackend.ts

@@ -71,6 +71,11 @@ export default class SeaBackend implements IBackend {
 
   private nativeOptions?: SeaNativeConnectionOptions;
 
+  // Drops the kernel-log level-change listener on close. No-op until connect()
+  // installs the bridge (and a no-op closure if the logger/binding can't
+  // retarget at runtime).
+  private kernelLogUnsubscribe: () => void = () => {};
+
   constructor(options: SeaBackendOptions) {
     this.context = options.context;
     this.binding = options.nativeBinding ?? getSeaNative();
@@ -90,7 +95,7 @@ export default class SeaBackend implements IBackend {
     // that predates the bridge (logging is advisory).
     const logger = this.context.getLogger();
     const kernelLogLevel = logger.getLevel?.() ?? LogLevel.info;
-    installKernelLogBridge(this.binding, logger, kernelLogLevel);
+    this.kernelLogUnsubscribe = installKernelLogBridge(this.binding, logger, kernelLogLevel);
 
     // Warn on the insecure combo: a `customCaCert` paired with
     // `checkServerCertificate: false` is almost always a mistake — verification
@@ -160,5 +165,11 @@ export default class SeaBackend implements IBackend {
     // No backend-level resources to release — each `SeaSessionBackend`
     // owns its own napi `Connection` lifecycle.
     this.nativeOptions = undefined;
+
+    // Stop retargeting the (process-global) kernel log level from this backend's
+    // logger; the kernel sink itself is process-global and is replaced by the
+    // next connect, matching the bridge's last-writer-wins model.
+    this.kernelLogUnsubscribe();
+    this.kernelLogUnsubscribe = () => {};
   }
 }

lib/sea/SeaLogging.ts

@@ -86,15 +86,24 @@ export function formatKernelLine(record: SeaNativeLogRecord): string {
  *   process the most recently connected client's logger receives kernel logs —
  *   mirroring the Python connector's `pyo3_log` model. Single-client apps, the
  *   common case, are unaffected.
+ * - **Runtime retargeting:** if `logger` exposes `onLevelChange` (as
+ *   `DBSQLLogger` does), the bridge subscribes so a later `logger.setLevel(...)`
+ *   also retargets the kernel-side filter via `setKernelLogLevel` — keeping
+ *   kernel verbosity in lock-step with the driver's at runtime, not just at
+ *   connect. Loggers without it still get the connect-time level.
  * - **Graceful on older bindings:** if the loaded `.node` predates
  *   `initKernelLogging`, this is a no-op (kernel logs simply stay unbridged)
  *   rather than a hard failure — logging is advisory.
+ *
+ * Returns an **unsubscribe** function the caller must invoke on teardown
+ * (`SeaBackend.close()`) to drop the level-change listener; it is a safe no-op
+ * when nothing was subscribed.
  */
-export function installKernelLogBridge(binding: SeaNativeBinding, logger: IDBSQLLogger, level: LogLevel): void {
+export function installKernelLogBridge(binding: SeaNativeBinding, logger: IDBSQLLogger, level: LogLevel): () => void {
   // Defensive: a stale/older binding without the bridge export must not break
   // connect() — logging is non-critical.
   if (typeof binding.initKernelLogging !== 'function') {
-    return;
+    return () => {};
   }
 
   const callback = (err: Error | null, records: Array<SeaNativeLogRecord>): void => {
@@ -107,4 +116,16 @@ export function installKernelLogBridge(binding: SeaNativeBinding, logger: IDBSQL
   };
 
   binding.initKernelLogging(callback, logLevelToKernelLevel(level));
+
+  // Keep the kernel's level in lock-step with runtime `logger.setLevel(...)`
+  // calls. Requires both a logger that notifies (`onLevelChange`) and a binding
+  // that can retarget (`setKernelLogLevel`); otherwise the connect-time level
+  // stands and there is nothing to unsubscribe.
+  if (typeof logger.onLevelChange === 'function' && typeof binding.setKernelLogLevel === 'function') {
+    return logger.onLevelChange((newLevel) => {
+      binding.setKernelLogLevel(logLevelToKernelLevel(newLevel));
+    });
+  }
+
+  return () => {};
 }

tests/e2e/sea/logging-e2e.test.ts

@@ -28,7 +28,10 @@ import { LogLevel } from '../../../lib/contracts/IDBSQLLogger';
 import config from '../utils/config';
 import { InternalConnectionOptions } from '../../../lib/contracts/InternalConnectionOptions';
 
-const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+const delay = (ms: number) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
 
 describe('SEA — unified kernel + driver logging', function unifiedLogging() {
   // Live-warehouse round-trip plus async log flush.

tests/unit/DBSQLLogger.test.ts

@@ -0,0 +1,62 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { expect } from 'chai';
+import DBSQLLogger from '../../lib/DBSQLLogger';
+import { LogLevel } from '../../lib/contracts/IDBSQLLogger';
+
+describe('DBSQLLogger level subscription', () => {
+  it('getLevel reflects the configured level', () => {
+    const logger = new DBSQLLogger({ level: LogLevel.warn });
+    expect(logger.getLevel()).to.equal(LogLevel.warn);
+  });
+
+  it('onLevelChange fires subscribers with the new level on setLevel', () => {
+    const logger = new DBSQLLogger({ level: LogLevel.info });
+    const seen: LogLevel[] = [];
+    logger.onLevelChange((level) => seen.push(level));
+
+    logger.setLevel(LogLevel.debug);
+    logger.setLevel(LogLevel.error);
+
+    expect(seen).to.deep.equal([LogLevel.debug, LogLevel.error]);
+    // setLevel still updates the logger's own level.
+    expect(logger.getLevel()).to.equal(LogLevel.error);
+  });
+
+  it('the returned unsubscribe stops further notifications', () => {
+    const logger = new DBSQLLogger({ level: LogLevel.info });
+    const seen: LogLevel[] = [];
+    const unsubscribe = logger.onLevelChange((level) => seen.push(level));
+
+    logger.setLevel(LogLevel.debug);
+    unsubscribe();
+    logger.setLevel(LogLevel.warn);
+
+    expect(seen).to.deep.equal([LogLevel.debug]);
+  });
+
+  it('a throwing subscriber does not break setLevel or other subscribers', () => {
+    const logger = new DBSQLLogger({ level: LogLevel.info });
+    const seen: LogLevel[] = [];
+    logger.onLevelChange(() => {
+      throw new Error('boom');
+    });
+    logger.onLevelChange((level) => seen.push(level));
+
+    expect(() => logger.setLevel(LogLevel.debug)).to.not.throw();
+    expect(seen).to.deep.equal([LogLevel.debug]);
+    expect(logger.getLevel()).to.equal(LogLevel.debug);
+  });
+});

tests/unit/sea/logging.test.ts

@@ -22,25 +22,55 @@ import {
 import { LogLevel } from '../../../lib/contracts/IDBSQLLogger';
 import { SeaNativeBinding, SeaNativeLogRecord } from '../../../lib/sea/SeaNativeLoader';
 
-// Minimal recording logger.
-function recordingLogger() {
+// Minimal recording logger. With `withLevelChange` (default) it exposes
+// `onLevelChange` + an `emitLevelChange` test helper to simulate a runtime
+// `setLevel(...)`; pass `false` to model a logger that can't notify.
+function recordingLogger(opts: { withLevelChange?: boolean } = {}) {
   const lines: Array<{ level: LogLevel; message: string }> = [];
-  return {
+  const listeners: Array<(level: LogLevel) => void> = [];
+  const logger = {
     lines,
     log(level: LogLevel, message: string) {
       lines.push({ level, message });
     },
+    // test-only: simulate the driver's `setLevel(...)` firing its subscribers
+    emitLevelChange(level: LogLevel) {
+      listeners.forEach((l) => l(level));
+    },
+  } as {
+    lines: Array<{ level: LogLevel; message: string }>;
+    log(level: LogLevel, message: string): void;
+    emitLevelChange(level: LogLevel): void;
+    onLevelChange?(listener: (level: LogLevel) => void): () => void;
   };
+  if (opts.withLevelChange !== false) {
+    logger.onLevelChange = (listener: (level: LogLevel) => void) => {
+      listeners.push(listener);
+      return () => {
+        const i = listeners.indexOf(listener);
+        if (i >= 0) listeners.splice(i, 1);
+      };
+    };
+  }
+  return logger;
 }
 
-// A binding stub that captures the registered bridge callback + level.
+// A binding stub that captures the registered bridge callback + initial level,
+// and records each `setKernelLogLevel` retarget.
 function captureBinding(overrides: Partial<Record<keyof SeaNativeBinding, unknown>> = {}) {
-  const captured: { cb?: (err: Error | null, records: Array<SeaNativeLogRecord>) => void; level?: string } = {};
+  const captured: {
+    cb?: (err: Error | null, records: Array<SeaNativeLogRecord>) => void;
+    level?: string;
+    levelChanges: string[];
+  } = { levelChanges: [] };
   const binding = {
     initKernelLogging: (cb: (err: Error | null, records: Array<SeaNativeLogRecord>) => void, level: string) => {
       captured.cb = cb;
       captured.level = level;
     },
+    setKernelLogLevel: (level: string) => {
+      captured.levelChanges.push(level);
+    },
     ...overrides,
   } as unknown as SeaNativeBinding;
   return { binding, captured };
@@ -119,4 +149,56 @@ describe('SeaLogging', () => {
       expect(() => installKernelLogBridge(binding, recordingLogger(), LogLevel.info)).to.not.throw();
     });
   });
+
+  describe('runtime level retargeting', () => {
+    it('retargets the kernel level when the logger level changes at runtime', () => {
+      const { binding, captured } = captureBinding();
+      const logger = recordingLogger();
+      installKernelLogBridge(binding, logger, LogLevel.warn);
+      expect(captured.level).to.equal('warn'); // connect-time level
+
+      logger.emitLevelChange(LogLevel.debug);
+      logger.emitLevelChange(LogLevel.error);
+      expect(captured.levelChanges).to.deep.equal(['debug', 'error']);
+    });
+
+    it('stops retargeting once the returned unsubscribe is called', () => {
+      const { binding, captured } = captureBinding();
+      const logger = recordingLogger();
+      const unsubscribe = installKernelLogBridge(binding, logger, LogLevel.info);
+
+      logger.emitLevelChange(LogLevel.debug);
+      unsubscribe();
+      logger.emitLevelChange(LogLevel.error); // after unsubscribe → ignored
+
+      expect(captured.levelChanges).to.deep.equal(['debug']);
+    });
+
+    it('does not subscribe when the logger cannot notify (no onLevelChange)', () => {
+      const { binding, captured } = captureBinding();
+      const logger = recordingLogger({ withLevelChange: false });
+      const unsubscribe = installKernelLogBridge(binding, logger, LogLevel.info);
+      logger.emitLevelChange(LogLevel.debug);
+      expect(captured.levelChanges).to.have.length(0);
+      expect(unsubscribe).to.be.a('function'); // safe no-op
+      expect(() => unsubscribe()).to.not.throw();
+    });
+
+    it('does not subscribe when the binding cannot retarget (no setKernelLogLevel)', () => {
+      // initKernelLogging present, setKernelLogLevel absent (partial/older binding).
+      const captured: { installed: boolean } = { installed: false };
+      const binding = {
+        initKernelLogging: () => {
+          captured.installed = true;
+        },
+      } as unknown as SeaNativeBinding;
+      const logger = recordingLogger();
+      const unsubscribe = installKernelLogBridge(binding, logger, LogLevel.info);
+      expect(captured.installed).to.equal(true);
+      expect(() => {
+        logger.emitLevelChange(LogLevel.debug);
+        unsubscribe();
+      }).to.not.throw();
+    });
+  });
 });