Skip to content

Commit d4b196b

Browse files
zzylolzzylol
authored
Merge pull request #512 from ProjectASAP/docs/asapplanner-system-integration
docs: ASAPPlanner and ASAPQuery-backend integration architecture
2 parents 3ca9828 + d7aa5de commit d4b196b

4 files changed

Lines changed: 629 additions & 5 deletions

File tree

‎docs/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,11 @@ The end-to-end architecture and shared contracts are maintained centrally in
1111
That documentation owns collection, transmission, backend ingest/storage/query,
1212
SID, physical plans, workload inputs, and runtime feedback.
1313

14-
This repository keeps only code-owned implementation guidance and user-facing
15-
backend operation material.
14+
This repository keeps code-owned implementation guidance, user-facing backend
15+
operation material, and a scoped
16+
[ASAPPlanner integration proposal](design_docs/asapplanner-integration.md)
17+
covering architecture boundaries, workflow, and high-level migration without
18+
duplicating the canonical cross-component contracts.
1619

1720
## Getting started
1821

‎docs/design_docs/README.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,15 @@ Backend-specific implementation design notes are organized by component under
88
[`../developer_docs`](../developer_docs/README.md). They explain current Rust
99
internals and are subordinate to the shared system contracts.
1010

11-
Proposals for shared-contract review (not duplicate normative specifications):
11+
Proposals for shared-contract review:
1212

13-
- [Self-Describing Summary (SDS)](self-describing-summary.md): Schema,
14-
Dictionary and Record structure definitions.
13+
- [ASAPPlanner integration architecture](asapplanner-integration.md) proposes
14+
the Planner/backend responsibility boundary, shared semantic DAG workflow,
15+
and high-level consolidation milestones.
16+
- [Self-Describing Summary (SDS)](self-describing-summary.md) defines the proposed
17+
Summary Descriptor, Data Descriptor and Summary Instance layers.
18+
19+
These proposals complement the canonical cross-component contracts above.
1520

1621
Backend-specific operating profiles:
1722

‎docs/design_docs/asapplanner-integration.md‎

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
# ASAPPlanner and ASAPQuery-backend: integrated architecture
2+
3+
Status: proposed system-level consolidation and high-level migration, grounded
4+
in existing integration. This is not a claim that every target capability is
5+
implemented. No repository rename is proposed.
6+
7+
This document owns the Planner/backend integration proposal, not a second copy
8+
of the [shared ASAP system contracts](https://github.com/ProjectASAP/ASAPCollector/tree/main/docs/design_docs).
9+
The existing physical-plan, collection, transmission, and storage contracts
10+
remain authoritative for their respective interfaces.
11+
12+
## Design decision
13+
14+
<p align="center"><strong>Figure 1. Integrated ASAPPlanner–ASAPQuery-backend architecture and workflow.</strong></p>
15+
16+
```mermaid
17+
flowchart TD
18+
subgraph PlannerBoundary["ASAPPlanner boundary — reusable optimization"]
19+
Canonical[Canonical QueryExpr and workload semantics]
20+
Canonical --> Strategies[CSE and reusable replacement strategies]
21+
Strategies --> Candidates[Candidate post-ASAP workload DAGs]
22+
Candidates --> Ranking[Semantic legality, accuracy and evidence-based ranking]
23+
end
24+
25+
subgraph BackendBoundary["ASAPQuery-backend boundary — observability application"]
26+
Inputs[PromQL registrations, QueryWorkload and DataWorkload]
27+
Evidence[Runtime capabilities and complete deployment cost evidence]
28+
Commit[Control plane commits a feasible post-ASAP workload DAG]
29+
Compile[Physical binding and deployment selection]
30+
Bundle[One versioned physical plan bundle]
31+
Activate[Validate, stage and activate]
32+
Precompute[Ingest, precompute and summary store]
33+
Serve[Bound query execution and explicit exact fallback]
34+
Feedback[Readiness, accuracy and resource observations]
35+
Inputs --> Commit
36+
Commit --> Compile --> Bundle --> Activate
37+
Activate --> Precompute
38+
Activate --> Serve
39+
Precompute --> Serve
40+
Precompute --> Feedback
41+
Serve --> Feedback
42+
Feedback --> Evidence
43+
end
44+
45+
Inputs -->|Planning request| Canonical
46+
Candidates -->|Implementation evaluation request| Evidence
47+
Evidence -->|Feasibility and cost evidence| Ranking
48+
Ranking -->|Legal ranked post-ASAP alternatives| Commit
49+
Bundle -->|CollectorPlan in distributed profile| Collector[ASAPCollector — external runtime]
50+
Collector -->|Planned data or summary frames| Precompute
51+
Clients[PromQL clients] --> Serve
52+
Serve -->|Configured exact route| Exact[Prometheus or archive query service]
53+
```
54+
55+
**ASAPPlanner's selected post-ASAP workload DAG is the authoritative semantic
56+
plan. ASAPQuery-backend binds and executes that decision through its control
57+
plane and data plane.** Backend physical plans remain necessary, but must be
58+
traceable projections of that DAG, not independently optimized replacements
59+
for its dependencies, shared state, or query-result semantics.
60+
61+
Planner provides reusable legal alternatives and ranking. The backend owns
62+
deployment commitment, concrete realization, and operational policy. A
63+
deployment choice cannot silently change Planner-owned grouping, statistic,
64+
summary parameters, logical window, accuracy, or lifecycle: it must return to
65+
the legal candidate-selection boundary.
66+
67+
## Architecture boundaries and reuse
68+
69+
ASAPQuery-backend is the observability downstream application, including the
70+
MetricsObservabilityQuery use case. DQC (the proposed name for the current
71+
asap-fusion repository) is a separate downstream application, not an execution
72+
dependency of this backend.
73+
74+
| Responsibility | ASAPPlanner | ASAPQuery-backend |
75+
| --- | --- | --- |
76+
| Query semantics | Canonical expressions, equivalence, grouping and time semantics | PromQL API, workload registration and profile restrictions |
77+
| Optimization | CSE, legal sharing, rollup, decomposition, summary and accuracy alternatives | Feasibility evidence, deployment commitment and concrete assignments |
78+
| Time and state | Logical windows, abstract window framework and maintenance lifecycle | Panes, retention layout, update implementation and placement |
79+
| Plan identity | Logical producer identities and result dependencies | Plan versions, physical materializations, SID bindings and runtime handles |
80+
| Execution | Deployment-independent semantic contract | Ingest, precompute, store, serving, readiness and fallback |
81+
| Operations | Reusable models consuming scoped evidence | Activation, rollback, telemetry, freshness and resource enforcement |
82+
83+
Reuse works in both directions. The backend consumes Planner strategies;
84+
general-purpose rules discovered while optimizing repeated observability
85+
queries belong in Planner so DQC and other applications can reuse them.
86+
Prometheus staleness handling, SID resolution, Collector placement, and OpAMP
87+
publication remain downstream responsibilities.
88+
89+
## Inspection: what already exists
90+
91+
Inspected backend main at
92+
[`95131d83972bb7a07d338e2a5af925a20c15ddce`](https://github.com/ProjectASAP/ASAPQuery-backend/tree/95131d83972bb7a07d338e2a5af925a20c15ddce),
93+
using its pinned Planner revision
94+
[`cb50219c582d43f53ab77d3a595bd1ea4a9aa119`](https://github.com/ProjectASAP/ASAPPlanner/tree/cb50219c582d43f53ab77d3a595bd1ea4a9aa119).
95+
The baseline is merged code, not the completion of open PRs.
96+
97+
| Area | Existing foundation | Consolidation needed |
98+
| --- | --- | --- |
99+
| Frontend and selection | Planner dependency, canonical query parsing, backend selection from Planner alternatives | Make workload-wide sharing and strategy composition explicit across supported entry points |
100+
| Physical compilation | One bundle with precompute, transmission, backend and query projections; Collector projections when applicable | Preserve all selected shared producers and provenance through every projection |
101+
| Serving | Bound QueryPlan execution, exact materialization identities and explicit fallback | Audit remaining compatibility paths; serving must not make a new summary choice |
102+
| Deployment | Versioned staging and activation, runtime capability and evidence checks | Verify profile-specific failure and readiness behavior end to end |
103+
| Compatibility | Backend-local ASAPQuery profile alongside distributed collection | Keep distinct deployment profiles on the same semantic contract |
104+
105+
Evidence:
106+
[selection adapter](../../control_plane/src/planner_selection.rs),
107+
[physical compiler](../../control_plane/src/physical/compiler.rs),
108+
[legacy workload adapter](../../control_plane/src/physical/workload_planner.rs),
109+
[QueryPlan](../../control_plane/src/query_plan.rs), and
110+
[bound serving executor](../../data_plane/src/query_engines/asap_query_engine/post_asap_readout.rs).
111+
The selection adapter explicitly commits a ranked Planner candidate downstream.
112+
Consequently, the figure does not imply that the Planner library deploys or
113+
commits a complete backend configuration by itself.
114+
115+
This is an extension of existing integration, not a proposal to replace it
116+
wholesale. Implementation guides sometimes describe a broader target than an
117+
individual runtime path supports; migration acceptance must be demonstrated
118+
against executable paths, not inferred from interface names.
119+
120+
## One authoritative semantic DAG, derived runtime plans
121+
122+
The shared contract must preserve sources and filters, label/grouping identity,
123+
exact operators surrounding summaries, summary build/merge/readout, shared
124+
producers, query roots, logical time coverage, accuracy, and maintenance
125+
requirements. Audit the pinned post-ASAP representation for genuine gaps;
126+
extend Planner semantics where necessary.
127+
128+
Do not put concrete engine or implementation IDs into Planner IR. The backend
129+
retains a binding from logical producer identity to implementation, placement,
130+
materialization, state schema, and active generation. This follows the
131+
[Planner/downstream boundary](https://github.com/ProjectASAP/ASAPPlanner/blob/cb50219c582d43f53ab77d3a595bd1ea4a9aa119/docs/design_docs/asapplanner-downstream-boundary.md).
132+
133+
One selected DAG can produce several execution projections:
134+
135+
- PrecomputePlan: how the selected state is built and maintained.
136+
- TransmissionPlan and optional CollectorPlan: how distributed producers
137+
implement and deliver that state.
138+
- BackendPlan: compatible storage, catalog and routing bindings.
139+
- QueryPlan: executable reads, merges, readouts and remaining exact operations.
140+
141+
These projections may expand one semantic node into several physical tasks.
142+
They must not invent a different semantic sharing graph. QueryPlan need not be
143+
a byte-for-byte serialization of post-ASAP IR, nor should ingestion and query
144+
serving literally run an identical task schedule. They implement different
145+
phases of the same selected computation.
146+
147+
Sharing has explicit scope: maintain a shared producer once per compatible
148+
source/window/plan generation; reuse its state across query roots. Memoizing a
149+
query DAG within one request is useful but does not, by itself, prove
150+
cross-query or cross-request sharing.
151+
152+
## End-to-end workflow
153+
154+
1. **Register demand.** Collect canonical queries, evaluation cadence, time
155+
windows, accuracy scope, source arrival facts and optimization horizon.
156+
2. **Generate alternatives.** Planner applies legal rewrites and sharing,
157+
choosing among summary, abstract-window and lifecycle alternatives.
158+
3. **Evaluate implementations.** The backend checks runtime feasibility and
159+
supplies complete, fresh costs over the same workload horizon.
160+
4. **Commit and bind.** The control plane selects a legal workload alternative,
161+
retains its concrete realization, and compiles one coherent plan bundle.
162+
5. **Publish.** Validate and stage matching projections. For distributed
163+
deployment, require the corresponding Collector application evidence
164+
before activation. A failed rollout preserves the prior active generation.
165+
6. **Maintain and serve.** Ingest updates the selected state; a request uses one
166+
active snapshot and exact bindings. Warm execution requires complete,
167+
fresh coverage. Otherwise follow the configured exact route or return an
168+
explicit failure if that route is unavailable.
169+
7. **Observe and replan.** Attribute cost, readiness and accuracy evidence to
170+
the plan generation and producer. Semantic changes require a new planning
171+
decision and activation, not an ad-hoc serving-time substitution.
172+
173+
The backend-local profile uses Remote Write, local precompute and Prometheus
174+
fallback without requiring Collector/OpAMP. The distributed profile may use
175+
Collector-maintained summaries and configured archive services. Neither
176+
profile's optional infrastructure becomes a prerequisite for the other.
177+
178+
## Example: repeated dashboard queries sharing one state producer
179+
180+
Consider a gauge `request_size_bytes`, one scalar series per
181+
`(service, instance)`, without extra labels. Register these instant-query
182+
expressions repeatedly at the same evaluation cadence:
183+
184+
```promql
185+
# Q1: sum of observed sample values per service over the last five minutes
186+
sum by (service) (sum_over_time(request_size_bytes[5m]))
187+
188+
# Q2: sample-weighted mean per service over that same interval
189+
sum by (service) (sum_over_time(request_size_bytes[5m]))
190+
/
191+
sum by (service) (count_over_time(request_size_bytes[5m]))
192+
```
193+
194+
Q2 is deliberately not the unweighted mean of per-instance means. Its
195+
denominator counts actual observations, which matters when instances have
196+
different sample counts. These are gauge samples, not counter increases.
197+
198+
A legal target alternative is:
199+
200+
```text
201+
Selected samples and logical five-minute coverage
202+
|
203+
Shared state per (service, instance)
204+
SUM(value), COUNT(observations)
205+
|
206+
Merge/reduce by service
207+
SUM(sum), SUM(count)
208+
|
209+
+------+------+
210+
| |
211+
sum -> Q1 sum / count -> Q2
212+
```
213+
214+
Planner recognizes the common sum computation and can propose aggregate-state
215+
fusion with per-consumer readouts. The backend implements the selected window
216+
framework with compatible runtime state and binds both query roots to the
217+
same producer. It must preserve PromQL range boundaries, labels, absent-series
218+
behavior and division semantics; a missing denominator is not invented as
219+
zero. Physical panes may be used only when their coverage matches the selected
220+
logical interval, including boundary handling.
221+
222+
This diagram is a target acceptance example, not a claim that today's compiler
223+
already fuses these complete PromQL expressions. If an operator or window
224+
cannot be realized end to end, the current supported behavior is explicit
225+
fallback rather than partial warm execution with changed semantics.
226+
227+
For the first milestone, use exact sum/count state and compare against
228+
Prometheus at identical timestamps. Verify both numerical/label equivalence
229+
and one maintained producer shared by the two roots. Exact aggregate state
230+
does not eliminate the separate requirement to verify data completeness.
231+
232+
Approximate extensions must declare what epsilon measures and what delta
233+
covers. For a whole 20-row result with failure probability at most 0.05,
234+
20 valid per-row failure bounds of at most 0.0025 suffice by the union bound;
235+
independence is not required. Per-row 95% intervals alone do not establish
236+
95% confidence for the complete result. Multiple dashboard evaluations need
237+
their own declared scope; a result-level guarantee is not automatically
238+
session-wide. Shared state also does not make separate errors independent.
239+
240+
## Capabilities, costs and feedback
241+
242+
Capabilities answer **can this deployment faithfully execute this alternative?**
243+
Costs answer **which feasible alternative is preferable?**
244+
245+
| Capability question | Why it constrains selection |
246+
| --- | --- |
247+
| Can the producer build/update the selected family and parameters? | A readout implementation alone does not make a state maintainable |
248+
| Can storage and readout preserve the selected windows and labels? | A tumbling-only path cannot silently implement arbitrary sliding coverage |
249+
| Are merge operations and full/delta encodings compatible? | Distributed producers must construct the same logical state |
250+
| Can the runtime perform every exact operator after readout? | A supported sketch is insufficient for an unsupported full expression |
251+
| Can readiness, staleness and exact fallback be enforced? | Mathematical legality does not establish runtime answerability |
252+
253+
Costs include initialization, ingestion updates, overlapping/retained state,
254+
transmission, storage, merges, readouts, recurring queries, and shared producer
255+
construction once. Compare alternatives over the same data and demand scope.
256+
Missing evidence is not zero cost; stale or incomplete implementation evidence
257+
cannot justify selection.
258+
259+
Runtime observations reference the concrete binding and selected semantic
260+
producer. Physical controls may vary only within already-authorized
261+
guardrails. Changing grouping, family, parameters, windows or sharing returns
262+
to planning.
263+
264+
## Reuse across various ASAP workload scenarios
265+
266+
| Scenario | Reusable Planner strategy | Application-specific responsibility |
267+
| --- | --- | --- |
268+
| Repeated dashboards (MetricsObservabilityQuery) | Shared aggregates and prepared/maintained state | PromQL semantics, freshness and serving |
269+
| Multiple dashboard resolutions | Legal rollup and window alternatives | Compatible retention and exact time coverage |
270+
| Distributed telemetry aggregation | Mergeable summary and grouping alternatives | Collector placement, transmission and activation |
271+
| DQC analytical workloads | CSE, aggregate fusion and rollup | DQC engine adapters and batch execution policy |
272+
273+
General semantic rules belong in Planner. Backend-local metric-name fixtures,
274+
SID lookup or deployment-specific placement must not become universal Planner
275+
rules. No dependency on DQC is needed to reuse strategies contributed by it.
276+
277+
## High-level migration
278+
279+
See the [migration delivery plan](asapplanner-migration-plan.md) for PR-sized
280+
implementation slices, dependencies, regression fixtures and completion gates.
281+
282+
| Milestone | System outcome | Acceptance |
283+
| --- | --- | --- |
284+
| 1. Audit the shared contract and entry points | Current canonical compilation and compatibility paths have explicit ownership | Document supported operators, sharing scope, profile limits and true IR gaps |
285+
| 2. Complete one workload-wide semantic path | Registered queries use Planner alternatives with preserved shared producers | The two-query example has one selected producer and both result roots |
286+
| 3. Preserve bindings through all projections | Precompute, storage and serving implement the same selected decision | No duplicate maintenance; exact state/schema/window and generation agreement |
287+
| 4. Consolidate reusable strategies | Missing general fusion/rollup rules extend Planner | Rules work without backend metric names, SID objects or placement assumptions |
288+
| 5. Close capability and cost feedback | Only fully executable, properly costed alternatives are committed | Unsupported or stale evidence fails closed; estimated and observed costs are traceable |
289+
| 6. Validate profiles and retire redundant selection paths | Serving executes installed bindings without independent semantic planning | Prometheus parity, sharing, readiness, fallback and activation-failure tests pass |
290+
| 7. Broaden coverage (ProjectASAP-wide; not required for this repository) | Other applications, engines, sketches and lifecycles reuse the contract | Each participating provider demonstrates capability and semantic conformance |
291+
292+
The first milestone demonstration should use backend-local ingestion and the
293+
exact two-query example. Distributed rollout follows the same contract with
294+
additional producer and activation checks. Existing paths may remain as
295+
comparison baselines until parity is established; remove duplicate semantic
296+
selection, not necessary physical plans or profile-specific runtime adapters.
297+
298+
Step 7 is an ecosystem extension, not a prerequisite for completing this
299+
backend's scoped consolidation through steps 1–6.
300+
301+
## Related contracts and implementation guides
302+
303+
- [Physical compiler](../developer_docs/control-plane/physical-compiler.md)
304+
- [Plan publication](../developer_docs/control-plane/plan-publication.md)
305+
- [Backend plan runtime](../developer_docs/query-engine/backend-plan-runtime.md)
306+
- [ASAPQuery compatibility profile](asapquery-compatibility-profile.md)
307+
- [Runtime accuracy feedback](../developer_docs/control-plane/runtime-accuracy-feedback.md)

0 commit comments

Comments
 (0)