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 <[email protected]>
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.
