docs: reorganize control-plane design around ASAPPlanner boundary - #444
Merged
Merged
Conversation
…ntity ASAPPlanner's own scope statement (README "Scope"; asap-aware-mapping/README.md "Non-Goals") is explicit that it does not choose collector/backend placement, transport mode, or physical resources - confirmed against its current crates/types/src/post_asap module (SummaryAgg/SummaryFamilyType/GroupingStrategy/Reduction/SummaryEstimate), not older docs. Add design-compiled-plan-collector-backend-split.md: the ASAPQuery control plane compiles a selected post-ASAP DAG into a CompiledPlan carrying a CollectorSubplan (asap_edge YAML via OpAMP) and a BackendSubplan (BackendPlan), sharing one plan_id/plan_version/ activation/expiry/backend_compat identity - closing the exact gap ASAPCollector PR #558 documents (no plan_id/version/activation/expiry/ backend-compat on the OpAMP wire today) - rather than serializing the selected DAG directly into collector YAML. Update the migration doc (PR #444) to reference the compile step wherever it previously said "collector/backend stage allocation" or "collector configuration generation", fix the target-architecture diagram to show both subplans instead of only BackendPlan, add the legacy physical::plan::PlanNode/PipelineStage allocator to the post-cutover removal list, broaden PR 5 from a BackendPlan-only conversion to the full two-subplan compile, and note open ASAPPlanner PRs #300 (explicit update/readout phase boundary - the same boundary this split already uses structurally) and #299 (accuracy propagation) as tracked, non-blocking upstream changes for PR 6's coverage list. Correct design-backend-plan-wire-format.md's BackendPlan::plan_id comment ("observability only, not identity") to reflect its new role as the cross-subplan join key. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Checked against the real processor (opentelemetry-collector-contrib-patch/processor/asapedgeprocessor/ config.go), not the doc summary of it: today's MetricFamily.Mode is a bare two-value string (per_series/whole_stream, ParseAggMode-validated) and AggregateBy is a plain []string with no way to express GroupKeys.without - neither can distinguish Reduction::PerEntity from a genuine zero-key Reduce, the exact ambiguity Reduction was introduced to remove. Family is a flat string with no exact_kind discriminator and no GroupingStrategy field at all. Redesign MetricFamily to name every field and enum value directly from post_asap - Source/Family/ExactKind/ReduceBy/ReduceWithout/PerEntity/ Grouping/HydraKind/SharedRows/SharedColumns - while keeping Go's flat mapstructure-struct idiom (matching this same file's own FamilyKind/ Tier/ColdFormat pattern) rather than grafting a serde-style nested tagged union onto a decoder that was never built for one. The exact_kind and grouping gaps §6 previously listed as open follow-ups close as a direct consequence of the realignment, not as separate work. Explicit about scope: this is a schema proposal against real code, not a claim ASAPCollector has implemented it, and lists which MetricFamily fields have no DAG counterpart and correctly stay untouched (tier, spatial_filter, gos_*, emit_heap/weight_mode, threshold/CDM, cold archive, control_channel). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
zzylol
changed the title
zzylol
changed the title
zzylol
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganize
control_plane/docsinto a small set of topic-based, long-lived design documents. ASAPPlanner-owned logical planning is referenced instead of re-specified in ASAPQuery-backend.New structure
README.md: directory scope, ownership rule, and document index.asapplanner-integration.md: the Planner/backend ownership boundary and stable integration contracts.physical-planning.md: ASAPQuery-backend-owned placement, windows, aggregation placement, state representation, transmission, and compilation into matching CollectorPlan and BackendPlan artifacts.backend-plan.md: the control-plane contract installed and executed by the ASAPQuery data plane.Removed duplication
Planner remains responsible for parsing, IR, query-to-summary mapping, accuracy reasoning, workload sharing, candidate generation, and logical selection. ASAPQuery-backend documents only physical planning, activation, BackendPlan, and data-plane execution contracts.
Validation
git diff --checkcontrol_plane/docscontains only the four intended Markdown files;