Fix telemetry and feature flag implementation

- Fix event listener names: use 'connection.open' not 'telemetry.connection.open'
- Fix feature flag endpoint: use NODEJS client type instead of OSS_NODEJS
- Fix telemetry endpoints: use /telemetry-ext and /telemetry-unauth (not /api/2.0/sql/...)
- Update telemetry payload to match proto: use system_configuration with snake_case fields
- Add URL utility to handle hosts with or without protocol
- Add telemetryBatchSize and telemetryAuthenticatedExport config options
- Remove debug statements and temporary feature flag override

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: samikshya-db

lib/DBSQLClient.ts

@@ -236,6 +236,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
 
       // Check if telemetry enabled via feature flag
       const enabled = await this.featureFlagCache.isTelemetryEnabled(this.host);
+
       if (!enabled) {
         this.logger.log(LogLevel.debug, 'Telemetry disabled via feature flag');
         return;
@@ -254,39 +255,39 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       this.telemetryAggregator = new MetricsAggregator(this, exporter);
 
       // Wire up event listeners
-      this.telemetryEmitter.on('telemetry.connection.open', (event) => {
+      this.telemetryEmitter.on('connection.open', (event) => {
         try {
           this.telemetryAggregator?.processEvent(event);
         } catch (error: any) {
           this.logger.log(LogLevel.debug, `Error processing connection.open event: ${error.message}`);
         }
       });
 
-      this.telemetryEmitter.on('telemetry.statement.start', (event) => {
+      this.telemetryEmitter.on('statement.start', (event) => {
         try {
           this.telemetryAggregator?.processEvent(event);
         } catch (error: any) {
           this.logger.log(LogLevel.debug, `Error processing statement.start event: ${error.message}`);
         }
       });
 
-      this.telemetryEmitter.on('telemetry.statement.complete', (event) => {
+      this.telemetryEmitter.on('statement.complete', (event) => {
         try {
           this.telemetryAggregator?.processEvent(event);
         } catch (error: any) {
           this.logger.log(LogLevel.debug, `Error processing statement.complete event: ${error.message}`);
         }
       });
 
-      this.telemetryEmitter.on('telemetry.cloudfetch.chunk', (event) => {
+      this.telemetryEmitter.on('cloudfetch.chunk', (event) => {
         try {
           this.telemetryAggregator?.processEvent(event);
         } catch (error: any) {
           this.logger.log(LogLevel.debug, `Error processing cloudfetch.chunk event: ${error.message}`);
         }
       });
 
-      this.telemetryEmitter.on('telemetry.error', (event) => {
+      this.telemetryEmitter.on('error', (event) => {
         try {
           this.telemetryAggregator?.processEvent(event);
         } catch (error: any) {
@@ -334,6 +335,12 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
     if (options.telemetryEnabled !== undefined) {
       this.config.telemetryEnabled = options.telemetryEnabled;
     }
+    if (options.telemetryBatchSize !== undefined) {
+      this.config.telemetryBatchSize = options.telemetryBatchSize;
+    }
+    if (options.telemetryAuthenticatedExport !== undefined) {
+      this.config.telemetryAuthenticatedExport = options.telemetryAuthenticatedExport;
+    }
 
     this.authProvider = this.createAuthProvider(options, authProvider);
 

lib/contracts/IDBSQLClient.ts

@@ -34,8 +34,10 @@ export type ConnectionOptions = {
   socketTimeout?: number;
   proxy?: ProxyOptions;
   enableMetricViewMetadata?: boolean;
-  // Optional telemetry override
+  // Optional telemetry overrides
   telemetryEnabled?: boolean;
+  telemetryBatchSize?: number;
+  telemetryAuthenticatedExport?: boolean;
 } & AuthOptions;
 
 export interface OpenSessionRequest {

lib/telemetry/DatabricksTelemetryExporter.ts

@@ -20,6 +20,7 @@ import { LogLevel } from '../contracts/IDBSQLLogger';
 import { TelemetryMetric, DEFAULT_TELEMETRY_CONFIG } from './types';
 import { CircuitBreakerRegistry } from './CircuitBreaker';
 import ExceptionClassifier from './ExceptionClassifier';
+import { buildUrl } from './urlUtils';
 
 /**
  * Databricks telemetry log format for export.
@@ -37,19 +38,33 @@ interface DatabricksTelemetryLog {
     sql_driver_log: {
       session_id?: string;
       sql_statement_id?: string;
+      system_configuration?: {
+        driver_version?: string;
+        runtime_name?: string;
+        runtime_version?: string;
+        runtime_vendor?: string;
+        os_name?: string;
+        os_version?: string;
+        os_arch?: string;
+        driver_name?: string;
+        client_app_name?: string;
+      };
+      driver_connection_params?: any;
       operation_latency_ms?: number;
       sql_operation?: {
-        execution_result_format?: string;
+        execution_result?: string;
         chunk_details?: {
-          chunk_count: number;
-          total_bytes?: number;
+          total_chunks_present?: number;
+          total_chunks_iterated?: number;
+          initial_chunk_latency_millis?: number;
+          slowest_chunk_latency_millis?: number;
+          sum_chunks_download_time_millis?: number;
         };
       };
       error_info?: {
         error_name: string;
         stack_trace: string;
       };
-      driver_config?: any;
     };
   };
 }
@@ -190,8 +205,8 @@ export default class DatabricksTelemetryExporter {
     const authenticatedExport =
       config.telemetryAuthenticatedExport ?? DEFAULT_TELEMETRY_CONFIG.authenticatedExport;
     const endpoint = authenticatedExport
-      ? `https://${this.host}/api/2.0/sql/telemetry-ext`
-      : `https://${this.host}/api/2.0/sql/telemetry-unauth`;
+      ? buildUrl(this.host, '/telemetry-ext')
+      : buildUrl(this.host, '/telemetry-unauth');
 
     // Format payload
     const payload: DatabricksTelemetryPayload = {
@@ -231,7 +246,7 @@ export default class DatabricksTelemetryExporter {
    */
   private toTelemetryLog(metric: TelemetryMetric): DatabricksTelemetryLog {
     const log: DatabricksTelemetryLog = {
-      workspace_id: metric.workspaceId,
+      // workspace_id: metric.workspaceId, // TODO: Determine if this should be numeric or omitted
       frontend_log_event_id: this.generateUUID(),
       context: {
         client_context: {
@@ -247,21 +262,29 @@ export default class DatabricksTelemetryExporter {
       },
     };
 
-    // Add metric-specific fields
+    // Add metric-specific fields based on proto definition
     if (metric.metricType === 'connection' && metric.driverConfig) {
-      log.entry.sql_driver_log.driver_config = metric.driverConfig;
+      // Map driverConfig to system_configuration (snake_case as per proto)
+      log.entry.sql_driver_log.system_configuration = {
+        driver_version: metric.driverConfig.driverVersion,
+        driver_name: metric.driverConfig.driverName,
+        runtime_name: 'Node.js',
+        runtime_version: metric.driverConfig.nodeVersion,
+        os_name: metric.driverConfig.platform,
+        os_version: metric.driverConfig.osVersion,
+      };
     } else if (metric.metricType === 'statement') {
       log.entry.sql_driver_log.operation_latency_ms = metric.latencyMs;
 
       if (metric.resultFormat || metric.chunkCount) {
         log.entry.sql_driver_log.sql_operation = {
-          execution_result_format: metric.resultFormat,
+          execution_result: metric.resultFormat,
         };
 
         if (metric.chunkCount && metric.chunkCount > 0) {
           log.entry.sql_driver_log.sql_operation.chunk_details = {
-            chunk_count: metric.chunkCount,
-            total_bytes: metric.bytesDownloaded,
+            total_chunks_present: metric.chunkCount,
+            total_chunks_iterated: metric.chunkCount,
           };
         }
       }

lib/telemetry/FeatureFlagCache.ts

@@ -17,6 +17,7 @@
 import IClientContext from '../contracts/IClientContext';
 import { LogLevel } from '../contracts/IDBSQLLogger';
 import fetch from 'node-fetch';
+import { buildUrl } from './urlUtils';
 
 /**
  * Context holding feature flag state for a specific host.
@@ -118,8 +119,8 @@ export default class FeatureFlagCache {
       // Get driver version for endpoint
       const driverVersion = this.getDriverVersion();
 
-      // Build feature flags endpoint
-      const endpoint = `https://${host}/api/2.0/connector-service/feature-flags/OSS_NODEJS/${driverVersion}`;
+      // Build feature flags endpoint for Node.js driver
+      const endpoint = buildUrl(host, `/api/2.0/connector-service/feature-flags/NODEJS/${driverVersion}`);
 
       // Get authentication headers
       const authHeaders = await this.context.getAuthHeaders();

lib/telemetry/urlUtils.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2025 Databricks Contributors
+ *
+ * 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.
+ */
+
+/**
+ * Build full URL from host and path, handling protocol correctly.
+ * @param host The hostname (with or without protocol)
+ * @param path The path to append (should start with /)
+ * @returns Full URL with protocol
+ */
+export function buildUrl(host: string, path: string): string {
+  // Check if host already has protocol
+  if (host.startsWith('http://') || host.startsWith('https://')) {
+    return `${host}${path}`;
+  }
+  // Add https:// if no protocol present
+  return `https://${host}${path}`;
+}