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 93a9a1b docs: trim README + drop all SWIP / 10.5-history references
93a9a1b is described below
commit 93a9a1bfef974985775b6bbbea2d1142b05a04ed
Author: Wu Sheng <[email protected]>
AuthorDate: Tue May 19 17:26:08 2026 +0800
docs: trim README + drop all SWIP / 10.5-history references
docs/README.md:
- Dropped most inline links inside the section blurbs — the left-side
menu on the docs site is the canonical navigation, and the inline
list was duplicating it for every doc title.
- Re-cast the body around "how it's organized" + "where to start by
role" + "live demo" so the README reads as an orientation page,
not a link directory.
- Moved external references (apache/skywalking, booster-ui, demo URL)
to a single "References" section at the end of the page rather
than peppered throughout.
- Dropped the stale "the latter additionally requires OAP 10.5.0+ for
the SWIP-14 Inspect API" wording that the user flagged.
README.md (root):
- Slimmed from ~130 lines to ~60. Project root is now a short
feature list + tech-stack line + dev / container recipes + license.
Anyone after detail follows the link to docs/.
SWIP / 10.5 history removed across:
docs/compatibility/required-modules.md
docs/compatibility/oap-version.md
docs/operate/inspect.md
The remaining "v11-only" wording stays — it's the current truth.
There's no "SWIP" reference anywhere in the docs tree now.
---
README.md | 129 ++++++++-------------------------
docs/README.md | 49 ++++++++-----
docs/compatibility/oap-version.md | 2 -
docs/compatibility/required-modules.md | 2 +-
docs/operate/inspect.md | 3 +-
5 files changed, 60 insertions(+), 125 deletions(-)
diff --git a/README.md b/README.md
index b46184c..611110a 100644
--- a/README.md
+++ b/README.md
@@ -7,124 +7,53 @@ The next-generation web UI for [Apache
SkyWalking](https://github.com/apache/sky
[](https://www.apache.org/licenses/LICENSE-2.0)
-## Features
-
-### Multi-layer navigation
-- Layers (General Service, Service Mesh, Kubernetes, Browser RUM, Virtual MQ,
Virtual Database, FaaS, OpenTelemetry, …) are level-1 in the sidebar with
per-layer service counts and a colored marker.
-- Drilling into a layer expands its level-2 children inline: **Layer overview
· Services · Instances · Endpoints · Topology**.
-- Per-layer **menu mode** (full or lite) and renamable entity slots — e.g.
FaaS uses *Function / Version / Invocation*, MQ uses *Cluster / Broker /
Topic*, K8s uses *Workload / Pod / Container*, Browser uses *Application /
Session / Page*.
-
-### Landing
-- **Global landing**: layers-reporting KPI, services-across-layers count,
throughput **stacked by layer** (units differ per layer — General `cpm`, Mesh
`cpm`, MQ `msg/s`, DB `qps`, FaaS `inv/m`), layers-at-a-glance grid with sample
top services per layer, error-rate-by-layer, SLO burn donut, activity heatmap,
and "Available · no data" cards for configurable-but-empty layers.
-- **Per-layer landing**: layer header with data-source provenance and 6
layer-scoped KPIs, layer-scoped tabs (Overview · Services · Instances ·
Endpoints · Topology · Dashboards · Settings), layer throughput & latency,
**service health constellation** (polar graph: angle = service slot, radius =
log(cpm), color = error band), services table with traffic-share bars and
per-service sparklines, layer SLA burn-down, apdex distribution.
-
-### Service metrics deep-dive
-- **Multi-layer awareness**: a single service can report through multiple
layers simultaneously. The header shows an "N layers" chip and a strip of
auto-laid-out layer cards (e.g. General · Service Mesh · Kubernetes), each with
that layer's metric set and a sparkline. Clicking a card scopes the chart grid;
"Compare" opens side-by-side.
-- Standard SkyWalking metrics: `service_resp_time`, `cpm`, `sla`, `apdex`,
percentiles, JVM panels, instances grid.
-- **Service picker dropdown**: searchable (`⌘K`), sortable by cpm / p99 / err
/ name / recent, layer badges (`G·M·K`, `MQ`, `DB`…), starred favorites, status
dots — pick a row to jump the page to that service.
-
-### Topology — three visual modes
-- **Force-directed** with animated traffic-flow particles
-- **Hierarchical DAG** by tier
-- **Hex / honeycomb** grid
-Each variant ships with the same toolbar (Layer filter, Group by, Color by,
free-text Filter), legend (error-rate ramp, edge-weight = cpm), and side detail
panel (KPI mini-grid, upstream callers, downstream dependencies).
-
-### Endpoint / API dependency
-Multi-hop caller → endpoint → downstream view (not just a single popout).
Latency breakdown, dependency table, recent traces inline.
-
-### Dashboards (custom + per-scope)
-- **Widget editor**: draggable resizable grid, MQE query drawer with
token-level syntax coloring, visualization picker, threshold rules, panel
options.
-- **Per-scope templates**: Glance (fleet overview), Service, Instance,
Endpoint, Topology, Metric drill — each bound to that entity scope with the
right default panels.
-- **Linked widgets**: service list on the left scopes every widget on the
page; all time-series share a **synced crosshair** with a pinned tooltip that
reads values from every chart at the same instant, plus a dashed **compare
cursor** and an "At cursor" / "Δ vs compare" readout.
-
-### Trace explorer
-Duration scatter + sortable trace list + waterfall with per-span service /
kind / error highlighting.
-
-### Log explorer
-- **Condition bar** with chip filters: status, service, env, attributes
(`@http.status_code:>=500`, `@duration_ms:>300`), exclusions, free-text.
-- **Saved views** and view-mode tabs (Stream / Patterns / Table /
Transactions).
-- **Facets sidebar** (Status, Service, Env, Host, Container, K8s pod,
@trace_id, @http.status_code, …) with counts.
-- **Timeline histogram** with brush selection.
-- **Mixed-format payloads**: each row inline-expands the raw payload as
**JSON, YAML, or raw text** with proper syntax coloring; Tree / Raw / Table
tabs, JSONPath breadcrumb, line gutter, ⌘F.
-- **Top patterns** roll-up: templated event groups with severity dot, mini
bar, and event count.
-- Right detail pane: quick filter pills (＋ / −), attributes table, related
trace / host / dashboard cards.
-
-### Alarms (active, read-only + Live debug)
-- **Active alarms only, read-only** — no rule management, no acknowledge, no
manual close. Recovery is driven by the backend (alarms auto-clear when the
rule stops firing). This is the operate view: timeline, severity tabs, alarm
list + right-side detail with trigger expression and channel routing.
-- **Live debug card** — Run now / Step / Pause / Copy as MQE; **MQE
expression** with syntax coloring; **execution trace** (fetch → select → window
→ compare → hold) with per-step output count, latency, and ok/match/fire
badges; **matched entities table**; **eval window chart** with crossing-now
pulse; **raw OAP response** as pretty-printed JSON.
-
-### Admin & RBAC
-- **Local + LDAP auth**: bind config, search base, attribute mapping,
test-bind.
-- **Roles & permissions**: per-layer, per-dashboard, per-action (view, edit,
debug alarm, edit layer config). Alarms are read-only — no acknowledge / close
/ silence actions.
-- **Users**: local + LDAP-backed users, group sync state.
-- **Audit log**: dashboard edits, role changes, auth-provider changes — who,
what, when.
-- **Layer admin**: menu mode (full / lite) + entity-term mapping, per-layer
settings.
-- **System health**: OAP cluster status, storage backend status (BanyanDB,
Elasticsearch, JDBC).
-
-### Profiling (planned)
-Flame graph view backed by SkyWalking's profiling / async-profiler / eBPF data.
-
-## Compatibility
-
-Horizon UI is built against the SkyWalking OAP GraphQL query-protocol (same
schema as booster-ui consumes). No backend changes are required.
+## Documentation
+
+Full docs ship at [skywalking.apache.org → Horizon
UI](https://skywalking.apache.org/docs/) and live in this repo under
[`docs/`](docs/README.md). The left-side menu there is the canonical entry
point — setup, compatibility, access control, customization, components, and
operate are all covered.
+
+## At a glance
+
+- **Multi-layer navigation** — Layers in the sidebar with per-layer service
counts, drill-down to overview / services / instances / endpoints / topology,
per-layer entity-slot renaming.
+- **Landing** — global cross-layer overview + per-layer landing with service
constellation and traffic-share bars.
+- **Service deep-dive** — multi-layer aware; one service can report through
General + Service Mesh + K8s at once with side-by-side comparison.
+- **Topology** — force-directed / hierarchical DAG / hex honeycomb variants on
the same data.
+- **Endpoint / API dependency** — multi-hop caller → endpoint → downstream
view with latency breakdown.
+- **Dashboards** — draggable grid + MQE query drawer + per-scope templates
(Glance / Service / Instance / Endpoint / Topology / Metric drill), synced
crosshair + compare cursor across panels.
+- **Trace explorer** — duration scatter, sortable list, waterfall with
per-span service / kind / error highlighting.
+- **Log explorer** — chip filters, saved views, facets sidebar, timeline
brush, mixed JSON / YAML / raw payload tree, top patterns roll-up.
+- **Alarms** — active alarms only, read-only (no acknowledge / close —
recovery is backend-driven), with a Live Debug panel for MQE expressions.
+- **Admin** — local + LDAP auth, RBAC (4 built-in roles, 28 verbs), audit log,
layer admin, system / OAP cluster health, 5 bundled themes (Horizon · Meridian
· Obsidian · Daybreak · Aurora).
+- **Profiling** — flame graphs over trace-based / async-profiler / eBPF /
pprof data.
## Tech stack
-| Layer | Choice |
-|---|---|
-| Framework | Vue 3 + TypeScript (Composition API, `<script setup>`) |
-| Build | Vite 5 |
-| Routing | vue-router 4 |
-| State | Pinia |
-| HTTP / GraphQL | `graphql-request` + `fetch` |
-| Charts (time series / heatmap / sankey / scatter / stacked bar / donut) |
Apache ECharts 5 |
-| Topology / polar / sparklines | D3 v7 |
-| Dashboard grid | `vue-grid-layout` |
-| Flame graph | `d3-flame-graph` |
-| Code editor (MQE) | Monaco |
-| i18n | vue-i18n |
-| Testing | Vitest + Vue Test Utils |
-| E2E | Cypress |
+Vue 3 + TypeScript on Vite 5, Pinia, vue-router 4, Apache ECharts 5, D3 v7,
vue-grid-layout, d3-flame-graph, Monaco, Vitest. The BFF is Fastify on Node 20+.
## Development
-Requires Node.js 20+ and pnpm 10+ (pinned via Corepack in `package.json`).
+Requires Node.js 20+ and pnpm 10+ (pinned via Corepack).
```bash
-pnpm install # one-time / after lockfile changes;
auto-builds workspace packages via `prepare`
+pnpm install # one-time / after lockfile changes
+pnpm --filter bff dev # BFF on :8081 (NODE_ENV=development)
+pnpm --filter ui dev # Vite dev server on :9091, proxies /api → BFF
-# Dev loop (hot-reload, verbose pretty logs)
-pnpm --filter bff dev # BFF on :8081 with NODE_ENV=development →
debug level + per-request access logs
-pnpm --filter ui dev # Vite dev server on :9091, proxies /api to
the BFF
-
-# Static checks / tests
pnpm -r type-check
-pnpm -r lint # read-only; `pnpm -r lint:fix` to mutate
+pnpm -r lint # `lint:fix` mutates
pnpm -r test:unit
pnpm license:check # CI gate via skywalking-eyes
+```
-# Self-contained "binary mode" — produces ./dist/ that boots with `node
dist/server.js`
-pnpm package
-HORIZON_CONFIG=./horizon.yaml HORIZON_STATIC_DIR=./dist/static node
dist/server.js
+Container build (zero-compile-in-image — Dockerfile just copies in the
pre-built `dist/`):
-# Container — Docker just copies in the pre-built dist (no compile in image)
+```bash
+pnpm package # produces
./dist/
docker build -t horizon-ui:local .
docker run --rm -p 8081:8081 -v "$PWD/horizon.yaml:/app/horizon.yaml:ro"
horizon-ui:local
```
-### Logging
-
-The BFF uses [pino](https://github.com/pinojs/pino). Two modes, picked from
`NODE_ENV`:
-
-| Mode | When | Format | Default level |
-|---|---|---|---|
-| **Dev** | `pnpm --filter bff dev` (sets `NODE_ENV=development`) | Pretty,
colorized, via `pino-pretty` | `debug` + per-request access logs |
-| **Prod** | Everything else — `node dist/server.js`, Docker container, CI |
One JSON object per line on stdout | `error` — quiet by default |
-
-Adjust with `LOG_LEVEL`: `info` opens per-request access logs in prod, `debug`
adds lifecycle chatter, `trace` is everything. Genuine request errors stay
logged at `error` under any default that includes `error`. See
[docs/setup/container-image.md →
Logging](docs/setup/container-image.md#logging) for the three orthogonal
channels (app logs, audit log, wire-debug log) and example `jq` recipes.
+See [`docs/setup/container-image.md`](docs/setup/container-image.md) for image
tags, env vars, mounting `horizon.yaml`, and a Kubernetes example.
## License
-Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
-
-License headers and dependency licenses are enforced in CI via
[skywalking-eyes](https://github.com/apache/skywalking-eyes); configuration is
in [.licenserc.yaml](.licenserc.yaml).
+Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). License headers and
dependency licenses are enforced in CI via
[skywalking-eyes](https://github.com/apache/skywalking-eyes); configuration in
[.licenserc.yaml](.licenserc.yaml).
diff --git a/docs/README.md b/docs/README.md
index 7d8ecb6..c8b4aff 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,38 +1,41 @@
# Apache SkyWalking Horizon UI
-Horizon UI is the next-generation web UI for [Apache
SkyWalking](https://github.com/apache/skywalking). It targets feature parity
with [skywalking-booster-ui](https://github.com/apache/skywalking-booster-ui)
on the same OAP GraphQL query-protocol and MQE, with a modernized, dense,
dark-first design.
+Horizon UI is the next-generation web UI for Apache SkyWalking. It targets
feature parity with the existing booster-ui against the same OAP GraphQL
query-protocol and MQE, with a modernized dense dark-first design.
-This documentation tree explains:
+The sidebar on the left of this site is the canonical entry point — every
section below has its own page there. This README is the orientation map.
-- **[Design Target](design-target.md)** — what Horizon UI is built for and how
it differs from booster-ui.
-- **Compatibility** — minimum [OAP version](compatibility/oap-version.md),
[required OAP modules](compatibility/required-modules.md), [port
matrix](compatibility/ports.md), and the per-pane [check sequence on the
Cluster Status page](compatibility/cluster-status.md).
-- **Setup** — [quick start](setup/overview.md), the [container
image](setup/container-image.md) (image tags, env vars, how to mount
`horizon.yaml`, Kubernetes example), and the full [`horizon.yaml`
reference](setup/horizon-yaml.md), broken down per top-level section:
[server](setup/server.md), [oap](setup/oap.md), [auth](setup/auth.md),
[rbac](setup/rbac.md), [session](setup/session.md), [audit](setup/audit.md),
[setup/alarms files](setup/files.md), [debugLog](setup/debug-log.md).
-- **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 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)).
+## How it's organized
-## Repository layout (orientation only)
+- **Design Target** — what Horizon UI is built for and how it differs from
booster-ui.
+- **Compatibility** — which OAP version + modules + ports Horizon needs, and
what each pane of the Cluster Status page actually probes.
+- **Setup** — quick start, the container image, and a field-by-field reference
for `horizon.yaml`.
+- **Access Control** — local + LDAP auth, break-glass admin, the role / verb
model, the audit log, and the admin pages.
+- **Customization** — how the sidebar is composed from OAP layers, how to
author layer dashboard and overview templates, and the end-to-end recipe for
adding a new layer.
+- **Components** — field-by-field reference for every widget primitive and the
wrapped chart components.
+- **Operate** — Cluster Status & Metadata, and the Inspect page (metric
catalog + entity enumerator).
+
+## Quick orientation
The UI is a pnpm monorepo:
| App / package | Purpose |
|---|---|
| `apps/ui/` | Vue 3 + Vite single-page app. |
-| `apps/bff/` | Fastify-based Backend For Frontend. Owns OAP connectivity,
session/auth, audit log, bundled templates. |
-| `packages/api-client/` | TypeScript types shared between BFF and UI
(widget/template shapes, menu response, dashboard scope enum, etc.). |
+| `apps/bff/` | Fastify-based Backend For Frontend. The single place that
talks to OAP — query GraphQL + admin REST + Zipkin. |
+| `packages/api-client/` | TypeScript types shared between BFF and UI. |
+| `packages/design-tokens/` | CSS custom properties shipped to both apps (the
5 bundled themes live here). |
-The UI **only** talks to the BFF; the BFF is the single place that talks to
OAP (GraphQL query port + admin REST port + Zipkin). This means every OAP-side
requirement in [Compatibility](compatibility/oap-version.md) is enforced once,
in the BFF, not scattered through the UI.
+The UI **only** talks to the BFF; the BFF is the single place that talks to
OAP. Every OAP-side requirement is enforced once, in the BFF, not scattered
through the UI.
-## Where to start
+## Where to start, by role
| If you are… | Read first |
|---|---|
-| Deploying Horizon for the first time | [Setup → Quick
Start](setup/overview.md), then [Compatibility → OAP
Version](compatibility/oap-version.md). |
-| Wiring up LDAP / configuring roles | [Access Control → LDAP
Backend](access-control/ldap-backend.md), then [RBAC](access-control/rbac.md). |
-| Customizing what shows up on a per-layer page | [Customization → Layer
Dashboard Templates](customization/layer-templates.md). |
-| Building a "war room" overview | [Customization → Overview
Templates](customization/overview-templates.md). |
-| Diagnosing a "module disabled" warning | [Compatibility → Required OAP
Modules](compatibility/required-modules.md) and [Cluster Status Check
Sequence](compatibility/cluster-status.md). |
+| Deploying Horizon for the first time | Setup → Quick Start, then
Compatibility → OAP Version. |
+| Wiring up LDAP / configuring roles | Access Control → LDAP Backend, then
RBAC. |
+| Customizing per-layer dashboards | Customization → Layer Dashboard
Templates. |
+| Building a "war room" overview | Customization → Overview Templates. |
+| Diagnosing a "module disabled" warning | Compatibility → Required OAP
Modules and Cluster Status Check Sequence. |
## Live demo
@@ -46,4 +49,10 @@ oap:
password: skywalking
```
-The demo exposes the GraphQL query port only; the admin REST port (and
therefore the Cluster, Inspect, DSL Management, and Live Debugger pages) is not
reachable from outside.
+The demo exposes the GraphQL query port only; the admin REST port — and
therefore the Cluster, Inspect, DSL Management, and Live Debugger pages — is
not reachable from outside.
+
+## References
+
+- [Apache SkyWalking](https://github.com/apache/skywalking) — the backend
Horizon UI consumes.
+- [skywalking-booster-ui](https://github.com/apache/skywalking-booster-ui) —
the previous-generation UI; Horizon is feature-equivalent against the same OAP
protocol.
+- [demo.skywalking.apache.org](https://demo.skywalking.apache.org) — public
OAP demo (basic auth `skywalking:skywalking`).
diff --git a/docs/compatibility/oap-version.md
b/docs/compatibility/oap-version.md
index c07d86b..05ceaf5 100644
--- a/docs/compatibility/oap-version.md
+++ b/docs/compatibility/oap-version.md
@@ -4,8 +4,6 @@
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 [...]
-> 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
diff --git a/docs/compatibility/required-modules.md
b/docs/compatibility/required-modules.md
index 574e289..1a0c420 100644
--- a/docs/compatibility/required-modules.md
+++ b/docs/compatibility/required-modules.md
@@ -18,7 +18,7 @@ The admin-port endpoints are gated by per-module selectors on
the OAP side. Hori
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 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 [...]
+The entire admin-port surface (all four modules) is **OAP 11.x only**. 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 entries are hidden. See [OAP
Version](oap-version.md) for the full feature-vs-version matrix.
## How Horizon detects module state
diff --git a/docs/operate/inspect.md b/docs/operate/inspect.md
index 119306c..670092c 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
**OAP 11.x only** — the page does not render on v10.
+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 OAP's **Inspect API**, which is
**v11-only** — the page does not render on v10.
## What the page is for
@@ -116,4 +116,3 @@ The BFF is a thin proxy — caching is per-request, not
cross-request. The Inspe
- [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.
