Skip to content

Commit ffdaa64

Browse files
committed
Add comprehensive telemetry system for Node.js SQL driver
Implements a complete telemetry system following the JDBC driver pattern: Core Components: - TelemetryEventEmitter: Event-based telemetry emission using Node.js EventEmitter - MetricsAggregator: Per-statement aggregation with batch processing and periodic flushing - DatabricksTelemetryExporter: HTTP export to Databricks telemetry endpoints with retry logic - FeatureFlagCache: Per-host feature flag caching with reference counting - CircuitBreaker: Per-host endpoint protection with OPEN/HALF_OPEN/CLOSED states - ExceptionClassifier: Terminal vs retryable exception classification - TelemetryClient/Provider: Per-host HTTP client management with reference counting Integration: - Integrated into DBSQLClient with per-connection lifecycle management - Event emissions at key driver operations: connection.open, statement.start/complete, cloudfetch.chunk, error - Feature flag driven with runtime override support via ConnectionOptions - All telemetry errors swallowed and logged at debug level only - Zero impact on driver operations when telemetry fails or is disabled Testing: - 226 comprehensive unit and integration tests - 97.76% line coverage, 90.59% branch coverage, 100% function coverage - Tests verify exception swallowing, debug-only logging, reference counting, circuit breaker behavior Configuration: - telemetryEnabled: boolean (default: false, feature flag driven) - telemetryBatchSize: number (default: 100) - telemetryFlushIntervalMs: number (default: 5000) - telemetryRetryMaxAttempts: number (default: 3) See docs/TELEMETRY.md for complete documentation.
1 parent d0a68a1 commit ffdaa64

31 files changed

Lines changed: 11197 additions & 4 deletions

README.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,53 @@ client
5151
});
5252
```
5353

54+
## Telemetry
55+
56+
The Databricks SQL Driver for Node.js includes an **opt-in telemetry system** that collects driver usage metrics and performance data to help improve the driver. Telemetry is **disabled by default** and follows a **privacy-first design**.
57+
58+
### Key Features
59+
60+
- **Privacy-first**: No SQL queries, results, or sensitive data is ever collected
61+
- **Opt-in**: Controlled by server-side feature flag (disabled by default)
62+
- **Non-blocking**: All telemetry operations are asynchronous and never impact your queries
63+
- **Resilient**: Circuit breaker protection prevents telemetry failures from affecting your application
64+
65+
### What Data is Collected?
66+
67+
When enabled, the driver collects:
68+
69+
- ✅ Driver version and configuration settings
70+
- ✅ Query performance metrics (latency, chunk counts, bytes downloaded)
71+
- ✅ Error types and status codes
72+
- ✅ Feature usage (CloudFetch, Arrow format, compression)
73+
74+
**Never collected**:
75+
76+
- ❌ SQL query text
77+
- ❌ Query results or data values
78+
- ❌ Table/column names or schema information
79+
- ❌ User credentials or personal information
80+
81+
### Configuration
82+
83+
To enable or disable telemetry explicitly:
84+
85+
```javascript
86+
const client = new DBSQLClient({
87+
telemetryEnabled: true, // Enable telemetry (default: false)
88+
});
89+
90+
// Or override per connection:
91+
await client.connect({
92+
host: '********.databricks.com',
93+
path: '/sql/2.0/warehouses/****************',
94+
token: 'dapi********************************',
95+
telemetryEnabled: false, // Disable for this connection
96+
});
97+
```
98+
99+
For detailed documentation including configuration options, event types, troubleshooting, and privacy details, see [docs/TELEMETRY.md](docs/TELEMETRY.md).
100+
54101
## Run Tests
55102

56103
### Unit tests

0 commit comments

Comments
 (0)