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 {
@@ -729,7 +729,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 +764,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 +778,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,16 @@
 // 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 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 +136,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 +258,7 @@ export interface KernelFederationOptions {
 export type KernelNativeConnectionOptions = KernelSessionDefaults &
   KernelTlsOptions &
   KernelHttpOptions &
+  KernelTelemetryOptions &
   KernelProxyOptions &
   KernelFederationOptions &
   (
@@ -588,6 +620,97 @@ 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 };
+
+export function buildKernelTelemetryOptions(
+  config: Pick<
+    ClientConfig,
+    | 'telemetryEnabled'
+    | 'telemetryBatchSize'
+    | 'telemetryFlushIntervalMs'
+    | 'telemetryMaxRetries'
+    | 'telemetryBackoffBaseMs'
+    | 'telemetryCloseTimeoutMs'
+    | 'telemetryCircuitBreakerThreshold'
+    | 'telemetryCircuitBreakerTimeout'
+  >,
+) {
+  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(),
+    // The JS/Thrift telemetry path always runs with a per-host circuit breaker
+    // (`CircuitBreakerRegistry` creates one unconditionally). Enable the kernel's
+    // breaker too so the `telemetryCircuitBreakerThreshold` / `...TimeoutMs` knobs
+    // forwarded below actually take effect — the napi `.d.ts` documents those two
+    // as applying only when the breaker is enabled, so if the kernel defaults it
+    // off they would silently do nothing.
+    telemetryCircuitBreakerEnabled: true,
+    telemetryEnabled: (config.telemetryEnabled ?? true) && !isTelemetryDisabledByEnv(),
+  };
+
+  if (Number.isFinite(config.telemetryBatchSize)) {
+    telemetry.telemetryBatchSize = config.telemetryBatchSize;
+  }
+  if (Number.isFinite(config.telemetryFlushIntervalMs)) {
+    telemetry.telemetryFlushIntervalMs = config.telemetryFlushIntervalMs;
+  }
+  if (Number.isFinite(config.telemetryMaxRetries)) {
+    telemetry.telemetryMaxRetries = config.telemetryMaxRetries;
+  }
+  if (Number.isFinite(config.telemetryBackoffBaseMs)) {
+    telemetry.telemetryRetryDelayMs = config.telemetryBackoffBaseMs;
+  }
+  if (Number.isFinite(config.telemetryCloseTimeoutMs)) {
+    telemetry.telemetryCloseFlushTimeoutMs = config.telemetryCloseTimeoutMs;
+  }
+  if (Number.isFinite(config.telemetryCircuitBreakerThreshold)) {
+    telemetry.telemetryCircuitBreakerThreshold = config.telemetryCircuitBreakerThreshold;
+  }
+  if (Number.isFinite(config.telemetryCircuitBreakerTimeout)) {
+    telemetry.telemetryCircuitBreakerTimeoutMs = config.telemetryCircuitBreakerTimeout;
+  }
+
+  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()),
     };
 
     // 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,7 @@ 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 PlainHttpAuthentication from '../../lib/connection/auth/PlainHttpAuthentication';
 import DatabricksOAuth from '../../lib/connection/auth/DatabricksOAuth';
@@ -957,6 +958,22 @@ 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();
+      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', () => {

tests/unit/kernel/_helpers/nativeOptions.ts

@@ -33,6 +33,31 @@ export default function expectNativeConnectionOptions(actual: unknown, expectedR
   const { customHeaders, ...rest } = actual as Record<string, unknown> & {
     customHeaders?: Array<{ name: string; value: string }>;
   };
+  for (const key of [
+    'driverName',
+    'driverVersion',
+    'runtimeName',
+    'runtimeVersion',
+    'runtimeVendor',
+    'osName',
+    'osVersion',
+    'osArch',
+    'clientAppName',
+    'localeName',
+    'charSetEncoding',
+    'processName',
+    'telemetryEnabled',
+    'telemetryBatchSize',
+    'telemetryFlushIntervalMs',
+    'telemetryMaxRetries',
+    'telemetryRetryDelayMs',
+    'telemetryCloseFlushTimeoutMs',
+    'telemetryCircuitBreakerEnabled',
+    'telemetryCircuitBreakerThreshold',
+    'telemetryCircuitBreakerTimeoutMs',
+  ]) {
+    delete rest[key];
+  }
   expect(rest).to.deep.equal(expectedRest);
   expect(customHeaders, 'customHeaders').to.be.an('array').with.lengthOf(1);
   expect(customHeaders?.[0].name).to.equal('User-Agent');