You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Add section 14 detailing implemented and missing proto fields
- List all fields from OssSqlDriverTelemetryLog that are implemented
- Document which fields are not implemented and why
- Explain that missing fields require additional instrumentation
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: spec/telemetry-design.md
+62Lines changed: 62 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2382,6 +2382,68 @@ Compare:
2382
2382
2383
2383
---
2384
2384
2385
+
## 14. Proto Field Coverage
2386
+
2387
+
### 14.1 Implemented Fields
2388
+
2389
+
The Node.js driver implements the following fields from the `OssSqlDriverTelemetryLog` proto:
2390
+
2391
+
**Top-level fields:**
2392
+
-`session_id` - Session UUID for correlation
2393
+
-`sql_statement_id` - Statement UUID (filtered to exclude NIL UUID)
2394
+
-`system_configuration` - Complete driver and OS configuration
2395
+
-`auth_type` - Authentication type (pat, external-browser, oauth-m2m, custom)
2396
+
-`operation_latency_ms` - Operation execution time
2397
+
-`error_info` - Error details (name and stack trace)
2398
+
2399
+
**driver_connection_params:**
2400
+
-`http_path` - API endpoint path
2401
+
-`socket_timeout` - Connection timeout
2402
+
-`enable_arrow` - Arrow format flag
2403
+
-`enable_direct_results` - Direct results flag
2404
+
-`enable_metric_view_metadata` - Metric view metadata flag
2405
+
2406
+
**sql_operation (SqlExecutionEvent):**
2407
+
-`statement_type` - Operation type (EXECUTE_STATEMENT, LIST_CATALOGS, etc.)
2408
+
-`is_compressed` - Compression flag from CloudFetch
2409
+
-`execution_result` - Result format (INLINE_ARROW, INLINE_JSON, EXTERNAL_LINKS, COLUMNAR_INLINE)
2410
+
-`chunk_details.total_chunks_present` - Number of chunks
2411
+
-`chunk_details.total_chunks_iterated` - Number of chunks downloaded
2412
+
2413
+
### 14.2 Not Implemented Fields
2414
+
2415
+
The following proto fields are **not currently implemented** as they require additional instrumentation that is not present in the Node.js driver:
2416
+
2417
+
**sql_operation fields:**
2418
+
-`chunk_id` - Specific chunk identifier for failures (not tracked)
2419
+
-`retry_count` - Number of retry attempts (statement-level retries not tracked)
2420
+
-`operation_detail` (OperationDetail message):
2421
+
-`n_operation_status_calls` - Count of getOperationStatus calls
2422
+
-`operation_status_latency_millis` - Total latency of status calls
2423
+
-`operation_type` - Type of operation (redundant with statement_type)
2424
+
-`is_internal_call` - Whether operation is internal
2425
+
-`result_latency` (ResultLatency message):
2426
+
-`result_set_ready_latency_millis` - Time until first result available
2427
+
-`result_set_consumption_latency_millis` - Time to consume all results
2428
+
2429
+
**chunk_details fields:**
2430
+
-`initial_chunk_latency_millis` - Time to download first chunk
2431
+
-`slowest_chunk_latency_millis` - Maximum chunk download time
2432
+
-`sum_chunks_download_time_millis` - Total download time across all chunks
2433
+
2434
+
**driver_connection_params fields:**
2435
+
Most fields in `DriverConnectionParameters` are specific to JDBC/Java configurations and not applicable to the Node.js driver (proxy configuration, SSL settings, Azure/GCP specific settings, etc.). Only the fields listed in 14.1 are relevant and implemented.
2436
+
2437
+
**Reason for exclusion:** These fields require extensive instrumentation to track:
Implementing these would add significant complexity to the driver's core execution paths. They can be added in future iterations if needed for specific debugging or optimization use cases.
2444
+
2445
+
---
2446
+
2385
2447
## Summary
2386
2448
2387
2449
This **event-based telemetry design** provides an efficient approach to collecting driver metrics by:
0 commit comments