Check in oxql benchmark.

Add oxql field lookup benchmark. To avoid the complication of generating
realistic synthetic data, we provide scripts for fetching and loading
fields from a running ClickHouse instance.

Author: jmcarp

Cargo.lock

@@ -112,6 +112,7 @@ expectorate.workspace = true
 itertools.workspace = true
 omicron-test-utils.workspace = true
 oximeter-test-utils.workspace = true
+rand.workspace = true
 slog-dtrace.workspace = true
 sqlformat.workspace = true
 sqlparser.workspace = true
@@ -150,3 +151,7 @@ doc = false
 [[bench]]
 name = "protocol"
 harness = false
+
+[[bench]]
+name = "oxql"
+harness = false

oximeter/db/Cargo.toml

@@ -0,0 +1,36 @@
+# Oximeter benchmarks
+
+## Field lookup
+
+Filtering and pivoting OxQL field labels can take a significant fraction of overall query time, so we include a benchmark focusing on field lookup. This benchmark queries all timeseries for a given table, filtering on a far-future timestamp so that we don't exercise measurement lookup. Because field lookup latency varies with the number of field tables to be combined, we include metrics that use varying numbers of field types. In the interest of benchmarking realistic queries, this benchmark doesn't generate synthetic data, but instead provides scripts for the operator to back up real field data from a running rack and restore them into a test database.
+
+To fetch field data:
+
+```bash
+$ mkdir -p /tmp/oximeter-field-bench
+$ oximeter/db/benches/backup_field_tables.sh /tmp/oximeter-field-bench [port]
+```
+
+To restore into a test database. Note: take care not to restore into a real Oxide rack. For safety, the load script will fail if the destination database has nonzero rows.
+
+```bash
+$ oximeter/db/benches/load_field_tables.sh /tmp/oximeter-field-bench [port]
+```
+
+Then run the benchmark:
+
+```bash
+$ cargo bench --package oximeter-db --bench oxql -- --save-baseline main
+```
+
+To evaluate performance changes, run the benchmark using a new baseline:
+
+```bash
+$ cargo bench --package oximeter-db --bench oxql -- --save-baseline my-branch
+```
+
+Then compare with `critcmp`:
+
+```bash
+$ critcmp main my-branch
+```

oximeter/db/benches/README.md

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Dump ClickHouse field and schema tables to disk in native format. Run against
+# a test rack with realistic oximeter data. Used to capture test data for
+# benchmarking.
+#
+# Usage: ./backup_field_tables.sh <output_dir> [port]
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <output_dir> [port]" >&2
+    exit 1
+fi
+
+OUTPUT_DIR="$1"
+PORT="${2:-9000}"
+DATABASE="oximeter"
+
+mkdir -p "$OUTPUT_DIR"
+
+# Back up field tables.
+#
+# Note: Use SELECT rather than RESTORE because we may not have access to the
+# remote ClickHouse's local disk, or have backups enabled at all.
+for table in timeseries_schema fields_{bool,i8,i16,i32,i64,ipaddr,string,u8,u16,u32,u64,uuid}; do
+    count=$(clickhouse client --port "$PORT" \
+        --query "SELECT count() FROM $DATABASE.$table")
+    if [[ "$count" -eq 0 ]]; then
+        echo "No rows in table $DATABASE.$table; skipping"
+        continue
+    fi
+    output="$OUTPUT_DIR/${table}.native.gz"
+    echo "Backing up $DATABASE.$table ($count rows) to $output"
+    clickhouse client --port "$PORT" \
+        --query "SELECT * FROM $DATABASE.$table FORMAT Native" \
+        | gzip > "$output"
+done

oximeter/db/benches/backup_field_tables.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+#
+# Load field table backups into a fresh ClickHouse for benchmarking.
+# Crashes if the destination database already contains data.
+#
+# Usage: ./load_field_tables.sh <input_dir> [port]
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <input_dir> [port]" >&2
+    exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCHEMA_DIR="$SCRIPT_DIR/../schema/single-node"
+
+INPUT_DIR="$1"
+PORT="${2:-9000}"
+
+DATABASE="oximeter"
+
+# Error if database isn't empty.
+echo "Checking for existing data..."
+count=$(clickhouse client --port "$PORT" \
+    --query "SELECT ifNull(sum(total_rows), 0) FROM system.tables WHERE database = '$DATABASE'" \
+    2>/dev/null || echo "0")
+
+if [[ "$count" -gt 0 ]]; then
+    echo "Error: $DATABASE database already contains data ($count rows)"
+    echo "Refusing to initialize a non-empty database."
+    exit 1
+fi
+
+# Initialize schema.
+echo "Initializing database schema..."
+clickhouse client --port "$PORT" --multiquery < "$SCHEMA_DIR/db-init.sql"
+
+# Load backups.
+#
+# Note: Use INSERT rather than RESTORE because we may not have access to the
+# remote ClickHouse's local disk, or have backups enabled at all.
+for table in timeseries_schema fields_{bool,i8,i16,i32,i64,ipaddr,string,u8,u16,u32,u64,uuid}; do
+    input="$INPUT_DIR/${table}.native.gz"
+    if [[ ! -f "$input" ]]; then
+        echo "No backup for table $table; skipping"
+        continue
+    fi
+    echo "Loading $table"
+    gunzip -c "$input" | clickhouse client --port "$PORT" \
+        --query "INSERT INTO $DATABASE.$table FORMAT Native"
+done

oximeter/db/benches/load_field_tables.sh

@@ -0,0 +1,115 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! Benchmark for OxQL query performance.
+//!
+//! Tests multiple timeseries with varying numbers of field types.
+
+// Copyright 2026 Oxide Computer Company
+
+use criterion::BenchmarkId;
+use criterion::Criterion;
+use criterion::{criterion_group, criterion_main};
+use oximeter_db::Client;
+use oximeter_db::oxql::query::QueryAuthzScope;
+use rand::seq::SliceRandom;
+use std::net::IpAddr;
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+const DEFAULT_CLICKHOUSE_PORT: u16 = 9000;
+
+/// Timeseries for field lookup benchmarks, with their field table counts.
+///
+/// Note: we manually select a subset of metrics, spanning the range of field table counts. If we add metrics or change the schemas of existing metrics, we'll need to revisit the selection.
+const FIELD_TIMESERIES: &[(&str, u8)] = &[
+    ("crucible_upstairs:flush", 1),
+    ("ddm_session:advertisements_received", 2),
+    ("virtual_machine:vcpu_usage", 3),
+    ("bgp_session:active_connections_accepted", 4),
+    ("switch_data_link:bytes_sent", 6),
+];
+
+fn get_clickhouse_addr() -> IpAddr {
+    std::env::var("CLICKHOUSE_ADDRESS")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or_else(|| IpAddr::from([127, 0, 0, 1]))
+}
+
+fn get_clickhouse_port() -> u16 {
+    std::env::var("CLICKHOUSE_PORT")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(DEFAULT_CLICKHOUSE_PORT)
+}
+
+fn get_client(rt: &tokio::runtime::Runtime) -> Arc<Client> {
+    let ip = get_clickhouse_addr();
+    let port = get_clickhouse_port();
+    let addr = SocketAddr::new(ip, port);
+    let log = slog::Logger::root(slog::Discard, slog::o!());
+
+    rt.block_on(async {
+        let client = Arc::new(Client::new(addr, &log));
+        client.ping().await.unwrap();
+        client
+    })
+}
+
+// Benchmark field lookup. As of this writing, filtering and collating fields
+// can make up a significant proportion of overall query time, and its latency
+// varies with both the cardinality and the number of field tables that need to
+// be combined for the relevant series. Query each series in FIELD_TIMESERIES,
+// filtering to a future timestamp so that we only benchmark the performance of
+// field lookup, and ignore measurements. Note that the user is responsible for
+// populating ClickHouse with test data.
+fn oxql_field_lookup(c: &mut Criterion) {
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .unwrap();
+
+    let client = get_client(&rt);
+    let mut group = c.benchmark_group("oxql");
+
+    let mut timeseries: Vec<_> = FIELD_TIMESERIES.iter().collect();
+    timeseries.shuffle(&mut rand::rng());
+
+    for (timeseries, field_tables) in timeseries {
+        // Use a far-future timestamp to benchmark field lookup only, with no
+        // measurements.
+        let query =
+            format!("get {} | filter timestamp > @2200-01-01", timeseries);
+
+        rt.block_on(client.oxql_query(&query, QueryAuthzScope::Fleet)).unwrap();
+
+        let bench_id = format!("{}/{}_tables", field_tables, timeseries);
+
+        group.bench_function(
+            BenchmarkId::new("field_lookup", &bench_id),
+            |bench| {
+                let client = client.clone();
+                let query = query.clone();
+                bench.to_async(&rt).iter(|| {
+                    let client = client.clone();
+                    let query = query.clone();
+                    async move {
+                        client.oxql_query(&query, QueryAuthzScope::Fleet).await
+                    }
+                })
+            },
+        );
+    }
+
+    group.finish();
+}
+
+criterion_group!(
+    name = benches;
+    config = Criterion::default().sample_size(50).noise_threshold(0.05);
+    targets = oxql_field_lookup
+);
+
+criterion_main!(benches);