Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ asap_sketchlib = { git = "https://github.com/ProjectASAP/asap_sketchlib", rev =
# Internal workspace crates.
aqpbm-datagen = { path = "aqpbm-datagen" }
aqpbm-core = { path = "aqpbm-core", default-features = false }
aqpbm-engines-external = { path = "aqpbm-engines-external" }
sketch-bench = { path = "sketch-bench" }
aqpbm-usecase = { path = "aqpbm-usecase" }
# sketch-runtime = { path = "sketch-runtime" } # parked;
Expand Down
1 change: 1 addition & 0 deletions aqpbm-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ heap-track = ["sketch-bench/heap-track", "aqpbm-core/heap-track"]
[dependencies]
aqpbm-datagen = { workspace = true, features = ["import"] }
aqpbm-core.workspace = true
aqpbm-engines-external.workspace = true
sketch-bench.workspace = true
clap.workspace = true
serde.workspace = true
Expand Down
41 changes: 38 additions & 3 deletions aqpbm-cli/src/bench_external_cmd.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ use aqpbm_core::harness::protocol::{
load_probe_for, MeasurementClocks, OsCpuClock, ProcessCpuFiles, Protocol,
};
use aqpbm_core::harness::rundir::RunDir;
use aqpbm_engines_external::clickhouse_server::{ClickHouseEngine, ClickHouseServer};
use clap::{Parser, Subcommand};

/// The lanes this binary can run.
pub const LANES: [&str; 1] = ["fake"];
pub const LANES: [&str; 2] = ["fake", "clickhouse"];

#[derive(Parser, Debug)]
pub struct BenchExternalArgs {
Expand All @@ -41,9 +42,23 @@ pub struct RunArgs {
/// The run directory: workloads/, plans/<variant>/, results/.
#[arg(long)]
pub run_dir: PathBuf,
/// The lane: `fake` (the harness's own fake engine).
/// The lane: `fake` (the harness's own fake engine) or `clickhouse`.
#[arg(long)]
pub lane: String,
/// The ClickHouse server's HTTP interface, e.g. `http://10.0.0.1:8123`
/// (lane `clickhouse`).
#[arg(long)]
pub clickhouse_url: Option<String>,
/// The cgroup agent beside the server, e.g. `http://10.0.0.1:9101`
/// (lane `clickhouse`).
#[arg(long)]
pub cgroup_agent_url: Option<String>,
/// `max_threads` of every ClickHouse statement; 1 for the main figures.
#[arg(long, default_value_t = 1)]
pub clickhouse_max_threads: u32,
/// How long one ClickHouse statement may run, in seconds.
#[arg(long, default_value_t = 600)]
pub clickhouse_statement_timeout_s: u64,
/// Only these variants (repeatable); every variant under plans/ by default.
#[arg(long = "variant")]
pub variants: Vec<String>,
Expand Down Expand Up @@ -93,7 +108,27 @@ pub fn run(args: BenchExternalArgs) -> Result<()> {

fn run_lane_cmd(args: RunArgs) -> Result<()> {
let engine: Box<dyn EngineUnderTest> = match args.lane.as_str() {
"fake" => Box::new(FakeEngine::default()),
"fake" => {
if args.clickhouse_url.is_some() || args.cgroup_agent_url.is_some() {
bail!("--clickhouse-url and --cgroup-agent-url are for lane clickhouse only");
}
Box::new(FakeEngine::default())
}
"clickhouse" => {
let (Some(url), Some(cgroup_agent_url)) =
(args.clickhouse_url.clone(), args.cgroup_agent_url.clone())
else {
bail!("lane clickhouse needs --clickhouse-url and --cgroup-agent-url");
};
Box::new(ClickHouseEngine::new(ClickHouseServer {
url,
cgroup_agent_url,
max_threads: args.clickhouse_max_threads,
statement_timeout: std::time::Duration::from_secs(
args.clickhouse_statement_timeout_s,
),
})?)
}
other => bail!("unknown lane '{other}'; known lanes: {}", LANES.join(", ")),
};
let run_dir = RunDir::open(&args.run_dir)?;
Expand Down
25 changes: 24 additions & 1 deletion aqpbm-cli/tests/bench_external_cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ fn an_unknown_lane_names_the_known_lanes() {
"--run-dir",
run.to_str().unwrap(),
"--lane",
"clickhouse",
"victoriametrics",
]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
Expand All @@ -162,3 +162,26 @@ fn an_unknown_lane_names_the_known_lanes() {
);
let _ = std::fs::remove_dir_all(run.parent().unwrap());
}

/// X3: the clickhouse lane needs the server and its cgroup agent.
#[test]
fn the_clickhouse_lane_needs_its_server() {
let run = fixture("x3");
let out = approxbench(&[
"bench-external",
"run",
"--run-dir",
run.to_str().unwrap(),
"--lane",
"clickhouse",
"--clickhouse-url",
"http://10.0.0.2:8123",
]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(
stderr.contains("--clickhouse-url") && stderr.contains("--cgroup-agent-url"),
"{stderr}"
);
let _ = std::fs::remove_dir_all(run.parent().unwrap());
}
2 changes: 2 additions & 0 deletions aqpbm-engines-external/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,7 @@ repository.workspace = true
description = "Runs ASAPPlanner plan files on external engines: reads an InstallablePlan file (wire version 15) and translates it into ClickHouse materialized views and SQL. The translator is the capability check: a node it has no rule for is refused. Depends on no ASAPPlanner crate."

[dependencies]
aqpbm-core.workspace = true
serde_json.workspace = true
ureq = { version = "2", default-features = false }
thiserror.workspace = true
16 changes: 16 additions & 0 deletions aqpbm-engines-external/capabilities/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,22 @@ Prometheus `extrapolatedRate` is cited at v3.15.1.

A stored read is right only at a window end, so a query that reads stored windows fails (`throwIf`) at any other evaluation time. Every insert uses `INSERT_SETTINGS`, so a NULL value is an error instead of 0. The sketch rows above give each sketch's class. The ClickHouse files list no sketch yet, because the translator does not build sketch states yet; each sketch joins `supported_summaries` in the PR that adds its translation rule.

**Conformance on a server.** `tests/clickhouse_conformance.rs` (`#[ignore]`, `AQPBM_CLICKHOUSE_URL` and `AQPBM_CGROUP_AGENT_URL`) runs one case per row through the engine adapter (`clickhouse_server`) against a real server, with hand-computed answers:

| Row | Case |
|---|---|
| stored Sum / Count / Min / Max | `stored_sum_count_min_max` |
| stored Rate / Increase (b) | `stored_rate_is_promql_minus_the_first_value_after_each_reset` (three installs fed in turn, max_threads 1 and 16) |
| query-time Rate / Increase; raw samples retained | `query_time_rate_is_promql` |
| query-time grouped sums; `Aggregate` | `grouped_sums_quantiles_and_aggregates` |
| instant selector | `instant_selector` |
| top_k | `top_k_ties_and_nan` |
| regrouping merges, `Project`, `BinaryOp`, checked division | `average_as_sum_over_count_and_checked_division` |
| IRate; query-time results kept across evaluations (c) | `class_c_rows_are_refused` |
| raw samples retained (stored-only metric); retention | `storage_and_retention` |
| window boundary (left-open) | `the_harness_conformance_kit_passes` |
| sketches | not yet: no sketch rule |

## VictoriaMetrics

The VictoriaMetrics translator comes in a later PR. Until then, these files are the planned capabilities and are checked only by the planner run in the PR's manual check.
Expand Down
55 changes: 43 additions & 12 deletions aqpbm-engines-external/src/clickhouse.rs
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ use crate::{NodeId, SharingLost, Substitution, TranslationError};
/// The plan's series identity column, a label column like any other. It has
/// one value per series, so it is a plain `String`: `LowCardinality` pays
/// off only below about ten thousand distinct values.
const SERIES_IDENTITY: &str = "$promql_series_identity";
pub const SERIES_IDENTITY: &str = "$promql_series_identity";

/// The settings every `INSERT` into a source table uses: a NULL value is an
/// error instead of being stored as 0 (PromQL samples are never NULL), in
Expand All @@ -62,6 +62,11 @@ pub const INSERT_SETTINGS: &str = "input_format_null_as_default = 0, insert_null
pub struct ClickHouseDeployment {
/// `CREATE TABLE` statements: one per metric, then one per stored chain.
pub tables: Vec<String>,
/// The source table of each metric, in the order of `tables`: where its
/// samples are inserted.
pub sources: Vec<SourceTable>,
/// The tables of the stored chains (`v<node>`), in the order of `tables`.
pub stored_tables: Vec<String>,
/// `CREATE MATERIALIZED VIEW` statements, one per stored chain.
pub materialized_views: Vec<String>,
/// One `SELECT` per query root, in root order, with the parameter `{t:Int64}`.
Expand All @@ -77,6 +82,16 @@ pub struct ClickHouseDeployment {
pub sharing_lost: Vec<SharingLost>,
}

/// A metric's source table: samples of `metric` (their `__name__`) are
/// inserted into `table`, with one column per label of `label_columns`, in
/// that order, the series identity last.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceTable {
pub metric: String,
pub table: String,
pub label_columns: Vec<String>,
}

/// A table's retention: rows whose time is older than `retention_ms` before
/// the newest evaluation are no longer read.
#[derive(Debug, Clone, PartialEq, Eq)]
Expand Down Expand Up @@ -136,12 +151,15 @@ pub fn translate(plan: &PlanFile) -> Result<ClickHouseDeployment, TranslationErr
queries.push(relation.sql);
query_time_steps_ms.push(relation.step_ms);
}
let mut tables = source_tables(plan);
let (sources, mut tables): (Vec<SourceTable>, Vec<String>) =
source_tables(plan).into_iter().unzip();
let mut stored_tables = Vec::new();
let mut table_retention = source_retention(plan);
let mut materialized_views = Vec::new();
let mut substitutions = Vec::new();
for chain in translator.chains.values() {
tables.push(chain.table());
stored_tables.push(chain.table_name());
materialized_views.push(chain.view());
if let Some(retention_ms) = chain.retention_ms {
table_retention.push(TableRetention {
Expand All @@ -161,6 +179,8 @@ pub fn translate(plan: &PlanFile) -> Result<ClickHouseDeployment, TranslationErr
}
}
Ok(ClickHouseDeployment {
sources,
stored_tables,
tables,
materialized_views,
queries,
Expand Down Expand Up @@ -366,7 +386,7 @@ fn over_values(function: &str) -> String {
/// primary key; a `minmax` index on `ts` skips the granules outside a time
/// range. A metric only stored chains read keeps no rows (`ENGINE = Null`):
/// its materialized views still see every insert.
fn source_tables(plan: &PlanFile) -> Vec<String> {
fn source_tables(plan: &PlanFile) -> Vec<(SourceTable, String)> {
struct SourceColumns<'a> {
metric: &'a str,
labels: Vec<&'a str>,
Expand Down Expand Up @@ -421,10 +441,18 @@ fn source_tables(plan: &PlanFile) -> Vec<String> {
.map(|label| format!(", {} {}", quoted(label), label_type(label)))
.collect();
let table = source_table(source.metric);
let described = SourceTable {
metric: source.metric.to_string(),
table: table.clone(),
label_columns: source.labels.iter().map(|l| l.to_string()).collect(),
};
if !source.keeps_rows {
return format!(
"CREATE TABLE {table} (ts DateTime64(3, 'UTC'), value Float64{columns}) \
ENGINE = Null"
return (
described,
format!(
"CREATE TABLE {table} (ts DateTime64(3, 'UTC'), value Float64{columns}) \
ENGINE = Null"
),
);
}
let sorting_key: Vec<String> = source
Expand All @@ -434,11 +462,14 @@ fn source_tables(plan: &PlanFile) -> Vec<String> {
.map(|label| quoted(label))
.chain(["ts".to_string()])
.collect();
format!(
"CREATE TABLE {table} (ts DateTime64(3, 'UTC'), value Float64{columns}, \
INDEX ts_minmax ts TYPE minmax GRANULARITY 1) \
ENGINE = MergeTree ORDER BY ({})",
sorting_key.join(", ")
(
described,
format!(
"CREATE TABLE {table} (ts DateTime64(3, 'UTC'), value Float64{columns}, \
INDEX ts_minmax ts TYPE minmax GRANULARITY 1) \
ENGINE = MergeTree ORDER BY ({})",
sorting_key.join(", ")
),
)
})
.collect()
Expand Down Expand Up @@ -1416,7 +1447,7 @@ fn column_list(labels: &[String]) -> String {
.join(", ")
}

fn quoted(identifier: &str) -> String {
pub(crate) fn quoted(identifier: &str) -> String {
format!("`{}`", identifier.replace('\\', "\\\\").replace('`', "\\`"))
}

Expand Down
Loading