Skip to content

docs: define ASAPQuery compatibility profile - #479

Merged
zzylol merged 4 commits into
mainfrom
docs/asapquery-compatibility-profile
Sep 3, 2026
Merged

zzylol merged 4 commits into
mainfrom
docs/asapquery-compatibility-profile

Conversation

@zzylol

@zzylol zzylol commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Why

ASAPQuery-backend currently documents its broader distributed Collector and modified-OTLP architecture. ProjectASAP/ASAPQuery has a smaller drop-in scope: Prometheus copies raw samples through Remote Write, the query engine builds summaries locally, and unsupported queries fall back to Prometheus.

We need an explicit compatibility target before reintroducing that path so it does not accidentally restore stale planner code or couple the MVP to ASAPCollector.

Before this PR

The active architecture said Prometheus Remote Write and backend-local raw precompute were not the MVP architecture. There was no current contract for running ASAPQuery-backend without ASAPCollector or for treating the ASAPQuery scope as a subset of the larger backend.

After this PR

A backend-specific asapquery compatibility profile defines:

Prometheus --remote_write--> raw receiver --> backend-local precompute --> SummaryStore
PromQL client --> Prometheus API --> planned summary readout | Prometheus fallback

The profile:

  • requires only Prometheus Remote Write v1 ingestion, backend-local precompute, the warm summary store, PromQL serving, workload observation, canonical ASAPPlanner invocation, and Prometheus fallback;
  • explicitly excludes ASAPCollector, CollectorPlan, OpAMP, OTLP, source sampling, GOS, delta transport, and distributed placement;
  • treats PrecomputePlan as an internal BackendPlan projection activated atomically;
  • records retry/deduplication, backpressure, coverage, fallback, and failure behavior;
  • maps reusable backend components and current gaps; and
  • gives six implementation phases with executable acceptance criteria and one final MVP completion criterion.

The existing getting-started pages now identify themselves as the distributed Collector profile and link to this smaller alternative.

Reference behavior is pinned to ProjectASAP/ASAPQuery commit 9fb051aa798361fca8e3012835412cb6fa338a0c. Canonical logical planning remains owned by the pinned ASAPPlanner; this proposal does not copy the historical ASAPQuery planner.

Validation

  • git diff --cached --check
  • verified all relative Markdown links resolve
  • reviewed the referenced ASAPQuery Remote Write decoder, query tracker, precompute engine, query adapter, and Prometheus fallback paths
  • documentation-only change; repository MVP CI runs on the PR

Scope

Documentation only. Runtime implementation is intentionally split into the phases described by the new contract.

@zzylol
zzylol merged commit 838b4a0 into main Sep 3, 2026
1 check passed
@zzylol
zzylol deleted the docs/asapquery-compatibility-profile branch September 3, 2026 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant