oximeter: clean up query summary logic and docs. (#9184)

* Convert query summaries lazily; h/t @david-crespo.
* Drop query summaries from user-facing docs; h/t @ahl. This feature is
only useful for Oxide engineers to investigate oximeter performance, and
we don't want to leak implementation details into public docs.

Author: jmcarp

nexus/src/external_api/http_entrypoints.rs

@@ -7157,13 +7157,13 @@ impl NexusExternalApi for NexusExternalApiImpl {
                             .into_iter()
                             .map(Into::into)
                             .collect(),
-                        query_summaries: include_summaries.then_some(
+                        query_summaries: include_summaries.then(|| {
                             result
                                 .query_summaries
                                 .into_iter()
                                 .map(Into::into)
-                                .collect(),
-                        ),
+                                .collect()
+                        }),
                     })
                 })
                 .map_err(HttpError::from)
@@ -7201,13 +7201,13 @@ impl NexusExternalApi for NexusExternalApiImpl {
                             .into_iter()
                             .map(Into::into)
                             .collect(),
-                        query_summaries: include_summaries.then_some(
+                        query_summaries: include_summaries.then(|| {
                             result
                                 .query_summaries
                                 .into_iter()
                                 .map(Into::into)
-                                .collect(),
-                        ),
+                                .collect()
+                        }),
                     })
                 })
                 .map_err(HttpError::from)

nexus/types/src/external_api/params.rs

@@ -2443,8 +2443,11 @@ pub struct ProbeListSelector {
 pub struct TimeseriesQuery {
     /// A timeseries query string, written in the Oximeter query language.
     pub query: String,
-    /// Whether to include ClickHouse query summaries in the response.
+    /// Whether to include query summaries in the response. Note: we omit this
+    /// field from the generated docs, since it is not intended for consumption
+    /// by customers.
     #[serde(default)]
+    #[schemars(skip)]
     pub include_summaries: bool,
 }
 

nexus/types/src/external_api/views.rs

@@ -1124,14 +1124,14 @@ impl From<oxql_types::Table> for OxqlTable {
     }
 }
 
-/// Basic metadata about the resource usage of a single ClickHouse SQL query.
+/// Basic metadata about the resource usage of a query.
 #[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
 pub struct OxqlQuerySummary {
     /// The database-assigned query ID.
     pub id: Uuid,
-    /// The raw ClickHouse SQL query.
+    /// The raw query.
     pub query: String,
-    /// The total duration of the ClickHouse query (network plus execution).
+    /// The total duration of the query (network plus execution).
     pub elapsed_ms: usize,
     /// Summary of the data read and written.
     pub io_summary: oxql_types::IoSummary,
@@ -1153,7 +1153,10 @@ impl From<oxql_types::QuerySummary> for OxqlQuerySummary {
 pub struct OxqlQueryResult {
     /// Tables resulting from the query, each containing timeseries.
     pub tables: Vec<OxqlTable>,
-    /// Summaries of queries run against ClickHouse.
+    /// Summaries of queries run against ClickHouse. Note: we omit this field
+    /// from the generated docs, since it is not intended for consumption by
+    /// customers.
+    #[schemars(skip)]
     pub query_summaries: Option<Vec<OxqlQuerySummary>>,
 }
 

openapi/nexus.json

@@ -21426,54 +21426,6 @@
           "items"
         ]
       },
-      "IoCount": {
-        "description": "A count of bytes / rows accessed during a query.",
-        "type": "object",
-        "properties": {
-          "bytes": {
-            "description": "The number of bytes accessed.",
-            "type": "integer",
-            "format": "uint64",
-            "minimum": 0
-          },
-          "rows": {
-            "description": "The number of rows accessed.",
-            "type": "integer",
-            "format": "uint64",
-            "minimum": 0
-          }
-        },
-        "required": [
-          "bytes",
-          "rows"
-        ]
-      },
-      "IoSummary": {
-        "description": "Summary of the I/O resources used by a query.",
-        "type": "object",
-        "properties": {
-          "read": {
-            "description": "The bytes and rows read by the query.",
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/IoCount"
-              }
-            ]
-          },
-          "written": {
-            "description": "The bytes and rows written by the query.",
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/IoCount"
-              }
-            ]
-          }
-        },
-        "required": [
-          "read",
-          "written"
-        ]
-      },
       "IpNet": {
         "x-rust-type": {
           "crate": "oxnet",
@@ -22591,14 +22543,6 @@
         "description": "The result of a successful OxQL query.",
         "type": "object",
         "properties": {
-          "query_summaries": {
-            "nullable": true,
-            "description": "Summaries of queries run against ClickHouse.",
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/OxqlQuerySummary"
-            }
-          },
           "tables": {
             "description": "Tables resulting from the query, each containing timeseries.",
             "type": "array",
@@ -22611,41 +22555,6 @@
           "tables"
         ]
       },
-      "OxqlQuerySummary": {
-        "description": "Basic metadata about the resource usage of a single ClickHouse SQL query.",
-        "type": "object",
-        "properties": {
-          "elapsed_ms": {
-            "description": "The total duration of the ClickHouse query (network plus execution).",
-            "type": "integer",
-            "format": "uint",
-            "minimum": 0
-          },
-          "id": {
-            "description": "The database-assigned query ID.",
-            "type": "string",
-            "format": "uuid"
-          },
-          "io_summary": {
-            "description": "Summary of the data read and written.",
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/IoSummary"
-              }
-            ]
-          },
-          "query": {
-            "description": "The raw ClickHouse SQL query.",
-            "type": "string"
-          }
-        },
-        "required": [
-          "elapsed_ms",
-          "id",
-          "io_summary",
-          "query"
-        ]
-      },
       "OxqlTable": {
         "description": "A table represents one or more timeseries with the same schema.\n\nA table is the result of an OxQL query. It contains a name, usually the name of the timeseries schema from which the data is derived, and any number of timeseries, which contain the actual data.",
         "type": "object",
@@ -26034,11 +25943,6 @@
         "description": "A timeseries query string, written in the Oximeter query language.",
         "type": "object",
         "properties": {
-          "include_summaries": {
-            "description": "Whether to include ClickHouse query summaries in the response.",
-            "default": false,
-            "type": "boolean"
-          },
           "query": {
             "description": "A timeseries query string, written in the Oximeter query language.",
             "type": "string"