You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/05/19 02:32:47 UTC

(skywalking-horizon-ui) branch main updated: docs: reframe OAP version requirement as v11-native / v10-partial

This is an automated email from the ASF dual-hosted git repository.

wu-sheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-horizon-ui.git


The following commit(s) were added to refs/heads/main by this push:
     new f56cc9c  docs: reframe OAP version requirement as v11-native / v10-partial
f56cc9c is described below

commit f56cc9cadccce8e73527de78613d0f91d42acb03
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Tue May 19 10:32:37 2026 +0800

    docs: reframe OAP version requirement as v11-native / v10-partial
    
    There is no OAP 10.5 release — the admin-server, receiver-runtime-rule,
    dsl-debugging, and inspect modules appeared in the 10.5 development
    snapshot but shipped in 11.0. Treat any "10.5" reference in prior docs
    as "v11".
    
    Recast the matrix so v10 is partial-support (data-plane only) and v11
    is native (full admin-port surface). The triage stack — dashboards,
    alarms, traces, logs, topology, profiling — runs on either. Everything
    admin-port (Inspect, DSL Management, Live Debugger, Alarm Rule editor,
    Cluster Status → Admin pane, OAP UI-template sync) is v11-only.
    
    Also touched the MQE target-resolver comment in apps/bff for the same
    reason — same correction, code-side.
---
 apps/bff/src/util/mqe-target.ts        |  8 ++++----
 docs/README.md                         |  2 +-
 docs/compatibility/oap-version.md      | 34 +++++++++++++++++++---------------
 docs/compatibility/required-modules.md | 12 ++++++------
 docs/operate/cluster-metadata.md       |  2 +-
 docs/operate/inspect.md                |  6 +++---
 docs/setup/oap.md                      |  6 +++---
 docs/setup/overview.md                 |  2 +-
 8 files changed, 38 insertions(+), 34 deletions(-)

diff --git a/apps/bff/src/util/mqe-target.ts b/apps/bff/src/util/mqe-target.ts
index 2d08852..58944f1 100644
--- a/apps/bff/src/util/mqe-target.ts
+++ b/apps/bff/src/util/mqe-target.ts
@@ -28,8 +28,8 @@
  *      `Map<String,String>` with keys like `core.default.restPort`
  *      and (when the sharing-server module is enabled)
  *      `sharing-server.default.restPort`. Prefer the sharing-server
- *      values because 10.5+ defaults the query GraphQL there; fall
- *      back to core's REST otherwise.
+ *      values because OAP 11.x defaults the query GraphQL there; fall
+ *      back to core's REST otherwise (the v10 layout).
  *
  *   3. Host fallback: if the discovered bind host is empty / wildcard
  *      (`0.0.0.0`, `::`), reuse the admin URL's hostname. Port-forward
@@ -137,8 +137,8 @@ interface PickResult {
 }
 
 function pickFromDump(dump: Record<string, string>, adminHost: string): PickResult {
-  // Prefer sharing-server over core (10.5+ defaults the query
-  // GraphQL on the sharing-server REST).
+  // Prefer sharing-server over core (OAP 11.x defaults the query
+  // GraphQL on the sharing-server REST; the v10 layout has it on core).
   const sharingHost = dump['sharing-server.default.restHost'];
   const sharingPortStr = dump['sharing-server.default.restPort'];
   const coreHost = dump['core.default.restHost'];
diff --git a/docs/README.md b/docs/README.md
index 4b86180..7d8ecb6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,7 +10,7 @@ This documentation tree explains:
 - **Access Control** — [local](access-control/local-backend.md) + [LDAP](access-control/ldap-backend.md) backends, [break-glass admin](access-control/break-glass.md), the 28-verb [RBAC model](access-control/rbac.md), the [audit log](access-control/audit-log.md), and the three [admin pages](access-control/admin-pages.md).
 - **Customization** — how the [sidebar is composed from OAP layers](customization/menu-structure.md), how to author [layer dashboard templates](customization/layer-templates.md), how to author [overview (war-room) templates](customization/overview-templates.md), and the end-to-end recipe for [adding a new layer](customization/adding-a-new-layer.md).
 - **Components** — field-by-field reference for every widget primitive ([overview](components/overview-widgets.md) + [per-layer dashboard](components/dashboard-widgets.md)) and the [wrapped chart components](components/charts.md).
-- **Operate** — [Cluster Status & Metadata](operate/cluster-metadata.md) page and the [Inspect](operate/inspect.md) page (the latter additionally requires OAP 10.5.0+ for the SWIP-14 Inspect API; everything else works on any OAP 10.x — see the [feature matrix](compatibility/oap-version.md#feature-matrix-vs-oap-version)).
+- **Operate** — [Cluster Status & Metadata](operate/cluster-metadata.md) page and the [Inspect](operate/inspect.md) page (the latter requires OAP 11.x for the SWIP-14 Inspect API; OAP 10.x is partially supported — see the [feature matrix](compatibility/oap-version.md#feature-matrix-vs-oap-version)).
 
 ## Repository layout (orientation only)
 
diff --git a/docs/compatibility/oap-version.md b/docs/compatibility/oap-version.md
index b0a741d..ebaf1eb 100644
--- a/docs/compatibility/oap-version.md
+++ b/docs/compatibility/oap-version.md
@@ -1,32 +1,36 @@
 # OAP Version Requirement
 
-## Minimum: OAP 10.0; recommended OAP 10.5.0+
+## Native: OAP 11.x; partial support: OAP 10.x
 
-Horizon UI runs against **any Apache SkyWalking OAP in the 10.x line**. Most of the UI works against 10.0–10.4; one page — **Inspect** — additionally requires **10.5.0+** because it calls the [Inspect API (SWIP-14)](https://github.com/apache/skywalking/blob/master/docs/en/swip/swip-14.md) endpoints that were introduced in 10.5.
+Horizon UI is **built natively against Apache SkyWalking OAP 11.x** — the full feature set assumes v11. **OAP 10.x is partially supported**: the data-plane stack (dashboards, traces, logs, topology, alarms, profiling) renders correctly because it only touches the query GraphQL port. Everything that lives on OAP's **admin port** — Inspect, DSL Management, Live Debugger, Alarm Rule editor, Cluster Status → Admin pane, OAP UI-template sync — depends on modules (`admin-server`, `receiver-run [...]
 
-Older 9.x OAPs are not supported — the layer concept, the MQE language baseline Horizon assumes, and the admin port layout all settled in 10.0.
+> Note: those four modules appeared in OAP's 10.5 development snapshot, but **there is no OAP 10.5 release** — the SWIPs that introduced them shipped in 11.0. Treat any "10.5" reference in old docs as "v11."
+
+Older 9.x OAPs are not supported — the layer concept, the MQE language baseline Horizon assumes, and the admin port layout all settled later.
 
 ### Feature matrix vs OAP version
 
-| Horizon feature | OAP 10.0–10.4 | OAP 10.5.0+ |
+| Horizon feature | OAP 10.x (partial) | OAP 11.x (native) |
 |---|---|---|
 | Layer dashboards, overviews | ✓ | ✓ |
-| Alarms (read) | ✓ — falls back to legacy `getAlarm` when `queryAlarms` is absent | ✓ — uses `queryAlarms` (server-side layer filter) when present |
+| Alarms (read) | ✓ — falls back to legacy `getAlarm` when `queryAlarms` is absent | ✓ — uses `queryAlarms` (server-side layer filter) |
 | Traces (native + Zipkin), Logs, Topology | ✓ | ✓ |
 | Profiling (trace / async / pprof / eBPF) | ✓ — per the profiling modules you've turned on | ✓ |
 | Cluster Status — Query pane | ✓ | ✓ |
-| Cluster Status — Admin pane (admin-server, runtime-rule, dsl-debugging) | ✓ — module probe works on any v10 admin-server | ✓ — also reports the `inspect` module |
-| DSL Management, Live Debugger, Alarm Rule editor | ✓ — needs `receiver-runtime-rule` + `dsl-debugging` modules on (any v10) | ✓ |
-| MQE execution / metric reads | ✓ — Horizon's MQE target resolver discovers the REST port from `core.restHost`/`core.restPort` when `sharing-server` is absent | ✓ — uses `sharing-server.default.restPort` (the v10.5+ default) |
-| **Inspect page** (metric catalog + entity enumerator) | ✗ — endpoints don't exist; the page is hidden / returns 404 | ✓ — requires `SW_INSPECT=default` on OAP |
+| MQE execution / metric reads | ✓ — falls back to `core.restHost`/`core.restPort` when `sharing-server` is absent | ✓ — uses `sharing-server.default.restPort` (the v11 default) |
+| Cluster Status — Admin pane (admin-server, runtime-rule, dsl-debugging, inspect) | ✗ — admin-port modules don't exist on v10; pane is hidden | ✓ |
+| DSL Management, Live Debugger, Alarm Rule editor | ✗ — needs `receiver-runtime-rule` + `dsl-debugging` (v11-only) | ✓ |
+| **Inspect page** (metric catalog + entity enumerator) | ✗ — `/inspect/*` endpoints don't exist | ✓ — requires `SW_INSPECT=default` on OAP |
+| **OAP UI-template sync** (admin pages edit OAP-stored dashboards) | ✗ — `/ui-management/templates*` not available; admin pages are read-only against bundled | ✓ — required for non-read-only admin editing |
 
-### What "requires 10.5.0+" means in practice for the Inspect page
+### What "partial support on v10" means in practice
 
-- The Inspect page makes calls to `GET /inspect/metrics` and `GET /inspect/entities` on the OAP admin port. These endpoints only exist in OAP 10.5.0+.
-- Horizon's Cluster Status → Admin pane probes the `inspect` module via the OAP config dump. On an OAP < 10.5, the module is not in the dump, so the pane shows `inspect` as off and the Inspect tab is hidden from the sidebar. There is no broken-half-rendered state.
-- All other pages remain fully functional on 10.0–10.4. The compatibility cliff is scoped to one page.
+- **Data-plane pages just work.** Dashboards, overviews, alarms (read), traces, logs, topology, and profiling all render on v10. The GraphQL query port (default `:12800`) is what they use, and the protocol is stable across both lines.
+- **Admin port is dark on v10.** The entire admin port (default `:17128`) is gone — `admin-server`, `receiver-runtime-rule`, `dsl-debugging`, and `inspect` are v11-only. Anything that depends on them (Inspect, DSL Management, Live Debugger, Alarm Rule editor, Cluster Status → Admin pane, OAP UI-template sync) is unavailable. The sidebar entries are hidden so operators don't see broken pages.
+- **MQE target resolution** falls back to OAP's `core.restHost`/`core.restPort` instead of the v11 `sharing-server.default.restPort` default. Works fine, just a different code path.
+- **Admin template editing** is read-only — the dashboard / overview / alert admin pages render bundled JSON and show the OAP-unreachable banner. Saves are blocked. Display still works.
 
-If you run 10.0–10.4 and don't need the Inspect tab, you don't need to upgrade. If you do need it, upgrade OAP to 10.5.0+ and set `SW_INSPECT=default`.
+If you only need triage (dashboards, alarms, traces, logs), v10 is sufficient. If you need any operate / admin functionality, you need v11.
 
 ## Where the version is shown
 
@@ -50,7 +54,7 @@ Horizon does **not** lock to a specific OAP minor version. The BFF probes OAP's
 - **Alarms**: prefers the modern `queryAlarms` capability (server-side layer filter) and falls back to the legacy `getAlarm` (all-layers + client-side filter) when the schema doesn't include it.
 - **Per-call capability cache** ensures the probe runs once per BFF lifetime, not per request.
 
-This means a Horizon release built against OAP 10.5.0 will continue to work against OAP 10.7, 10.8, etc., picking up new server-side capabilities automatically when they appear — and will also keep working against an older 10.x OAP at the cost of the Inspect page.
+This means a Horizon release built against OAP 11.x will continue to work against future v11 patch releases, picking up new server-side capabilities automatically when they appear — and will also keep working against v10 at the cost of Inspect + admin template editing.
 
 ## Versions of related pieces
 
diff --git a/docs/compatibility/required-modules.md b/docs/compatibility/required-modules.md
index e48e992..574e289 100644
--- a/docs/compatibility/required-modules.md
+++ b/docs/compatibility/required-modules.md
@@ -11,14 +11,14 @@ The admin-port endpoints are gated by per-module selectors on the OAP side. Hori
 
 | Module | OAP env-var | Min OAP | Endpoints Horizon hits | What breaks if disabled |
 |---|---|---|---|---|
-| **admin-server** | `SW_ADMIN_SERVER=default` | 10.0 | `GET /debugging/config/dump` | Everything on the admin port. With admin-server off, all three other selectors report `enabled: false` regardless of their actual state. |
-| **receiver-runtime-rule** | `SW_RECEIVER_RUNTIME_RULE=default` | 10.0 | `GET /runtime/rule/list`, `GET /runtime/rule`, `POST /runtime/rule/addOrUpdate`, `POST /runtime/rule/delete`, `GET /runtime/rule/bundled` | DSL Management page; alarm rule editor save/load; cluster-status rule matrix; Live Debugger rule picker; Inspect page source attribution. |
-| **dsl-debugging** | `SW_DSL_DEBUGGING=default` | 10.0 | `GET /dsl-debugging/status`, `GET /status/alarm/*` | Live Debugger (MAL / LAL / OAL session start, poll, stop); cluster-status DSL health pane; alarm rule diagnostics. |
-| **inspect** | `SW_INSPECT=default` | **10.5.0** | `GET /inspect/metrics`, `GET /inspect/entities` | Inspect page (returns 404 from OAP). |
+| **admin-server** | `SW_ADMIN_SERVER=default` | 11.x | `GET /debugging/config/dump`, `/ui-management/templates*` | Everything on the admin port. With admin-server off, all other admin-port selectors report `enabled: false` regardless of their actual state. The template-sync admin pages fall back to bundled read-only. |
+| **receiver-runtime-rule** | `SW_RECEIVER_RUNTIME_RULE=default` | 11.x | `GET /runtime/rule/list`, `GET /runtime/rule`, `POST /runtime/rule/addOrUpdate`, `POST /runtime/rule/delete`, `GET /runtime/rule/bundled` | DSL Management page; alarm rule editor save/load; cluster-status rule matrix; Live Debugger rule picker; Inspect page source attribution. |
+| **dsl-debugging** | `SW_DSL_DEBUGGING=default` | 11.x | `GET /dsl-debugging/status`, `GET /status/alarm/*` | Live Debugger (MAL / LAL / OAL session start, poll, stop); cluster-status DSL health pane; alarm rule diagnostics. |
+| **inspect** | `SW_INSPECT=default` | 11.x | `GET /inspect/metrics`, `GET /inspect/entities` | Inspect page (returns 404 from OAP). |
 
-All four are recommended. **admin-server** is non-optional; the rest can be left off if you do not need the corresponding feature, but the Cluster Status page will surface warnings.
+All four are recommended on v11. **admin-server** is non-optional for the v11 admin surface; the rest can be left off if you do not need the corresponding feature, but the Cluster Status page will surface warnings.
 
-The `inspect` module is the only one that requires OAP 10.5.0+; the first three exist in every 10.x release. On an OAP < 10.5, the `inspect` row in the Cluster Status → Admin pane reports off (the module isn't in the config dump) and the Inspect tab is hidden from the sidebar — the rest of the UI is unaffected. See [OAP Version](oap-version.md) for the full feature-vs-version matrix.
+The entire admin-port surface (all four modules) is **OAP 11.x only**. They appeared in the 10.5 development snapshot but **there is no OAP 10.5 release** — the SWIPs that introduced them shipped in 11.0. On OAP 10.x the data-plane stack (dashboards, traces, logs, topology, alarms, profiling) works fine; the admin-port features (DSL Management, Live Debugger, Alarm Rule editor, Cluster Status → Admin pane, Inspect, OAP UI-template sync) are unavailable and the corresponding sidebar entri [...]
 
 ## How Horizon detects module state
 
diff --git a/docs/operate/cluster-metadata.md b/docs/operate/cluster-metadata.md
index 693e0e7..1f52605 100644
--- a/docs/operate/cluster-metadata.md
+++ b/docs/operate/cluster-metadata.md
@@ -20,7 +20,7 @@ The triage flow during a banner-heavy incident lives here. The full check sequen
 │  Query (:12800)                  │  Admin (:17128)              │
 │  ─────────────────────           │  ─────────────────────       │
 │  Reachable  ✓                    │  Reachable  ✓                │
-│  Version    10.5.0               │  admin-server         ✓      │
+│  Version    11.0.0               │  admin-server         ✓      │
 │  Timezone   +0800                │  receiver-runtime-rule ✓     │
 │  Timestamp  2026-05-18 09:14:02  │  dsl-debugging        ✓      │
 │  Health     0 (OK)               │  inspect              ✓      │
diff --git a/docs/operate/inspect.md b/docs/operate/inspect.md
index c7f4eb2..119306c 100644
--- a/docs/operate/inspect.md
+++ b/docs/operate/inspect.md
@@ -2,7 +2,7 @@
 
 Path: `/admin/inspect`. Verb: `inspect:read` (granted by maintainer, operator, admin).
 
-The Inspect page lets the operator browse OAP's live metric catalog and enumerate the entities (services, instances, endpoints, processes, …) that have data for a given metric. It is built on the **Inspect API** (SWIP-14), which is new in OAP 10.5.0 — the page does not render on older OAPs.
+The Inspect page lets the operator browse OAP's live metric catalog and enumerate the entities (services, instances, endpoints, processes, …) that have data for a given metric. It is built on the **Inspect API** (SWIP-14), which is **OAP 11.x only** — the page does not render on v10.
 
 ## What the page is for
 
@@ -15,7 +15,7 @@ Common scenarios:
 
 ## Prerequisites
 
-- OAP 10.5.0 or later.
+- OAP 11.x.
 - `SW_INSPECT=default` on the OAP side.
 - `SW_ADMIN_SERVER=default` (gates the admin port itself).
 - The admin port (default 17128) reachable from the Horizon BFF.
@@ -113,7 +113,7 @@ The BFF is a thin proxy — caching is per-request, not cross-request. The Inspe
 
 ## Related
 
-- [Compatibility → OAP Version](../compatibility/oap-version.md) — why 10.5.0.
+- [Compatibility → OAP Version](../compatibility/oap-version.md) — why v11.
 - [Compatibility → Required OAP Modules](../compatibility/required-modules.md) — `SW_INSPECT` enablement.
 - [Customization → Layer Dashboard Templates](../customization/layer-templates.md) — where the metrics you find here end up being used.
 - OAP's [SWIP-14 (Inspect API)](https://github.com/apache/skywalking/blob/master/docs/en/swip/swip-14.md) — upstream design.
diff --git a/docs/setup/oap.md b/docs/setup/oap.md
index 6be4062..c0a605d 100644
--- a/docs/setup/oap.md
+++ b/docs/setup/oap.md
@@ -23,7 +23,7 @@ oap:
 | `timeoutMs` | number | `15000` | no | Per-request HTTP timeout (milliseconds) for all OAP calls. Applies to query, admin, Zipkin. Must be positive integer. |
 | `auth.username` | string | — | required if `auth` block present | Basic-auth username. Sent on every outbound OAP call. |
 | `auth.password` | string | — | required if `auth` block present | Basic-auth password. Sent on every outbound OAP call. Use `${VAR}` interpolation, not a literal. |
-| `mqe.host` | string | — | no | (Reserved) Override host for MQE GraphQL. When unset, Horizon discovers it via the sharing-server config dump on OAP 10.5+, falling back to `queryUrl`'s host. |
+| `mqe.host` | string | — | no | (Reserved) Override host for MQE GraphQL. When unset, Horizon discovers it via the sharing-server config dump on OAP 11.x, falling back to `queryUrl`'s host. |
 | `mqe.port` | number | — | no | (Reserved) Override port for MQE GraphQL. Must be positive integer. |
 
 ## How the BFF uses each URL
@@ -55,13 +55,13 @@ oap:
 
 ## OAP capability probing
 
-Horizon detects optional GraphQL fields via introspection on first use, then caches the result per BFF process lifetime. This is what makes "Horizon runs against any 10.5+ OAP" work — newer fields are picked up automatically when present, and missing fields are routed around silently.
+Horizon detects optional GraphQL fields via introspection on first use, then caches the result per BFF process lifetime. This is what lets Horizon run natively against OAP 11.x while still supporting v10 for triage — newer fields are picked up automatically when present, and missing fields are routed around silently.
 
 | Capability | Probed |
 |---|---|
 | `queryAlarms` (modern alarm query with server-side layer filter) | First alarms request. If missing → falls back to legacy `getAlarm` and filters client-side. |
 | `getMenuItems` field set (per OAP version) | First menu request. |
-| MQE target (sharing-server vs core.restPort) | First MQE call. OAP 10.5+ default → sharing-server. |
+| MQE target (sharing-server vs core.restPort) | First MQE call. OAP 11.x default → sharing-server; v10 → `core.restPort`. |
 
 The cache is per-process. After a BFF restart, the next request re-probes.
 
diff --git a/docs/setup/overview.md b/docs/setup/overview.md
index 95e214b..bffbe9d 100644
--- a/docs/setup/overview.md
+++ b/docs/setup/overview.md
@@ -4,7 +4,7 @@ This page is the smallest possible path from "no Horizon" to "Horizon in front o
 
 ## Prerequisites
 
-- Apache SkyWalking **OAP 10.x** (any 10.0+). The Inspect page additionally requires **10.5.0+**; everything else works on the whole 10.x line. See [Compatibility → OAP Version](../compatibility/oap-version.md) for the feature-vs-version matrix.
+- Apache SkyWalking **OAP 11.x** (native). OAP 10.x runs the data-plane stack (dashboards, traces, logs, topology, alarms, profiling) but the entire admin port — Inspect, DSL Management, Live Debugger, Alarm Rule editor, Cluster Status → Admin pane, and OAP UI-template sync — is v11-only. See [Compatibility → OAP Version](../compatibility/oap-version.md) for the feature-vs-version matrix.
 - Network reachability from the Horizon BFF to the OAP query port (`:12800`) and admin port (`:17128`). See [Network Ports](../compatibility/ports.md).
 - Node.js 20+, pnpm 9+ (for source builds). A pre-built artifact will not need either.