feat(csharp): emit per-statement telemetry on the SEA path (PECO-3022)

[jadewang-db]

🥞 Stacked PR

Use this link to review incremental changes.

• stack/PECO-3022-sea-telemetry-design [Files changed] [MERGED]
  • stack/pr-phase1-connection-telemetry-create-refactor [Files changed]
    • stack/pr-phase2-observer-interface [Files changed]
      • stack/pr-phase3-databricks-statement-observer [Files changed]
        • stack/pr-phase4-sea-connection-telemetry [Files changed]
          • stack/pr-phase5-sea-statement-telemetry [Files changed]

---

Summary

Wires all eight observer hookpoints into StatementExecutionStatement so the SEA path emits a complete per-statement telemetry record matching the Thrift path. This is the final phase of the PECO-3022 stack — after merge, SEA telemetry is at production parity with Thrift for every field the design owns.

Observer callsites (all 8)

Hookpoint	Where it fires
OnExecuteStarted	ExecuteQueryInternalAsync before _client.ExecuteStatementAsync
OnExecuteSucceeded	After execute response, with SeaResultFormatMapper for ExecutionResult.Format
OnPollCompleted	After polling loop terminates (accumulated count + ms)
OnFirstBatchReady	At reader construction in ExecuteQueryInternalAsync (fires regardless of consumer iteration)
OnConsumed	At reader Dispose, with EnsureObserverSignaled safety net for consumers that abandon the reader
OnChunksDownloaded	At cloud-fetch reader Dispose; falls back to empty ChunkMetrics until the gap-fix workstream surfaces real values
OnError	ExecuteQueryInternalAsync catch block
OnFinalized	StatementExecutionStatement.Dispose, gated on _executeStarted, idempotent via Interlocked.CompareExchange

Additional pieces

• SeaResultFormatMapper — pure-function helper mapping wire disposition × manifest state to proto ExecutionResult.Format (per design §8).
• SeaMetadataOperationMapper + SetPendingMetadataOperation — categorizes metadata operations so GetCatalogs/GetSchemas/GetTables/GetColumns/GetPrimaryKeys/GetCrossReference emit (StatementType.Metadata, OperationType.List*) instead of (Query, ExecuteStatementAsync). GetTableTypes (pure local, no SQL) emits its own direct EmitStatementOperationTelemetry since it bypasses the statement pipeline.
• OperationType.ExecuteStatementAsync instead of ExecuteStatement — SEA is always async on the wire (design §17 open question ci(deps): Bump actions/checkout from 4 to 5 #3).
• ExecuteUpdate path — observer lifecycle now mirrors the Query path; UPDATE statements emit telemetry just like SELECTs.
• CLOSE_STATEMENT event — emitted from Dispose with idempotency gate, mirroring the Thrift path's per-statement-disposal event.
• E2E test skip-guards — 11 of 12 Skip.If(Protocol == "rest", ...) guards in csharp/test/E2E/Telemetry/ removed. The existing Thrift telemetry suite now runs against SEA, turning it into a Thrift-vs-SEA comparator. RetryCountTests stays skipped (retry_count belongs to a separate gap-fix workstream).

Files touched

• csharp/src/StatementExecution/StatementExecutionStatement.cs — observer field, 8 hookpoints, metadata pending-operation, CLOSE_STATEMENT emission, ExecuteUpdate wiring, EnsureObserverSignaled safety net.
• csharp/src/StatementExecution/StatementExecutionConnection.cs — GetTableTypes direct emission, metadata-tagged ExecuteMetadataSqlAsync overload, ExecuteShowColumnsAsync operation-type threading.
• csharp/src/StatementExecution/SeaResultFormatMapper.cs (new) — disposition→proto-enum mapping.
• csharp/src/StatementExecution/SeaMetadataOperationMapper.cs (new) — metadata-keyword→OperationType.List* mapping.
• csharp/test/Unit/StatementExecution/StatementExecutionStatementObserverTests.cs + StatementExecutionStatementObserverInjectionTests.cs (new) — comprehensive unit coverage of all hookpoints, idempotency, and metadata stamping.
• csharp/test/E2E/Telemetry/*.cs — 11 files: PECO-3010 skip-guards + stale TODOs removed.
• csharp/doc/gap-report-PECO-3022-sea-telemetry-*.md (4 reports) — documents the iterative gap-fill rounds, prod-data verification, and final comparator results.

Test plan

• Unit: all observer hookpoints fire exactly-once in the expected order; CLOSE_STATEMENT idempotent across repeated Dispose; OnFinalized exactly-once even when both error path and dispose path call it.
• E2E telemetry suite on SEA (Protocol=rest): 62 / 93 pass — every divergence vs the Thrift run (84 / 93) is explained: 19 are the B5/ChunkMetrics workstream dependency, 6 are intentional SEA skips (RetryCount + LZ4 disabled), 3 are environmental SQL timeouts unrelated to telemetry wiring.
• Production-verified in main.eng_lumberjack.prod_frontend_log_sql_driver_log:
  • 30/30 SEA EXECUTE records carry operation_type = EXECUTE_STATEMENT_ASYNC, result_set_ready_latency_millis, result_set_consumption_latency_millis populated, socket_timeout = 900 (matches Thrift)
  • 30 paired CLOSE_STATEMENT events emitted
  • execution_result = INLINE_ARROW (no FORMAT_UNSPECIFIED records)

Related

• Builds on refactor(csharp): make ConnectionTelemetry.Create protocol-agnostic (PECO-3022) #460, feat(csharp): add IStatementOperationObserver and fail-open implementations (PECO-3022) #461, refactor(csharp): route DatabricksStatement telemetry through IStatementOperationObserver (PECO-3022) #462, feat(csharp): wire connection-level telemetry into StatementExecutionConnection (PECO-3022) #463.
• Design: docs: add SEA telemetry integration design (PECO-3022) #455.
• Gap reports: csharp/doc/gap-report-PECO-3022-sea-telemetry-*.md.

Part of PECO-3022. Closes out the PECO-3022 stack.