diff --git a/README.md b/README.md index c4ea78f18..3c6c4cc97 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ASAPPlanner turns SQL, PromQL, and MetricsQL query workloads into legal candidat - New to the repository? Read the [planner pipeline](docs/design_docs/concepts/planner-pipeline.md), then the [glossary](docs/design_docs/concepts/glossary.md). - Want to run a query? Follow [Run and inspect a query](docs/user_guide_docs/run-a-query.md). -- Want to see how a workload is planned, stage by stage? Use the [Stage Viewer](docs/user_guide_docs/stage-viewer.md). +- Want to see how a workload is planned, stage by stage? Use the [Plan Viewer](docs/user_guide_docs/plan-viewer.md). - Embedding Planner? Use the [library API guide](docs/develop_docs/library-api.md). - Extending Planner? Read the [planning stages design](docs/design_docs/proposals/planner-layering.md), then the [ASAP-aware mapping architecture](docs/develop_docs/asap-aware-mapping-architecture.md), which maps each stage to its code, then [extend ASAP-aware mapping](docs/develop_docs/extend-asap-aware-mapping.md). - Evaluating a design? Browse the [design documentation](docs/design_docs/README.md), [developer documentation](docs/develop_docs/README.md), and [user guides](docs/user_guide_docs/README.md). diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index c527319a6..37068f8f4 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -8,7 +8,7 @@ // `--run-until` (`stage0`, `stage1_pass1`, `stage1_pass2`, `stage2` or // `stage3`) and writes each stage's output, as text (`--format text`, the default; // `asap_devtools::planning_stages_text`) or as an `asap-stage-pipeline/v2` -// document for the Stage Viewer (`--format json`), to `--out` or standard +// document for the Plan Viewer (`--format json`), to `--out` or standard // output. The text is terse by default (a legend per stage, folded θ // variants, producer ids per input, pruned counts per cause); `--verbose` // prints every candidate, edge with its reason, group's properties and diff --git a/docs/README.md b/docs/README.md index 4ef582c9b..49c2dcfd4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,7 +11,7 @@ Choose the path that matches what you need to do. ## Run or inspect a query -Follow [Run and inspect a query](user_guide_docs/run-a-query.md). To see how the planner plans a workload stage by stage, and why it selects its plan, use [the Stage Viewer](user_guide_docs/stage-viewer.md). +Follow [Run and inspect a query](user_guide_docs/run-a-query.md). To see how the planner plans a workload stage by stage, and why it selects its plan, use [the Plan Viewer](user_guide_docs/plan-viewer.md). ## Embed the library diff --git a/docs/design_docs/architecture/README.md b/docs/design_docs/architecture/README.md index a521d7e3f..a7b556916 100644 --- a/docs/design_docs/architecture/README.md +++ b/docs/design_docs/architecture/README.md @@ -51,7 +51,7 @@ target. | Plan selection | `stage3-plan-selection` | Stage 3: accuracy and latency checks, costing and selection; the planning models and the Stage 1 to Stage 3 driver | | Planner facade | `planner` | `e2e_plan`: Stage 0 followed by Stages 1–3 | | Executor | `executor` | Stage 4: runs a `PhysicalASAPDAG` over `asap_sketchlib` summaries; no stage crate depends on it | -| Developer inspection | `devtools` | `asap_planner` and the Stage Viewer documents, corpus coverage tools | +| Developer inspection | `devtools` | `asap_planner` and the Plan Viewer documents, corpus coverage tools | | End-to-end validation | `integration-tests` | Verify behavior across frontends, stages and execution | ## Inputs and outputs diff --git a/docs/design_docs/architecture/input-output-workflow.md b/docs/design_docs/architecture/input-output-workflow.md index a148a9425..da5a8e08e 100644 --- a/docs/design_docs/architecture/input-output-workflow.md +++ b/docs/design_docs/architecture/input-output-workflow.md @@ -304,7 +304,7 @@ PlanningWorkload + frontend dependencies + PlanningModels |---|---|---| | Plan a workload end to end | `asap_planner::e2e_plan` | `PlanOutput` | | Plan already-lowered roots and inspect every stage | `asap_planner::run_planning` | `PlanningRun`, whose `selection` is the `Selection` | -| Inspect a workload's stages as a document | `asap_planner` (devtools) | The stage document the [Stage Viewer](../../user_guide_docs/stage-viewer.md) shows | +| Inspect a workload's stages as a document | `asap_planner` (devtools) | The stage document the [Plan Viewer](../../user_guide_docs/plan-viewer.md) shows | The integration associates each lowered root, by its position, with its workload entry (accuracy target, latency bound, recurrence). See the diff --git a/docs/design_docs/proposals/planner-layering-example2-acceptance.md b/docs/design_docs/proposals/planner-layering-example2-acceptance.md index 5c1d0dec8..454736fce 100644 --- a/docs/design_docs/proposals/planner-layering-example2-acceptance.md +++ b/docs/design_docs/proposals/planner-layering-example2-acceptance.md @@ -159,5 +159,5 @@ strictest size. is the `flows` table of `tools/dag-viewer/workloads/planner-layering/tables.json`, plans the SQL workload with the `flows(ts, src_ip)` catalog (with `--ignore-accuracy-guarantees`, none of the plans below is rejected for its -guarantee). The stage viewer has no tab for it; open the +guarantee). The plan viewer has no tab for it; open the document with **Open stage document…**. diff --git a/docs/develop_docs/extend-asap-aware-mapping.md b/docs/develop_docs/extend-asap-aware-mapping.md index 43248f3e4..306493991 100644 --- a/docs/develop_docs/extend-asap-aware-mapping.md +++ b/docs/develop_docs/extend-asap-aware-mapping.md @@ -105,7 +105,7 @@ tests in `planner_layering_example4.rs`. a stage function takes only the field it reads (Stage 2 takes `query_time_results_retained: bool`, not the whole struct). - Expose it in `asap_planner` and in the - [Stage Viewer guide](../user_guide_docs/stage-viewer.md). + [Plan Viewer guide](../user_guide_docs/plan-viewer.md). Tests: a Stage 3 unit test that the check rejects exactly the candidates it should, and a `crates/devtools/tests/asap_planner.rs` test for the flag. diff --git a/docs/develop_docs/library-api.md b/docs/develop_docs/library-api.md index ef3f59c66..259342ea6 100644 --- a/docs/develop_docs/library-api.md +++ b/docs/develop_docs/library-api.md @@ -295,7 +295,7 @@ let models = PlanningModels::builtin().with_cost_inputs(&settings); The `asap_planner` devtool runs the same stages and writes every stage's output as text or, with `--format json`, as one JSON document; see the -[Stage Viewer guide](../user_guide_docs/stage-viewer.md). +[Plan Viewer guide](../user_guide_docs/plan-viewer.md). ## Workload inputs and defaults diff --git a/docs/develop_docs/replacement-explanations.md b/docs/develop_docs/replacement-explanations.md index 93e69f094..0d29527bd 100644 --- a/docs/develop_docs/replacement-explanations.md +++ b/docs/develop_docs/replacement-explanations.md @@ -5,7 +5,7 @@ > and why each candidate was pruned or rejected, is now in the stages' > output: Pass 1's pruned candidates with their `PruneReason`, Stage 2's > pruned candidates, and Stage 3's `Rejection` reasons, all written by -> `asap_planner` (see the [Stage Viewer guide](../user_guide_docs/stage-viewer.md)). +> `asap_planner` (see the [Plan Viewer guide](../user_guide_docs/plan-viewer.md)). ASAP-aware mapping should make its discovered opportunities visible to users and other components. diff --git a/docs/user_guide_docs/README.md b/docs/user_guide_docs/README.md index 4cee670dd..841b9f765 100644 --- a/docs/user_guide_docs/README.md +++ b/docs/user_guide_docs/README.md @@ -5,4 +5,4 @@ result. - [Run and inspect a query](run-a-query.md) - [Plan a workload with asap_planner](asap-planner.md) -- [See how ASAPPlanner plans a workload: the Stage Viewer](stage-viewer.md) +- [See how ASAPPlanner plans a workload: the Plan Viewer](plan-viewer.md) diff --git a/docs/user_guide_docs/asap-planner.md b/docs/user_guide_docs/asap-planner.md index 1eb1e2234..36990ced3 100644 --- a/docs/user_guide_docs/asap-planner.md +++ b/docs/user_guide_docs/asap-planner.md @@ -2,7 +2,7 @@ `asap_planner` runs the planner's stages on a workload, up to the stage you choose, and prints what each stage produced: as text, or as a JSON document -for the [Stage Viewer](stage-viewer.md). It reports candidates, selection, +for the [Plan Viewer](plan-viewer.md). It reports candidates, selection, modeled costs and accuracy checks; it does not deploy or execute the plan. ## Build and run @@ -100,7 +100,7 @@ SQL examples. To try a single query, write a one-query workload file. ## Inspect the result With `--format json`, open the document in the -[Stage Viewer](stage-viewer.md), or read Stage 3 directly: +[Plan Viewer](plan-viewer.md), or read Stage 3 directly: ```sh cargo run --release -p asap-devtools --bin asap_planner -- \ diff --git a/docs/user_guide_docs/stage-viewer.md b/docs/user_guide_docs/plan-viewer.md similarity index 97% rename from docs/user_guide_docs/stage-viewer.md rename to docs/user_guide_docs/plan-viewer.md index 2d915fba7..5a1c47535 100644 --- a/docs/user_guide_docs/stage-viewer.md +++ b/docs/user_guide_docs/plan-viewer.md @@ -1,6 +1,6 @@ -# See how ASAPPlanner plans a workload: the Stage Viewer +# See how ASAPPlanner plans a workload: the Plan Viewer -The Stage Viewer is a web page that shows what ASAPPlanner does with one +The Plan Viewer is a web page that shows what ASAPPlanner does with one workload at each [planning stage](../design_docs/proposals/planner-layering.md#asapplanner-system-overview-planning-stages), and which plan it selects. It reads one JSON document per workload, written diff --git a/docs/user_guide_docs/run-a-query.md b/docs/user_guide_docs/run-a-query.md index c1c19059c..085330f91 100644 --- a/docs/user_guide_docs/run-a-query.md +++ b/docs/user_guide_docs/run-a-query.md @@ -14,7 +14,7 @@ tool on first use. | Command (`cargo run -p asap-devtools --bin … -- …`) | Input / options | Result | | --- | --- | --- | -| `asap_planner --workload --run-until ` | `PlanningWorkload` JSON files | Runs the planner's stages up to `` and prints each stage's output as text, or with `--format json` as the document the [Stage Viewer](stage-viewer.md) shows | +| `asap_planner --workload --run-until ` | `PlanningWorkload` JSON files | Runs the planner's stages up to `` and prints each stage's output as text, or with `--format json` as the document the [Plan Viewer](plan-viewer.md) shows | | `convert_rqe_atomic_costs ` | sketch-bench's per-operation cost table | Writes a measured table to set as `measured_operation_costs` in an `asap_planner --cost-inputs` file; skipped rows are listed on stderr | | `analyze_corpora --corpora --sample-interval-ms 1000 --out-dir ` | Repository PromQL corpora, output directory | Writes successful/error IR dumps and summary reports | | `analyze_corpora --sql-corpora --out-dir ` | Repository SQL corpora, output directory | Writes SQL corpus reports | @@ -49,7 +49,7 @@ the selected physical candidates, the plan's `cost_per_second` with each node's charge, each query's accepted accuracy, and the search status (`Optimal` when the plan is proven the cheapest). For this example the selected plan is exact for both queries. Add `--format json --out plan.json` -and open the document in the [Stage Viewer](stage-viewer.md) to see every +and open the document in the [Plan Viewer](plan-viewer.md) to see every stage. ## Inspect a query's logical DAG diff --git a/tools/dag-viewer/README.md b/tools/dag-viewer/README.md index d4a7f207b..a13f906e7 100644 --- a/tools/dag-viewer/README.md +++ b/tools/dag-viewer/README.md @@ -1,4 +1,4 @@ -# ASAPPlanner Stage Viewer +# ASAPPlanner Plan Viewer A browser view of what the planner does with one workload, read from an `asap-stage-pipeline/v2` document written by the `asap_planner` devtool @@ -31,24 +31,27 @@ To run it, see [RUNNING.md](RUNNING.md). (deployment capabilities, cost model, accuracy guarantees). Without the server, the rows say they need it. `#workload-sets` in the URL opens the section. -- **Query workload** with each query's accuracy, latency, recurrence, - predictability and range evaluation, and a line that counts the - candidates at each stage: the Pass 2 memo's logical candidates and how +- **Planner inputs** (blue bar), what the planner was given: + - **Query workload** with each query's accuracy (`error metric not set` when + the workload names no error metric), latency, recurrence, + predictability and range evaluation; + - **Data workload**: the arrival and one row per declared source with + exactly the facts it declares (series count, metric type, non-negative + values, sample interval, stream norms, distinct bound, distinct values + per label, distinct values per label set) and the queries whose text + names it; + - **Deployment and planner settings**: the deployment capabilities (raw + data and query-time results retained or not, the summaries it + supports), whether accuracy guarantees were enforced or ignored, and + the cost model Stage 3 priced the plan with (`cost.source`). +- **Planner output** (green bar), everything below: a line that counts the + candidates at each stage (the Pass 2 memo's logical candidates and how many Pass 2 pruned, the physical candidates and how many Stage 2 and - Stage 3 pruned, and whether a plan was selected. -- **Data workload** beside it: the arrival and one row per declared source - with exactly the facts it declares (series count, metric type, - non-negative values, sample interval, stream norms, distinct bound, - distinct values per label, distinct values per label set) and the queries - whose text names it, plus the deployment capabilities the run planned - with. -- **Stage 3 · plan selection**: one row, the selected plan with its cost - per second and the accuracy Stage 3 accepted per query, or why no plan - was selected. The header says why Stage 1 or Stage 2 failed when it did, - shows the selection's warnings, says whether accuracy guarantees were - enforced or ignored, and names the search with its MILP's size and times. -- **Two lanes**, stacked top to bottom so each is as wide as the page: - Stage 0 and Stage 3's plan, with each plan node's timing (also its fill: + Stage 3 pruned) and a line with Stage 3's outcome (plan selected, or why + not), why Stage 1 or Stage 2 failed when it did, the selection's + warnings, and the search with its MILP's size and times. +- **Two lanes**, each as wide as the page: **Input**, the queries as one + logical DAG (Stage 0's output, drawn with the inputs), and Stage 3's plan, with each plan node's timing (also its fill: green at ingestion time, orange at query time) and Stage 3 cost (`× n` when a node that is not materialized is computed once per consumer). Each lane is the whole workload's DAG, so a node shared by several queries @@ -68,13 +71,27 @@ To run it, see [RUNNING.md](RUNNING.md). is not installable says why instead. Clicking a row selects its node in the plan lane. - **Memo**: the memo after each planner step, one tab per step (`Stage 0`, - `Stage 1, Pass 1`, `Stage 1, Pass 2`), opening on the last. Each memo + `Stage 1 · Pass 1`, `Stage 1 · Pass 2`), opening on the last. Each memo group is a box `G ·