Forward kernel telemetry options

lib/DBSQLClient.ts

@@ -40,7 +40,7 @@ import TelemetryClientProvider from './telemetry/TelemetryClientProvider';
 import TelemetryEventEmitter from './telemetry/TelemetryEventEmitter';
 import MetricsAggregator from './telemetry/MetricsAggregator';
 import { DriverConfiguration, DRIVER_NAME, TelemetryEventType, DEFAULT_TELEMETRY_CONFIG } from './telemetry/types';
-import { safeEmit } from './telemetry/telemetryUtils';
+import { safeEmit, isTelemetryDisabledByEnv } from './telemetry/telemetryUtils';
 import driverVersion from './version';
 
 function prependSlash(str: string): string {
@@ -521,8 +521,10 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
    */
   private getLocaleName(): string {
     try {
-      // Try to get from environment variables
-      const lang = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || '';
+      // Try to get from environment variables. Use POSIX precedence
+      // (LC_ALL > LC_MESSAGES > LANG) so this matches the kernel path's
+      // getLocaleName and telemetry localeName stays backend-invariant.
+      const lang = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
       if (lang) {
         // LANG format is typically "en_US.UTF-8", extract "en_US"
         const match = lang.match(/^([a-z]{2}_[A-Z]{2})/);
@@ -729,7 +731,8 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
     // doesn't ship in the public `.d.ts`. Mirrors Python's `kwargs.get("use_kernel")`
     // pattern (see databricks-sql-python/src/databricks/sql/session.py).
     const internalOptions = options as ConnectionOptions & InternalConnectionOptions;
-    const backend = internalOptions.useKernel
+    const useKernel = internalOptions.useKernel === true;
+    const backend = useKernel
       ? new KernelBackend({ context: this })
       : new ThriftBackend({
           context: this,
@@ -763,7 +766,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
     // expecting to enable telemetry.
     const envKill = process.env.DATABRICKS_TELEMETRY_DISABLED;
     const trimmedEnvKill = typeof envKill === 'string' ? envKill.trim() : '';
-    const envDisabled = trimmedEnvKill.length > 0 && /^(1|true|yes|on)$/i.test(trimmedEnvKill);
+    const envDisabled = isTelemetryDisabledByEnv();
     // Surface the misconfiguration: an ops engineer who sees the var name and
     // tries to "set it to false to keep telemetry on" otherwise gets the
     // opposite of what they expect (the var is then silently ignored, runtime
@@ -777,7 +780,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
           `Telemetry remains controlled by the runtime config and feature flag.`,
       );
     }
-    if (this.config.telemetryEnabled && !envDisabled) {
+    if (!useKernel && this.config.telemetryEnabled && !envDisabled) {
       await this.initializeTelemetry();
     }
 

lib/kernel/KernelAuth.ts

@@ -12,11 +12,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import os from 'os';
 import { ConnectionOptions } from '../contracts/IDBSQLClient';
+import { ClientConfig } from '../contracts/IClientContext';
 import { InternalConnectionOptions } from '../contracts/InternalConnectionOptions';
+import IDBSQLLogger, { LogLevel } from '../contracts/IDBSQLLogger';
 import AuthenticationError from '../errors/AuthenticationError';
 import HiveDriverError from '../errors/HiveDriverError';
 import { buildUserAgentString, normalizePemBytes } from '../utils';
+import driverVersion from '../version';
+import { DRIVER_NAME } from '../telemetry/types';
+import { sanitizeProcessName, isTelemetryDisabledByEnv } from '../telemetry/telemetryUtils';
 
 /**
  * Default local listener port for the U2M authorization-code callback.
@@ -131,6 +137,32 @@ export interface KernelSessionDefaults {
   retryOverallTimeoutSecs?: number;
 }
 
+export interface KernelTelemetryOptions {
+  /** Driver/runtime identity forwarded to kernel-owned telemetry. */
+  driverName?: string;
+  driverVersion?: string;
+  runtimeName?: string;
+  runtimeVersion?: string;
+  runtimeVendor?: string;
+  osName?: string;
+  osVersion?: string;
+  osArch?: string;
+  clientAppName?: string;
+  localeName?: string;
+  charSetEncoding?: string;
+  processName?: string;
+  /** Kernel-owned telemetry switch and batching. */
+  telemetryEnabled?: boolean;
+  telemetryBatchSize?: number;
+  telemetryFlushIntervalMs?: number;
+  telemetryMaxRetries?: number;
+  telemetryRetryDelayMs?: number;
+  telemetryCloseFlushTimeoutMs?: number;
+  telemetryCircuitBreakerEnabled?: boolean;
+  telemetryCircuitBreakerThreshold?: number;
+  telemetryCircuitBreakerTimeoutMs?: number;
+}
+
 /**
  * TLS options shared across all auth-mode variants. Mirror the napi
  * binding's `ConnectionOptions.checkServerCertificate` / `.customCaCert`
@@ -227,6 +259,7 @@ export interface KernelFederationOptions {
 export type KernelNativeConnectionOptions = KernelSessionDefaults &
   KernelTlsOptions &
   KernelHttpOptions &
+  KernelTelemetryOptions &
   KernelProxyOptions &
   KernelFederationOptions &
   (
@@ -588,6 +621,164 @@ export function buildKernelRetryOptions(config: {
   return out;
 }
 
+function getLocaleName(env: NodeJS.ProcessEnv = process.env): string {
+  try {
+    const lang = env.LC_ALL || env.LC_MESSAGES || env.LANG || '';
+    const match = lang.match(/^([a-z]{2}_[A-Z]{2})/);
+    return match?.[1] ?? 'en_US';
+  } catch {
+    return 'en_US';
+  }
+}
+
+function getProcessName(): string {
+  try {
+    if (process.title && process.title !== 'node') {
+      return sanitizeProcessName(process.title) || 'node';
+    }
+    const scriptPath = process.argv?.[1];
+    if (scriptPath) {
+      return sanitizeProcessName(scriptPath).replace(/\.[^.]*$/, '') || 'node';
+    }
+    return 'node';
+  } catch {
+    return 'node';
+  }
+}
+
+// Re-exported from the shared telemetry helper so the kernel opt-out and the
+// Thrift-path opt-out (DBSQLClient) parse `DATABRICKS_TELEMETRY_DISABLED`
+// through one implementation and can never drift.
+export { isTelemetryDisabledByEnv };
+
+/**
+ * Build the kernel telemetry options block from the driver's `ClientConfig`.
+ *
+ * **Always-forward is intentional, mirroring `buildKernelRetryOptions`.** On the
+ * real `DBSQLClient` path `getDefaultConfig()` seeds every one of these knobs from
+ * `DEFAULT_TELEMETRY_CONFIG`, so they are never `undefined` and always propagate to
+ * the kernel's `openSession` — the driver's telemetry-tuning defaults deliberately
+ * govern both backends from one `ClientConfig` (same rationale as the retry knobs),
+ * rather than letting the kernel's independent defaults apply. The kernel's own
+ * `"Omitted ⇒ kernel default"` branch is therefore only reachable via a bare
+ * `configOverrides`-style config (e.g. unit tests), not the default-populated one a
+ * live client uses. The `Number.isFinite(...) && > 0` guards below are NOT an
+ * opt-in gate: they exist to reject a caller-supplied out-of-range value (warning
+ * via `warnRejected`) and to tolerate sparse test configs, not to compare against
+ * the default.
+ */
+export function buildKernelTelemetryOptions(
+  config: Pick<
+    ClientConfig,
+    // NOTE: `telemetryEnabled` is intentionally NOT in this Pick. On the kernel
+    // path the enable decision is opt-in via `ConnectionOptions.telemetryEnabled`
+    // (plus the `DATABRICKS_TELEMETRY_DISABLED` env kill-switch) — the driver's
+    // default-true `config.telemetryEnabled` does not propagate here, so leaving
+    // it out keeps the signature honest rather than advertising a knob we ignore.
+    | 'telemetryBatchSize'
+    | 'telemetryFlushIntervalMs'
+    | 'telemetryMaxRetries'
+    | 'telemetryBackoffBaseMs'
+    | 'telemetryCloseTimeoutMs'
+    | 'telemetryCircuitBreakerThreshold'
+    | 'telemetryCircuitBreakerTimeout'
+  >,
+  options: Pick<ConnectionOptions, 'telemetryEnabled'> = {},
+  logger?: IDBSQLLogger,
+) {
+  // Surface a rejected telemetry knob for parity with the `DATABRICKS_TELEMETRY_DISABLED`
+  // misconfiguration warn in `DBSQLClient.connect`: a caller-supplied out-of-range value
+  // (e.g. `telemetryBatchSize: 0`) is silently dropped in favour of the kernel default,
+  // so without this the user gets no feedback that their setting was discarded. Only
+  // warns when the knob was actually supplied (`Number.isFinite`) but out of range —
+  // an unset knob (`undefined`) is never a misconfiguration. On the live `DBSQLClient`
+  // path these knobs are always populated from `DEFAULT_TELEMETRY_CONFIG`, so the
+  // `undefined` branch is the sparse-config (e.g. unit-test) case, not the norm.
+  const warnRejected = (name: string, value: number | undefined, constraint: string) => {
+    if (Number.isFinite(value)) {
+      logger?.log(
+        LogLevel.warn,
+        `Ignoring telemetry option '${name}'=${value}: value must be ${constraint}. ` +
+          `Falling back to the kernel default.`,
+      );
+    }
+  };
+  const telemetry: KernelTelemetryOptions = {
+    driverName: DRIVER_NAME,
+    driverVersion,
+    runtimeName: 'Node.js',
+    runtimeVersion: process.version,
+    runtimeVendor: 'Node.js Foundation',
+    osName: process.platform,
+    osVersion: os.release(),
+    osArch: os.arch(),
+    clientAppName: undefined,
+    localeName: getLocaleName(),
+    charSetEncoding: 'UTF-8',
+    processName: getProcessName(),
+  };
+
+  const envDisabled = isTelemetryDisabledByEnv();
+  if (options.telemetryEnabled !== undefined || envDisabled) {
+    telemetry.telemetryEnabled = (options.telemetryEnabled ?? true) && !envDisabled;
+  }
+
+  // `batchSize`, `flushIntervalMs`, and `closeFlushTimeoutMs` share the same napi
+  // contract constraint as the breaker fields below (`Must be greater than zero when
+  // supplied`), so a caller-supplied `0`/negative would forward verbatim and surface
+  // as a hard kernel `openSession` rejection. Treat any non-positive value as a
+  // misconfiguration and fall back to the kernel defaults, matching the breaker guard.
+  if (Number.isFinite(config.telemetryBatchSize) && config.telemetryBatchSize! > 0) {
+    telemetry.telemetryBatchSize = config.telemetryBatchSize;
+  } else {
+    warnRejected('telemetryBatchSize', config.telemetryBatchSize, 'greater than zero');
+  }
+  if (Number.isFinite(config.telemetryFlushIntervalMs) && config.telemetryFlushIntervalMs! > 0) {
+    telemetry.telemetryFlushIntervalMs = config.telemetryFlushIntervalMs;
+  } else {
+    warnRejected('telemetryFlushIntervalMs', config.telemetryFlushIntervalMs, 'greater than zero');
+  }
+  // `telemetryMaxRetries` and `telemetryRetryDelayMs` (from `telemetryBackoffBaseMs`)
+  // both document `0` as valid, so we don't require `> 0` like the fields above. Only
+  // `telemetryMaxRetries` is a user-settable `ConnectionOptions` knob (copied by
+  // `copyDefinedTelemetryOptions`); `telemetryBackoffBaseMs` is internal and only ever
+  // arrives from `DEFAULT_TELEMETRY_CONFIG.backoffBaseMs`, so it can't be user-negative
+  // today. We still guard both `>= 0` uniformly: a negative mapped onto the kernel's
+  // unsigned retry count would be rejected or wrap, so `>= 0` keeps `0` valid while
+  // falling back to the kernel default for negatives.
+  if (Number.isFinite(config.telemetryMaxRetries) && config.telemetryMaxRetries! >= 0) {
+    telemetry.telemetryMaxRetries = config.telemetryMaxRetries;
+  } else {
+    warnRejected('telemetryMaxRetries', config.telemetryMaxRetries, 'zero or greater');
+  }
+  if (Number.isFinite(config.telemetryBackoffBaseMs) && config.telemetryBackoffBaseMs! >= 0) {
+    telemetry.telemetryRetryDelayMs = config.telemetryBackoffBaseMs;
+  } else {
+    warnRejected('telemetryBackoffBaseMs', config.telemetryBackoffBaseMs, 'zero or greater');
+  }
+  if (Number.isFinite(config.telemetryCloseTimeoutMs) && config.telemetryCloseTimeoutMs! > 0) {
+    telemetry.telemetryCloseFlushTimeoutMs = config.telemetryCloseTimeoutMs;
+  } else {
+    warnRejected('telemetryCloseTimeoutMs', config.telemetryCloseTimeoutMs, 'greater than zero');
+  }
+  // The napi contract requires threshold/timeout to be strictly positive when
+  // supplied. A caller-supplied `0` (or negative) would otherwise be forwarded
+  // verbatim and surface as a hard kernel `openSession` rejection, so treat any
+  // non-positive value as a misconfiguration and delegate to the kernel default.
+  if (Number.isFinite(config.telemetryCircuitBreakerThreshold) && config.telemetryCircuitBreakerThreshold! > 0) {
+    telemetry.telemetryCircuitBreakerThreshold = config.telemetryCircuitBreakerThreshold;
+  } else {
+    warnRejected('telemetryCircuitBreakerThreshold', config.telemetryCircuitBreakerThreshold, 'greater than zero');
+  }
+  if (Number.isFinite(config.telemetryCircuitBreakerTimeout) && config.telemetryCircuitBreakerTimeout! > 0) {
+    telemetry.telemetryCircuitBreakerTimeoutMs = config.telemetryCircuitBreakerTimeout;
+  } else {
+    warnRejected('telemetryCircuitBreakerTimeout', config.telemetryCircuitBreakerTimeout, 'greater than zero');
+  }
+
+  return telemetry;
+}
+
 /**
  * Map the public `ConnectionOptions.proxy` (`{protocol, host, port, auth}` —
  * the same shape the Thrift backend accepts) onto the kernel's structured napi

lib/kernel/KernelBackend.ts

@@ -22,7 +22,12 @@ import HiveDriverError from '../errors/HiveDriverError';
 import { serializeQueryTags } from '../utils';
 import { getKernelNative, KernelNativeBinding, KernelConnection } from './KernelNativeLoader';
 import { decodeNapiKernelError } from './KernelErrorMapping';
-import { buildKernelConnectionOptions, buildKernelRetryOptions, KernelNativeConnectionOptions } from './KernelAuth';
+import {
+  buildKernelConnectionOptions,
+  buildKernelRetryOptions,
+  buildKernelTelemetryOptions,
+  KernelNativeConnectionOptions,
+} from './KernelAuth';
 import { installKernelLogBridge } from './KernelLogging';
 import KernelSessionBackend from './KernelSessionBackend';
 
@@ -93,6 +98,7 @@ export default class KernelBackend implements IBackend {
     this.nativeOptions = {
       ...buildKernelConnectionOptions(options),
       ...buildKernelRetryOptions(this.context.getConfig()),
+      ...buildKernelTelemetryOptions(this.context.getConfig(), options, this.context.getLogger()),
     };
 
     // Bridge the Rust kernel's `tracing` logs into the SAME `DBSQLLogger` the

lib/telemetry/telemetryUtils.ts

@@ -254,6 +254,21 @@ export function sanitizeProcessName(name: string | undefined): string {
   return lastSep < 0 ? firstToken : firstToken.slice(lastSep + 1);
 }
 
+/**
+ * Parse the `DATABRICKS_TELEMETRY_DISABLED` hard kill switch. Recognized truthy
+ * values are `1`, `true`, `yes`, `on` (case-insensitive, surrounding whitespace
+ * trimmed); anything else (empty, `0`, `false`, `no`, `off`, unrecognized)
+ * returns `false` and leaves telemetry under the runtime config's control.
+ *
+ * Single source of truth for both the Thrift path (DBSQLClient) and the kernel
+ * path (KernelAuth) so the two opt-outs can never drift.
+ */
+export function isTelemetryDisabledByEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.DATABRICKS_TELEMETRY_DISABLED;
+  const trimmed = typeof raw === 'string' ? raw.trim() : '';
+  return trimmed.length > 0 && /^(1|true|yes|on)$/i.test(trimmed);
+}
+
 /**
  * Run a telemetry emit at a call site, swallowing all exceptions and logging
  * at debug level. Replaces the copy-pasted try/catch + getTelemetryEmitter?.()

tests/unit/DBSQLClient.test.ts

@@ -4,6 +4,8 @@ import fs from 'fs';
 import DBSQLClient, { ThriftLibrary } from '../../lib/DBSQLClient';
 import DBSQLSession from '../../lib/DBSQLSession';
 import ThriftBackend from '../../lib/thrift-backend/ThriftBackend';
+import KernelBackend from '../../lib/kernel/KernelBackend';
+import * as KernelNativeLoader from '../../lib/kernel/KernelNativeLoader';
 
 import PlainHttpAuthentication from '../../lib/connection/auth/PlainHttpAuthentication';
 import DatabricksOAuth from '../../lib/connection/auth/DatabricksOAuth';
@@ -957,6 +959,29 @@ describe('DBSQLClient telemetry paths', () => {
         .filter((c) => c.args[0] === LogLevel.warn && /DATABRICKS_TELEMETRY_DISABLED/.test(c.args[1] as string));
       expect(warnCalls.length).to.equal(0);
     });
+
+    it('does not initialize Node telemetry on the kernel path', async () => {
+      delete process.env.DATABRICKS_TELEMETRY_DISABLED;
+      const client = new DBSQLClient();
+      const initStub = sinon.stub(client as any, 'initializeTelemetry').resolves();
+      // DBSQLClient constructs `new KernelBackend({ context: this })` without
+      // injecting a `nativeBinding`, so the KernelBackend constructor calls
+      // `getKernelNative()`, which throws where the native `.node` artifact
+      // isn't built (e.g. CI). Stub the loader so construction succeeds and the
+      // assertion below tests the `!useKernel` telemetry gate rather than the
+      // presence of a built kernel artifact.
+      sinon.stub(KernelNativeLoader, 'getKernelNative').returns({} as any);
+      sinon.stub(KernelBackend.prototype, 'connect').resolves();
+      sinon.stub(KernelBackend.prototype, 'close').resolves();
+
+      try {
+        await client.connect({ ...connectOptions, telemetryEnabled: true, useKernel: true } as any);
+
+        expect(initStub.callCount).to.equal(0);
+      } finally {
+        await client.close();
+      }
+    });
   });
 
   describe('extractWorkspaceId', () => {