details about query execution

js/types/v1/query_metrics_pb.ts

@@ -30,21 +30,36 @@ export type QueryMetrics = Message<"types.v1.QueryMetrics"> & {
   queryText: string;
 
   /**
+   * Time from query start to query returning. Measures query submission overhead
+   * (network round-trip, connection setup).
+   *
    * @generated from field: google.protobuf.Duration query_sent_latency = 300;
    */
   querySentLatency?: Duration;
 
   /**
+   * Time from query start to first row ready. Also known as "Time to First Row"
+   * (TTFR) or "Time to First Byte" (TTFB). Measures query execution latency on
+   * server.
+   *
    * @generated from field: google.protobuf.Duration first_result_latency = 301;
    */
   firstResultLatency?: Duration;
 
   /**
+   * Wall-clock time from first row to last row. Measures result fetching
+   * duration (not cumulative time spent). Calculated as
+   * `lastFetchTime - firstFetchTime`, so include serialization and
+   * row-processing overhead.
+   *
    * @generated from field: google.protobuf.Duration final_result_latency = 302;
    */
   finalResultLatency?: Duration;
 
   /**
+   * Full end-to-end time from query start to close. Total duration
+   * during which the server processed the request.
+   *
    * @generated from field: google.protobuf.Duration total_latency = 3;
    */
   totalLatency?: Duration;

proto/types/v1/query_metrics.proto

@@ -11,9 +11,20 @@ message QueryMetrics {
   string query_id = 1;
   string query_text = 2;
 
+  // Time from query start to query returning. Measures query submission overhead
+  // (network round-trip, connection setup).
   google.protobuf.Duration query_sent_latency = 300;
+  // Time from query start to first row ready. Also known as "Time to First Row"
+  // (TTFR) or "Time to First Byte" (TTFB). Measures query execution latency on
+  // server.
   google.protobuf.Duration first_result_latency = 301;
+  // Wall-clock time from first row to last row. Measures result fetching
+  // duration (not cumulative time spent). Calculated as
+  // `lastFetchTime - firstFetchTime`, so include serialization and
+  // row-processing overhead.
   google.protobuf.Duration final_result_latency = 302;
+  // Full end-to-end time from query start to close. Total duration
+  // during which the server processed the request.
   google.protobuf.Duration total_latency = 3;
 
   int64 rows_returned = 4;