Populate sql_operation, statement_id, and auth_type in telemetry

Fixes:
- sql_operation now properly populated by fetching metadata before statement close
- statement_id always populated from operation handle GUID
- auth_type now included in driver_connection_params

Changes:
- DBSQLOperation: Fetch metadata before emitting statement.complete to ensure
  resultFormat is available for sql_operation field
- DBSQLClient: Track authType from connection options and include in
  driver configuration
- DatabricksTelemetryExporter: Export auth_type in driver_connection_params
- types.ts: Add authType to DriverConfiguration interface
- Design doc: Document auth_type, resultFormat population, and connection params

Implementation details:
- emitStatementComplete() is now async to await metadata fetch
- Auth type defaults to 'access-token' if not specified
- Result format fetched even if not explicitly requested by user
- Handles metadata fetch failures gracefully (continues without resultFormat)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: samikshya-chand_data <samikshya.chand@databricks.com>

Author: samikshya-db

lib/DBSQLClient.ts

@@ -80,6 +80,8 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
   // Telemetry components (instance-based, NOT singletons)
   private host?: string;
 
+  private authType?: string;
+
   private featureFlagCache?: FeatureFlagCache;
 
   private telemetryClientProvider?: TelemetryClientProvider;
@@ -210,6 +212,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       localeName: this.getLocaleName(),
       charSetEncoding: 'UTF-8',
       processName: this.getProcessName(),
+      authType: this.authType || 'access-token',
 
       // Feature flags
       cloudFetchEnabled: this.config.useCloudFetch ?? false,
@@ -377,8 +380,9 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       }
     }
 
-    // Store host for telemetry
+    // Store host and auth type for telemetry
     this.host = options.host;
+    this.authType = options.authType || 'access-token'; // Default to access-token
 
     // Store enableMetricViewMetadata configuration
     if (options.enableMetricViewMetadata !== undefined) {

lib/DBSQLOperation.ts

@@ -296,7 +296,7 @@ export default class DBSQLOperation implements IOperation {
     const result = new Status(response.status);
 
     // Emit statement.complete telemetry event
-    this.emitStatementComplete();
+    await this.emitStatementComplete();
 
     this.onClose?.();
     return result;
@@ -526,18 +526,29 @@ export default class DBSQLOperation implements IOperation {
    * Emit statement.complete telemetry event and complete aggregation.
    * CRITICAL: All exceptions swallowed and logged at LogLevel.debug ONLY.
    */
-  private emitStatementComplete(): void {
+  private async emitStatementComplete(): Promise<void> {
     try {
       const {telemetryEmitter} = (this.context as any);
       const {telemetryAggregator} = (this.context as any);
       if (!telemetryEmitter || !telemetryAggregator) {
         return;
       }
 
+      // Fetch metadata if not already fetched to get result format
+      let resultFormat: string | undefined;
+      try {
+        if (!this.metadata && !this.cancelled) {
+          await this.getMetadata();
+        }
+        resultFormat = this.metadata?.resultFormat
+          ? TSparkRowSetType[this.metadata.resultFormat]
+          : undefined;
+      } catch (error) {
+        // If metadata fetch fails, continue without it
+        resultFormat = undefined;
+      }
+
       const latencyMs = Date.now() - this.startTime;
-      const resultFormat = this.metadata?.resultFormat
-        ? TSparkRowSetType[this.metadata.resultFormat]
-        : undefined;
 
       telemetryEmitter.emitStatementComplete({
         statementId: this.id,

lib/telemetry/DatabricksTelemetryExporter.ts

@@ -293,6 +293,10 @@ export default class DatabricksTelemetryExporter {
       if (metric.latencyMs !== undefined) {
         log.entry.sql_driver_log.operation_latency_ms = metric.latencyMs;
       }
+      // Include driver connection params (auth type)
+      log.entry.sql_driver_log.driver_connection_params = {
+        auth_type: metric.driverConfig.authType,
+      };
     } else if (metric.metricType === 'statement') {
       log.entry.sql_driver_log.operation_latency_ms = metric.latencyMs;
 

lib/telemetry/types.ts

@@ -30,11 +30,6 @@ export enum TelemetryEventType {
   ERROR = 'error',
 }
 
-/**
- * Driver name constant for telemetry
- */
-export const DRIVER_NAME = 'nodejs-sql-driver';
-
 /**
  * Configuration for telemetry components
  */
@@ -215,6 +210,9 @@ export interface DriverConfiguration {
   /** Process name */
   processName: string;
 
+  /** Authentication type (access-token, databricks-oauth, custom) */
+  authType: string;
+
   // Feature flags
   /** Whether CloudFetch is enabled */
   cloudFetchEnabled: boolean;

spec/telemetry-design.md

@@ -1234,6 +1234,7 @@ interface DriverConfiguration {
   localeName: string;          // Locale (e.g., 'en_US')
   charSetEncoding: string;     // Character encoding (e.g., 'UTF-8')
   processName: string;         // Process name from process.title or script name
+  authType: string;            // Authentication type (access-token, databricks-oauth, custom)
 
   // Feature flags
   cloudFetchEnabled: boolean;
@@ -1255,6 +1256,10 @@ interface DriverConfiguration {
 - **localeName**: Extracted from `LANG` environment variable in format `language_country` (e.g., `en_US`), defaults to `en_US`
 - **charSetEncoding**: Always `'UTF-8'` (Node.js default encoding), equivalent to JDBC's Charset.defaultCharset()
 - **processName**: Obtained from `process.title` or extracted from `process.argv[1]` (script name), equivalent to JDBC's ProcessNameUtil.getProcessName()
+- **authType**: Authentication method used ('access-token', 'databricks-oauth', or 'custom'), exported as `driver_connection_params.auth_type`
+
+**Connection Parameters**:
+- **auth_type**: Exported in `driver_connection_params` field for connection metrics, indicates authentication method used
 
 ### 4.3 Statement Metrics
 
@@ -1271,7 +1276,7 @@ interface StatementMetrics {
   pollCount: number;
   pollLatencyMs: number;
 
-  // Result format
+  // Result format (fetched from metadata before statement close)
   resultFormat: 'inline' | 'cloudfetch' | 'arrow';
 
   // CloudFetch metrics
@@ -1281,6 +1286,8 @@ interface StatementMetrics {
 }
 ```
 
+**Result Format Population**: To ensure `sql_operation` is properly populated in telemetry logs, the driver fetches result set metadata before emitting the `statement.complete` event. This guarantees that `resultFormat` is available even if the user closes the statement immediately after execution without explicitly fetching results.
+
 ### 4.4 Privacy Considerations
 
 **Never Collected**: