Skip to content

Commit 53189a8

Browse files
samikshya-dbclaude
andcommitted
Document proto field coverage in design doc
- 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>
1 parent 25c8f51 commit 53189a8

1 file changed

Lines changed: 62 additions & 0 deletions

File tree

spec/telemetry-design.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2382,6 +2382,68 @@ Compare:
23822382

23832383
---
23842384

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:
2438+
- Per-operation status polling (operation_detail)
2439+
- Result set consumption timing (result_latency)
2440+
- Per-chunk download timing (chunk_details timing fields)
2441+
- Statement-level retry tracking
2442+
2443+
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+
23852447
## Summary
23862448

23872449
This **event-based telemetry design** provides an efficient approach to collecting driver metrics by:

0 commit comments

Comments
 (0)