oximeter: clean up query summary logic and docs.

* Convert query summaries lazily; h/t @david-crespo.
* Genericize user-facing docs; h/t @ahl. We don't need to leak details of the
  oximeter implementation here, so we drop references to clickhouse and clarify
  that query summaries are meant for performance investigation and not general
  use.

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,7 +2443,7 @@ 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. Used to track oximeter performance.
     #[serde(default)]
     pub include_summaries: bool,
 }

nexus/types/src/external_api/views.rs

@@ -1123,14 +1123,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 single backend 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,
@@ -1152,7 +1152,7 @@ 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 the oximeter backend. Used to track oximeter performance.
     pub query_summaries: Option<Vec<OxqlQuerySummary>>,
 }
 

openapi/nexus.json

@@ -22553,7 +22553,7 @@
         "properties": {
           "query_summaries": {
             "nullable": true,
-            "description": "Summaries of queries run against ClickHouse.",
+            "description": "Summaries of queries run against the oximeter backend. Used to track oximeter performance.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/OxqlQuerySummary"
@@ -22572,11 +22572,11 @@
         ]
       },
       "OxqlQuerySummary": {
-        "description": "Basic metadata about the resource usage of a single ClickHouse SQL query.",
+        "description": "Basic metadata about the resource usage of a single backend query.",
         "type": "object",
         "properties": {
           "elapsed_ms": {
-            "description": "The total duration of the ClickHouse query (network plus execution).",
+            "description": "The total duration of the query (network plus execution).",
             "type": "integer",
             "format": "uint",
             "minimum": 0
@@ -22595,7 +22595,7 @@
             ]
           },
           "query": {
-            "description": "The raw ClickHouse SQL query.",
+            "description": "The raw query.",
             "type": "string"
           }
         },
@@ -26037,7 +26037,7 @@
         "type": "object",
         "properties": {
           "include_summaries": {
-            "description": "Whether to include ClickHouse query summaries in the response.",
+            "description": "Whether to include query summaries in the response. Used to track oximeter performance.",
             "default": false,
             "type": "boolean"
           },