clarify endpoint documentation

oxidecomputer · Nov 21, 2024 · 8412fb1 · 8412fb1
1 parent 9637d25
commit 8412fb1
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 11 deletions.
diff --git a/clickhouse-admin/api/src/lib.rs b/clickhouse-admin/api/src/lib.rs
@@ -118,11 +118,12 @@ pub trait ClickhouseAdminServerApi {
         rqctx: RequestContext<Self::Context>,
     ) -> Result<HttpResponseOk<Vec<DistributedDdlQueue>>, HttpError>;
 
-    /// Retrieve time series from the system database.
+    /// Retrieve time series from the system database. The value the average of all
+    /// values within the interval.
     /// These are internal ClickHouse metrics.
     #[endpoint {
         method = GET,
-        path = "/timeseries/{table}/{metric}"
+        path = "/timeseries/{table}/{metric}/avg"
     }]
     async fn system_timeseries_avg(
         rqctx: RequestContext<Self::Context>,

diff --git a/clickhouse-admin/src/clickhouse_cli.rs b/clickhouse-admin/src/clickhouse_cli.rs
@@ -11,7 +11,7 @@ use clickhouse_admin_types::{
 };
 use dropshot::HttpError;
 use illumos_utils::{output_to_exec_error, ExecutionError};
-use slog::Logger;
+use slog::{info, Logger};
 use slog_error_chain::{InlineErrorChain, SlogInlineError};
 use std::collections::BTreeSet;
 use std::ffi::OsStr;
@@ -172,13 +172,17 @@ impl ClickhouseCli {
         &self,
         settings: SystemTimeSeriesSettings,
     ) -> Result<Vec<SystemTimeSeries>, ClickhouseCliError> {
-        // TODO: log query
+        let log = self.log.clone().unwrap();
+        let query = settings.query_avg();
+
+        info!(&log, "Querying system database"; "query" => &query);
+
         self.client_non_interactive(
             ClickhouseClientType::Server,
-            settings.query_avg().as_str(),
-            "Retrieve time series from the system.metric_log table",
+            &query,
+            "Retrieve time series from the system database",
             SystemTimeSeries::parse,
-            self.log.clone().unwrap(),
+            log,
         )
         .await
     }
@@ -222,7 +226,7 @@ impl ClickhouseCli {
                 ClickhouseCliError::Run {
                     description: subcommand_description,
                     subcommand: err_args_str,
-                    err: err.into(),
+                    err,
                 }
             })?,
             Err(e) => {

diff --git a/openapi/clickhouse-admin-server.json b/openapi/clickhouse-admin-server.json
@@ -74,10 +74,10 @@
         }
       }
     },
-    "/timeseries/{table}/{metric}": {
+    "/timeseries/{table}/{metric}/avg": {
       "get": {
-        "summary": "Retrieve time series from the system database.",
-        "description": "These are internal ClickHouse metrics.",
+        "summary": "Retrieve time series from the system database. The value the average of all",
+        "description": "values within the interval. These are internal ClickHouse metrics.",
         "operationId": "system_timeseries_avg",
         "parameters": [
           {