databricks
diff --git a/‎.eslintrc‎
Lines changed: 2 additions & 1 deletion b/‎.eslintrc‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎CHANGELOG.md‎
Lines changed: 7 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 85 additions & 0 deletions b/‎README.md‎
Lines changed: 85 additions & 0 deletions
@@ -29,7 +29,8 @@
       "files": ["*.test.js", "*.test.ts"],
       "rules": {
         "no-unused-expressions": "off",
-        "@typescript-eslint/no-unused-expressions": "off"
+        "@typescript-eslint/no-unused-expressions": "off",
+        "func-names": "off"
       }
     }
   ]
 
@@ -12,6 +12,13 @@
 - Add metric view metadata support (databricks/databricks-sql-nodejs#312 by @shivam2680)
 - Fix: Avoid calling require('lz4') if it's really not required (databricks/databricks-sql-nodejs#316 by @ikkala)
 - Add telemetry foundation (off by default) (databricks/databricks-sql-nodejs#324 by @samikshya-db)
+- Telemetry event emission and per-host aggregation (databricks/databricks-sql-nodejs#327 by @samikshya-db).
+  **Default change:** `telemetryEnabled` now defaults to `true` (gated by a remote feature flag).
+  To opt out programmatically, pass `telemetryEnabled: false` to `connect()`.
+  To disable globally without code changes, set the environment variable
+  `DATABRICKS_TELEMETRY_DISABLED` to one of `1`, `true`, `yes`, or `on`
+  (case-insensitive). Other values (empty, `0`, `false`, etc.) are ignored
+  — the runtime config takes precedence.
 
 ## 1.12.0
 
 
@@ -51,6 +51,91 @@ client
   });
 ```
 
+## Telemetry
+
+Starting with version 1.13, the driver collects telemetry — connection,
+statement, and CloudFetch chunk metrics, plus error events with redacted
+stack traces — to help Databricks improve driver performance and
+reliability. **Telemetry is enabled by default and gated by a server-side
+feature flag**: events are emitted only when the workspace's feature flag
+is on. No SQL text, parameter values, or row data are ever included.
+
+### What's collected
+
+- Connection lifecycle (`CREATE_SESSION`, `DELETE_SESSION`) with latency.
+- Statement lifecycle (`STATEMENT_START`, `STATEMENT_COMPLETE`) with
+  execution latency, operation type, and result format.
+- CloudFetch chunk timings and byte counts.
+- Error events with redacted stack traces (Bearer/JWT tokens, OAuth
+  secrets, home-directory paths, and Databricks PATs are stripped before
+  emission).
+
+See `TelemetryEvent` and `TelemetryMetric` in the package exports for the
+exact payload shapes.
+
+### Multi-tenant SaaS deployments — read this before enabling telemetry
+
+The telemetry layer shares one per-host `TelemetryClient` across every
+`DBSQLClient` connected to the same Databricks workspace host. The
+authenticated export path uses the **first-registered** client's auth
+provider, User-Agent, and `telemetryAuthenticatedExport` value — these
+fields are snapshotted at the host singleton and are **not** per-tenant.
+
+If you are operating a SaaS layer that fronts multiple tenants against the
+same Databricks workspace host with a shared driver process, telemetry from
+tenant B's queries can be POSTed under tenant A's auth headers, with
+tenant A's `userAgentEntry`. A tenant B that explicitly set
+`telemetryAuthenticatedExport: false` will still ride tenant A's
+authenticated pipeline.
+
+> **Recommendation for multi-tenant deployments**: set
+> `telemetryEnabled: false` on all `DBSQLClient` instances, or partition
+> by Databricks workspace host so each tenant owns its own
+> `TelemetryClient`. Subsequent registrants with diverging auth/UA values
+> emit a warn-level log so the leak is at least visible.
+
+### Opting out
+
+Three independent ways to disable telemetry, in order of precedence:
+
+1. **Environment variable** — set `DATABRICKS_TELEMETRY_DISABLED` to one
+   of `1`, `true`, `yes`, or `on` (case-insensitive). Other values
+   (empty, `0`, `false`, `off`, `no`) are ignored, leaving the runtime
+   config in charge.
+2. **Programmatic** — pass `telemetryEnabled: false` to `connect()`:
+   ```javascript
+   await client.connect({
+     host,
+     path,
+     token,
+     telemetryEnabled: false,
+   });
+   ```
+3. **Server-side** — Databricks-managed feature flag; if disabled for
+   your workspace, the driver does not emit telemetry regardless of
+   client config.
+
+### Tuning
+
+If you keep telemetry on, the following knobs are available on
+`ConnectionOptions` (see JSDoc on `IDBSQLClient.ts` for defaults and
+units):
+
+- `telemetryAuthenticatedExport` — set to `false` to ship reduced
+  payloads (no statement/session correlation IDs, generic User-Agent)
+  via the unauthenticated endpoint.
+- `telemetryBatchSize`, `telemetryFlushIntervalMs`, `telemetryMaxRetries`
+  — batching and retry tuning.
+- `telemetryCircuitBreakerThreshold`, `telemetryCircuitBreakerTimeout` —
+  circuit-breaker tuning for the export endpoint.
+- `telemetryCloseTimeoutMs` — bound on `await client.close()` waiting for
+  the final flush.
+
+> **Note for short-lived processes**: always `await client.close()`
+> before `process.exit(0)` so the final batch is flushed. Without an
+> explicit close, the periodic flush timer is `unref()`'d to avoid
+> holding the event loop open, so any unflushed events are dropped.
+
 ## Run Tests
 
 ### Unit tests
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,8 @@`
`29`	`29`	`"files": [".test.js", ".test.ts"],`
`30`	`30`	`"rules": {`
`31`	`31`	`"no-unused-expressions": "off",`
`32`		`- "@typescript-eslint/no-unused-expressions": "off"`
	`32`	`+ "@typescript-eslint/no-unused-expressions": "off",`
	`33`	`+ "func-names": "off"`
`33`	`34`	`}`
`34`	`35`	`}`
`35`	`36`	`]`