This is an automated email from the ASF dual-hosted git repository. wu-sheng pushed a commit to branch docs/accuracy-and-principles in repository https://gitbox.apache.org/repos/asf/skywalking-horizon-ui.git
commit 5fdeb72916b1ae941be2f496160f0794934e6cd2 Author: Wu Sheng <[email protected]> AuthorDate: Tue Jun 2 10:38:54 2026 +0800 docs: accuracy pass + concept-first config docs + principles; release tooling Bring the website docs in line with the current code after the 0.6.0 work, restructure the config docs around the UI (JSON as reference), codify the doc-writing principles, and make the post-vote finalize script Docker-Hub verify-only. CHANGELOG updated under 0.7.0. Staleness fixes - access-control/rbac.md + setup/rbac.md: document the `infra-3d:read` verb. - access-control/admin-pages.md: add `/admin/3d-map` (`overview:write`). - access-control/audit-log.md: rewrite the recorded-actions table to the actually-emitted actions; drop the never-emitted rows; fix the failure outcome format (`http_<code>`). - operate/inspect.md: correct the BFF routes to `/api/inspect/*`. - design-target.md: add the Topology overview widget. - customization/layer-templates.md: fix the components example to the real flag keys; add the `dependency` dashboard scope. - operate/infra-3d-map.md: rewrite Configuration for the redesigned model; add the Hierarchy pipeline stage. Config docs are concept-first - infra-3d-map / layer-templates / overview-templates lead with the concept and the admin UI; the JSON shape is a reference appendix. No raw-JSON editor exists on these pages, so the docs no longer imply one. Versioning - Docs no longer hardcode the Horizon version (the website pins docs per release); container-image.md stays as the release-tooling exception. i18n - i18n.md: language x scope coverage matrix. - adding-a-new-layer.md: add the "Add translations (i18n)" contributor step. docs/CLAUDE.md (new) - Operator-first, config-UI-first with JSON-as-appendix, no hardcoded versions, plus a carve-out for contributor pages. Release tooling - release-finalize.sh: the Docker Hub image is published by CI on `v*` tags; Step 5 now verifies the published tags, and the manual local-push fallback plus Docker Hub login preflight were removed. --- CHANGELOG.md | 15 +++++- docs/CLAUDE.md | 71 +++++++++++++++++++++++++++ docs/access-control/admin-pages.md | 1 + docs/access-control/audit-log.md | 24 ++++----- docs/access-control/rbac.md | 3 +- docs/customization/adding-a-new-layer.md | 21 +++++++- docs/customization/i18n.md | 17 +++++++ docs/customization/layer-templates.md | 25 ++++++---- docs/customization/overview-templates.md | 8 +-- docs/design-target.md | 1 + docs/operate/infra-3d-map.md | 73 ++++++++++++++++------------ docs/operate/inspect.md | 4 +- docs/setup/overview.md | 8 +-- docs/setup/rbac.md | 2 +- scripts/release-finalize.sh | 83 +++++++++----------------------- 15 files changed, 229 insertions(+), 127 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35509be..921875a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,20 @@ packages) plus the BFF's `HORIZON_VERSION` default. ## 0.7.0 -(In development — fill in highlights here before cutting the release.) +### Documentation & release tooling + +- The website docs were brought current with the 0.6.0 build and the + configuration pages restructured around the admin UI — the JSON shape is + now a reference appendix, not an authoring surface (these admin pages are + structured editors, not raw-JSON editors). Accuracy fixes span the RBAC + verbs (incl. `infra-3d:read`), the audit-log action set, the Metrics + Inspect API paths, the layer-template component flags, and the redesigned + 3D-map config + loading stages. A new `docs/CLAUDE.md` records the + doc-writing principles, and the i18n docs gain a language × scope coverage + matrix plus a translation step in the add-a-layer recipe. +- The container image is published to Docker Hub by CI on every `v*` tag; + the post-vote finalize script now only verifies the published tags (the + manual local-push fallback and Docker Hub login preflight were removed). ## 0.6.0 diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 0000000..bb5c5a6 --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1,71 @@ +# CLAUDE.md — Writing the Horizon UI docs + +`docs/` is the **public website documentation** for Horizon UI — a flat tree, +ordered by `menu.yml`, synced to the Apache SkyWalking website. It is written +for the people who **run and configure** Horizon (operators, dashboard +authors), not for contributors hacking on the code. These are the principles +for every page here. For the project-wide rules, see the root +[CLAUDE.md](../CLAUDE.md). + +## 1. Operator perspective first + +Document what a feature **does**, how to **configure** it, and how to +**operate / troubleshoot** it — observable behavior and configuration. + +Do **not** document the internals: + +- no source-file paths (`apps/bff/src/…`, `apps/ui/src/…`), +- no internal function / composable / store / route-handler names, +- no implementation narration ("the BFF then chunks / fans out / probes …"), +- no step-by-step retelling of the code's algorithm. + +If a sentence only makes sense to someone reading the source, it does not +belong in a doc. + +**One carve-out: contributor pages.** A few pages document repo / file-based +authoring that has no UI path — adding a new layer template, contributing a +translation catalog or a new locale. These are explicitly contributor-facing +and may reference repo files, `pnpm` commands, and the dev workflow; keep them +scoped to that task. Today: `customization/adding-a-new-layer.md` and the +contributor sections of `customization/i18n.md`. Everything else stays +operator-facing. + +## 2. Config is edited in the UI — lead with that; JSON is an appendix + +Almost everything configurable in Horizon (layer dashboards, overview +templates, the 3D-map config, alarm-page setup, global defaults, translations) +is edited through a **structured / visual admin page**, on a bundled default → +local draft → **Check diff & push** to OAP flow. A configuration page should: + +- **Start from the concept** — what this configuration is and what it controls. +- **Then the UI** — which admin page edits it and what the controls do. +- **Keep the JSON / schema as a reference appendix** at the end, framed as the + *stored* format the editor reads and writes (useful for understanding the + fields, or authoring as files), **not** as the primary "how to author" path. + +There is **no raw-JSON editor on these pages.** Never tell the reader to "edit +the JSON" on a page — they use the structured controls. The Monaco view that +appears is a read-only **diff** for review before pushing. + +## 3. Don't hardcode the Horizon version + +The website serves these docs **pinned per release**, so a version string in +the body is redundant and silently goes stale on the next release. By default, +write version-neutral: use a `<version>` placeholder in install commands, or +phrase around it. State a concrete version only when the content is genuinely +version-specific (a compatibility note, or a "new in X" call-out you +deliberately want pinned). + +The **one maintained exception** is `setup/container-image.md`: its image tags +track the current release and are advanced automatically by the release tooling +— leave them as concrete versions. + +## 4. Other house rules + +- **Tech terms and proper nouns stay verbatim** — SkyWalking, OAP, MQE, eBPF, + Kubernetes, Istio, GraphQL, layer keys (`GENERAL`, `MESH`), scope enums + (Service, Endpoint), metric ids. Don't translate or rename them. +- **Cross-link, don't duplicate.** One canonical page per concept; link to it + rather than restating it. +- **Add new pages to `menu.yml`.** A page that isn't in the menu isn't + navigable on the site. diff --git a/docs/access-control/admin-pages.md b/docs/access-control/admin-pages.md index 350c131..b8b1b41 100644 --- a/docs/access-control/admin-pages.md +++ b/docs/access-control/admin-pages.md @@ -114,6 +114,7 @@ Read-only. To change roles, edit `rbac.roles` in `horizon.yaml`; hot-reload appl | `/operate/inspect` | `inspect:read` | maintainer, operator, admin | | `/operate/ttl` | `ttl:read` | maintainer, operator, admin | | `/operate/config` | `config:read` | maintainer, operator, admin | +| `/admin/3d-map` | `overview:write` | operator, admin | `auth:read`, `user:read`, `role:read` are **not** in any default role. Either grant them via a custom role: diff --git a/docs/access-control/audit-log.md b/docs/access-control/audit-log.md index 125ab14..57008a2 100644 --- a/docs/access-control/audit-log.md +++ b/docs/access-control/audit-log.md @@ -10,10 +10,10 @@ Each event has these fields: |---|---| | `ts` | ISO-8601 timestamp. | | `actor` | Username, or `null` for system events. | -| `action` | Operation name, such as `auth.login` or `rule.addOrUpdate`. | +| `action` | Operation name, such as `auth.login` or `addOrUpdate`. | | `verb` | RBAC verb checked, when applicable. | | `target` | Resource id or name, when applicable. | -| `outcome` | `success`, `failure`, `break-glass`, or the upstream HTTP/OAP status. | +| `outcome` | `success` / `ok` / `break-glass` for normal flows; the OAP `applyStatus` or `http_<code>` on an upstream failure. | | `details` | Extra context for the operation. | | `fromIp` | Requester IP. | | `sessionId` | Session id, when a session exists. | @@ -26,21 +26,22 @@ tail -f horizon-audit.jsonl | jq -c 'select(.action | startswith("auth."))' ## Recorded actions -The recorded set can grow between releases. In 0.5.0: +The recorded set can grow between releases. The current set: | Action | Outcome values | Notes | |---|---|---| | `auth.login` | `success`, `failure` | Standard login. `details.backend` is `local` or `ldap`. On success `details.roles` carries the resolved role list. | | `auth.login.break-glass` | `break-glass` | Emergency admin login. Logged in addition to a WARN application log line. | | `auth.logout` | `success` | Explicit logout (cookie cleared). Sessions that simply expire are not logged. | -| `rule.addOrUpdate` | `success`, HTTP status on failure | DSL Management create / update. `target` is the rule name; `details` carries the diff summary. | -| `rule.delete` | `success`, HTTP status on failure | DSL Management delete. | -| `alarm-rule.addOrUpdate` | `success`, HTTP status on failure | Alarm Rule editor write. | -| `setup.write` | `success`, HTTP status on failure | Per-user setup state write. | -| `overview-template.write` | `success` | Overview template admin edits. | -| `layer-template.write` | `success` | Layer template admin edits. | +| `addOrUpdate` | OAP `applyStatus`, or `http_<code>` on failure | DSL Management — create / update a rule. `target` is the rule name; `details.catalog` is the rule catalog (alarm, MAL, OAL, …). | +| `inactivate` | OAP `applyStatus`, or `http_<code>` | DSL Management — deactivate a rule. | +| `delete` | OAP `applyStatus`, or `http_<code>` | DSL Management — delete a rule. `details.mode` is the delete mode. | +| `alarms.config.save` | `ok`, or an error status on failure | Alarm page setup save. | +| `setup.save` | `success`, or an error status on failure | Per-user setup state write (service / instance / endpoint setup). | +| `debug.start` | `ok`, or an error status on failure | Live Debugger — start a session. | +| `debug.stop` | `ok`, or an error status on failure | Live Debugger — stop a session. | -`outcome` is the literal string for normal flows (`success`, `failure`, `break-glass`) and a stringified HTTP / OAP status code when the underlying call failed. This makes audit-time error correlation straightforward: an entry with `outcome: "503"` tells you OAP returned a server error. +`outcome` is a short literal for normal flows (`success`, `ok`, or `break-glass`) and, when the underlying OAP call fails, the OAP `applyStatus` value or `http_<code>`. This makes audit-time error correlation straightforward: an entry with `outcome: "http_503"` tells you OAP returned a server error. ## Example entries @@ -93,10 +94,11 @@ The recorded set can grow between releases. In 0.5.0: { "ts": "2026-05-18T15:02:11.004Z", "actor": "alice", - "action": "rule.addOrUpdate", + "action": "addOrUpdate", "verb": "rule:write", "target": "service_resp_time_rule", "outcome": "success", + "details": { "catalog": "alarm" }, "fromIp": "10.0.5.12", "sessionId": "k7r..." } diff --git a/docs/access-control/rbac.md b/docs/access-control/rbac.md index 00e8963..0727d50 100644 --- a/docs/access-control/rbac.md +++ b/docs/access-control/rbac.md @@ -26,12 +26,13 @@ Known verbs are grouped into areas: | `topology:read` | Topology tab, topology widgets on overviews. | | `profile:read` | Profiling tab (results read-only). | | `overview:read` | Public overview dashboards. | +| `infra-3d:read` | 3D Infrastructure Map — the map's config + live traffic metrics. | ### Operate — dashboards, rules, diagnostics | Verb | Gates | |---|---| -| `overview:write` | Overview templates admin page (`/admin/overview-templates`): edit. | +| `overview:write` | Overview templates (`/admin/overview-templates`) and the 3D-map config (`/admin/3d-map`): edit / publish. | | `dashboard:read` / `dashboard:write` | Layer dashboard templates admin page: list / edit. | | `alarm-setup:read` / `alarm-setup:write` | Alarm Setup page: list / edit. | | `alarm-rule:read` / `alarm-rule:write` | Alarm Rule catalog: list / edit. | diff --git a/docs/customization/adding-a-new-layer.md b/docs/customization/adding-a-new-layer.md index f600edc..2a06cd0 100644 --- a/docs/customization/adding-a-new-layer.md +++ b/docs/customization/adding-a-new-layer.md @@ -90,7 +90,23 @@ Bundled template changes need a BFF restart (templates are loaded once at startu Each iteration is template + BFF restart. The schema is validated at startup; a bad template logs the error and falls back to defaults — check the BFF logs. -### 9. Promote to admin-editable (optional) +### 9. Add translations (i18n) + +The template's English strings — the layer `alias`, any `aliases.*`, `slots`, and the widget titles / KPI labels / group titles / tooltips inside `dashboards` — are the i18n source. Generate the sibling overlay catalogs so the layer renders in every shipped language: + +```sh +pnpm --filter @skywalking-horizon-ui/bff i18n:seed +``` + +This walks every bundled template and writes one `<your-key>.i18n.<locale>.json` per non-English locale (`de`, `es`, `fr`, `ja`, `ko`, `pt`, `zh-CN`), pre-filling shared widget vocabulary from the lexicon. Existing translations are preserved — only gaps are added. Fill the layer-specific prose you care about in each overlay (anything left blank falls back to English at render), then check for drift: + +```sh +pnpm --filter @skywalking-horizon-ui/bff i18n:validate +``` + +See [Languages and Translations](i18n.md) for the language × scope coverage, the shared lexicon, and how to add a brand-new locale. + +### 10. Promote to admin-editable (optional) Once the template stabilizes: @@ -99,7 +115,7 @@ Once the template stabilizes: The local bundled file remains the fallback. After you publish, the OAP-stored template becomes the runtime copy every Horizon instance reads. -### 10. Add an overview entry (optional) +### 11. Add an overview entry (optional) If the new layer belongs in a war-room view: @@ -141,4 +157,5 @@ OAP-side rename means a new enum key. Horizon will see the old key go inactive ( - [Layer Dashboard Templates](layer-templates.md) — field reference. - [Menu Structure](menu-structure.md) — how the sidebar composes layers. - [Overview Templates](overview-templates.md) — cross-layer dashboards. +- [Languages and Translations](i18n.md) — translating the template's strings. - [Components → Dashboard Widgets](../components/dashboard-widgets.md) — widget primitive reference. diff --git a/docs/customization/i18n.md b/docs/customization/i18n.md index 520b4cc..0d728a4 100644 --- a/docs/customization/i18n.md +++ b/docs/customization/i18n.md @@ -21,6 +21,20 @@ in English first; the other locales are catalog overlays. Missing keys fall back to English at the leaf, never at the file — a half-translated catalog renders strictly better than English-only. +## Coverage by scope + +All eight languages are first-class across the surfaces Horizon controls. The scope decides **where** the translation resolves: + +| Scope | Resolves | Languages | +|---|---|---| +| UI chrome — buttons, labels, modals, login, topbar, sidebar | In the browser (vue-i18n) | All 8 | +| Bundled layer-dashboard templates | On the BFF, from sibling overlay catalogs | All 8 | +| Bundled overview templates | On the BFF | All 8 | +| User-maintained dashboards saved to OAP | On the BFF, from each dashboard's embedded `i18n` block | English + whatever the author provides | +| OAP-supplied data — service / instance / endpoint / alarm names, tags, log lines, trace ops | not translated | rendered verbatim | + +A missing key in any translated scope falls back to English at the leaf, so a partially-translated catalog renders better than English-only. + ## Picking a language The locale picker lives in the topbar (next to the theme chip) and on @@ -124,3 +138,6 @@ pnpm --filter @skywalking-horizon-ui/bff i18n:validate It rejects catalog keys that no longer match the source template, non-string values at translatable paths, and lexicon entries that aren't present in the source `en.json` lexicon registry. + +When you add a **new layer**, generating its template's translations is part +of that workflow — see [Adding a New Layer](adding-a-new-layer.md). diff --git a/docs/customization/layer-templates.md b/docs/customization/layer-templates.md index eb00a03..d35adb3 100644 --- a/docs/customization/layer-templates.md +++ b/docs/customization/layer-templates.md @@ -2,9 +2,9 @@ A **layer template** is a single JSON file that describes everything Horizon needs to know about one OAP layer: its display name, color, sidebar grouping, which sub-tabs to expose, the service-list picker columns, the per-scope widget grids, the trace/log/topology routing, and the service-name parsing rule. -There is **one template per layer**, stored under `apps/bff/src/bundled_templates/layers/<key>.json` (lowercase filename matches the OAP layer enum, e.g. `general.json` for the `GENERAL` layer). +There is **one template per layer**. Horizon ships a bundled template for every supported layer, and an administrator customizes them in the **Layer Dashboards** admin page (under *Dashboard setup*) — a visual editor that saves a local draft and publishes to OAP with **Check diff & push**. You don't hand-edit JSON on the page; the shape documented below is the stored format the editor reads and writes, useful for understanding what each control maps to and for authoring templates as files. -## Top-level shape +## Template shape (reference) ```json { @@ -22,6 +22,7 @@ There is **one template per layer**, stored under `apps/bff/src/bundled_template "service": [ ... widgets ... ], "instance": [ ... widgets ... ], "endpoint": [ ... widgets ... ], + "dependency":[ ... widgets ... ], "topology": [ ... widgets ... ], "trace": [ ... widgets ... ], "logs": [ ... widgets ... ], @@ -83,17 +84,21 @@ Per-tab feature toggles. A `false` value hides the tab. ```json "components": { - "service": true, - "instance": true, - "endpoint": true, - "topology": true, - "trace": true, - "logs": false, - "profiling": true + "service": true, + "instances": true, + "endpoints": true, + "endpointDependency": true, + "topology": true, + "traces": true, + "logs": true, + "traceProfiling": true, + "ebpfProfiling": false, + "asyncProfiling": false, + "pprofProfiling": false } ``` -The landing tab when a layer is clicked is the **first enabled** in the priority order `service → instance → endpoint → topology → trace → logs → profiling`. +The keys are the per-layer sub-tabs. `networkProfiling` and `podLogs` are also available; any key omitted defaults to enabled. The landing tab when a layer is clicked is the **first enabled** in the priority order `service → instances → endpoints → endpointDependency → topology → traces → logs → traceProfiling`. ## `header` diff --git a/docs/customization/overview-templates.md b/docs/customization/overview-templates.md index 24a1cce..6e8be11 100644 --- a/docs/customization/overview-templates.md +++ b/docs/customization/overview-templates.md @@ -2,12 +2,12 @@ An **overview template** is a JSON file describing a war-room / cross-cutting dashboard composed from MQE-driven widgets on a 12-column grid. Overviews are independent of any single layer and are designed for the operator's "is everything OK?" pane. -Bundled templates: `apps/bff/src/bundled_templates/overviews/<id>.json`. Examples: +Horizon ships bundled overview templates, and an administrator customizes them in the **Overview Templates** admin page (`/admin/overview-templates`, under *Dashboard setup*) — a visual editor that saves a local draft and publishes to OAP with **Check diff & push**. You don't hand-edit JSON on the page; the shape documented below is the stored format the editor reads and writes. Bundled examples: -- `services.json` — cross-layer service health + Kubernetes capacity summary. -- `mesh.json` — Istio data-plane services + pilot activity + Kubernetes. +- **Service Health** — cross-layer service health + Kubernetes capacity summary. +- **Mesh** — Istio data-plane services + pilot activity + Kubernetes. -## Top-level shape +## Template shape (reference) ```json { diff --git a/docs/design-target.md b/docs/design-target.md index 49fbf83..e9fed63 100644 --- a/docs/design-target.md +++ b/docs/design-target.md @@ -23,6 +23,7 @@ Horizon ships dedicated widget primitives for observability stacks instead of ge - **KpiTileWidget** — compound tile combining a service count with N KPI rows (number or progress-bar style). - **MetricCompositeWidget** — mixed-style KPI grid (e.g., Kubernetes cluster summary: node count + CPU/memory progress bars). - **AlarmsWidget** — read-only active-incident rail with a 60-minute window, dual-mode (modern `queryAlarms` capability + legacy `getAlarm` fallback). +- **Topology** — embedded service-map snapshot for the configured layer, showing live services and call flows on an overview. - **TimeChart** — multi-series line chart with dual y-axis, synced crosshairs across all widgets on the same page. - **TopList** — top-N sorted list with optional tab switcher for multiple expressions. - **AlarmsTimeline** — per-minute stacked bar with brush selection for triage. diff --git a/docs/operate/infra-3d-map.md b/docs/operate/infra-3d-map.md index cbac6aa..95f21d7 100644 --- a/docs/operate/infra-3d-map.md +++ b/docs/operate/infra-3d-map.md @@ -128,8 +128,12 @@ progress live: 1. **Services** — the service roster and which layers they belong to. 2. **Templates** — which layers carry a topology. 3. **Topologies** — each topology-bearing layer's call graph. -4. **Layout** — placing the cubes. -5. **Metrics** — the per-service traffic numbers, fetched in batches so +4. **Hierarchy** — the cross-tier identity links between the different + views of the same service. Only services that are new since the last + run are fetched; the rest are reused, so a steady deployment costs + nothing here on refresh. +5. **Layout** — placing the cubes. +6. **Metrics** — the per-service traffic numbers, fetched in batches so the cubes light up progressively. Each step shows its status as the map builds; click a step to open a @@ -139,33 +143,42 @@ strip re-runs the whole sequence. ## Configuration -The map is driven by a global configuration that an administrator edits -at `/admin/3d-map` (linked under **Dashboard setup** in the sidebar). -The editor is the same dark, dense surface as the rest of Horizon's -admin pages, with a structured form plus an advanced raw-JSON view. - -From it you can: - -- **Filter layers** — a global filter, plus a per-tier filter, to choose - which layers appear on the map. -- **Arrange tiers** — rename tiers, reorder them top-to-bottom, and - assign each layer to a tier. +What the map shows is driven by a single configuration that an +administrator edits in the UI at `/admin/3d-map` (linked under +**Dashboard setup** in the sidebar). It is a **structured editor** — you +work with tiers, layers, colors, and metrics through form controls, not +raw JSON. Horizon ships a bundled default so the map is useful out of the +box; your edits are kept as a local draft in your browser, and **Check +diff & push** publishes them to OAP — which is the copy the map then +renders (falling back to the bundled default if OAP has none). + +From the editor you can: + +- **Filter layers** — one global layer filter, written as a regex. A + layer it excludes is dropped from the map entirely. This is the only + filter; everything it admits is then placed on a tier. +- **Arrange tiers** — rename tiers, reorder them top-to-bottom, and pin + each layer to a tier. A layer you don't pin lands on the **failover + tier** you nominate, so nothing silently falls off the map. +- **Group layers** — cluster several related layers (for example the + SkyWalking self-observability components) into one labelled block on a + tier, while each member keeps its own cube color. - **Color layers** — pick each layer's brand color (used for the cube, zone, and stamp). -- **Choose traffic metrics** — pick the throughput metric and unit each - layer's cubes display. Topology layers can carry both a server-side and - client-side metric (the server side is preferred, with the client side - as a fallback); other layers carry a single load metric. The bundled - defaults are seeded from each layer's dashboard template, so most - layers show a sensible number out of the box. -- **Style connections** — adjust the color and weight of the in-layer, - cross-layer, and hierarchy lines. - -Saving takes effect the next time the map is opened. A **Reset to -bundled** action restores the shipped defaults for review before saving. - -The bundled configuration is the read-only baseline; saved changes -shadow it. Both the map and the editor are gated by access control — any -signed-in user with read access can view the map, while editing the -configuration requires the 3D-map write permission (granted to operators -and admins by default). See [Roles and Permissions](../access-control/rbac.md). +- **Choose a traffic metric** — for each layer, set the single throughput + metric its cubes display: the MQE expression, a display label, and a + unit. The bundled defaults are seeded from each layer's dashboard + template, so most layers show a sensible number out of the box. + +A read-only **Service-map layers** list shows which layers lay their +cubes out as a call graph — that comes from each layer's template (its +service-map capability), not from this page. + +Pushed changes take effect the next time the map is opened. A **Reset** +action reloads either the shipped bundled default or OAP's current +version, so you can start over before saving. + +Viewing the map needs read access (`infra-3d:read`, held by the built-in +viewer role and above); editing and publishing the configuration needs +`overview:write` (operators and admins by default). See +[Roles and Permissions](../access-control/rbac.md). diff --git a/docs/operate/inspect.md b/docs/operate/inspect.md index 5c9dd4d..6f374c7 100644 --- a/docs/operate/inspect.md +++ b/docs/operate/inspect.md @@ -24,7 +24,7 @@ If any of these is missing, the page surfaces a hint banner directing the operat ## Catalog browser -**Endpoint:** `GET /inspect/metrics?regex=<pattern>&type=<type>&catalog=<catalog>&mqeQueryable=<bool>` +**Endpoint:** `GET /api/inspect/metrics?regex=<pattern>&type=<type>&catalog=<catalog>&mqeQueryable=<bool>` Filters: @@ -48,7 +48,7 @@ The list is virtualized — a typical OAP exposes hundreds of metrics; scrolling ## Entity enumerator -**Endpoint:** `GET /inspect/entities?metric=<name>&start=<...>&end=<...>&step=<DAY|HOUR|MINUTE>&limit=<n>` +**Endpoint:** `GET /api/inspect/entities?metric=<name>&start=<...>&end=<...>&step=<DAY|HOUR|MINUTE>&limit=<n>` For a chosen metric, OAP returns the set of entities that have data in the window. Useful for: diff --git a/docs/setup/overview.md b/docs/setup/overview.md index 9abdae4..614de02 100644 --- a/docs/setup/overview.md +++ b/docs/setup/overview.md @@ -12,11 +12,11 @@ This page is the shortest path from "no Horizon" to "Horizon in front of a runni ### 1. Unpack Horizon -Unpack the binary tarball and copy the example config: +Unpack the binary tarball (substitute the release version you downloaded for `<version>`) and copy the example config: ```sh -tar -xzf apache-skywalking-horizon-ui-0.5.0-bin.tar.gz -cd apache-skywalking-horizon-ui-0.5.0-bin +tar -xzf apache-skywalking-horizon-ui-<version>-bin.tar.gz +cd apache-skywalking-horizon-ui-<version>-bin cp horizon.example.yaml horizon.yaml ``` @@ -100,7 +100,7 @@ docker run -d --name horizon \ -p 8081:8081 \ -v "$PWD/horizon.yaml:/app/horizon.yaml:ro" \ -v horizon-state:/data \ - ghcr.io/apache/skywalking-horizon-ui:0.5.0 + ghcr.io/apache/skywalking-horizon-ui:<version> ``` See [Container Image](container-image.md) for image tags, Kubernetes YAML, log handling, and probes. diff --git a/docs/setup/rbac.md b/docs/setup/rbac.md index 963e83b..5120ad0 100644 --- a/docs/setup/rbac.md +++ b/docs/setup/rbac.md @@ -31,7 +31,7 @@ rbac: | Role | Purpose | Grants | |---|---|---| -| `viewer` | Read-only data catalog and public overviews. | `metrics:read`, `alarms:read`, `traces:read`, `logs:read`, `topology:read`, `profile:read`, `overview:read`. Deliberately not `*:read` so the viewer cannot see rule definitions, live-debug sessions, setup screens, or platform internals. | +| `viewer` | Read-only data catalog and public overviews. | `metrics:read`, `alarms:read`, `traces:read`, `logs:read`, `topology:read`, `profile:read`, `overview:read`, `infra-3d:read`. Deliberately not `*:read` so the viewer cannot see rule definitions, live-debug sessions, setup screens, or platform internals. | | `maintainer` | Viewer + platform monitoring. | viewer baseline + `cluster:read`, `ttl:read`, `config:read`, `inspect:read`. | | `operator` | Configures observability. | maintainer baseline + `overview:write`, `setup:read/write`, `dashboard:read/write`, `alarm-setup:read/write`, `alarm-rule:read/write`, `rule:*` (including `rule:write:structural`, `rule:delete`, `rule:debug`), `live-debug:*`, `profile:enable`. | | `admin` | Unrestricted. | `*`. | diff --git a/scripts/release-finalize.sh b/scripts/release-finalize.sh index c160c00..e901818 100755 --- a/scripts/release-finalize.sh +++ b/scripts/release-finalize.sh @@ -39,16 +39,16 @@ # 3. Verify the Docker Hub multi-arch image — CI's publish-image # workflow mirrors the GHCR image to Docker Hub automatically on # every `v*` tag push (apache/skywalking-ui:horizon-<v> and -# apache/skywalking-ui:latest). This step just confirms the two -# expected tags are present. Falls back to a manual local mirror -# (same `docker buildx imagetools create` CI runs) if CI didn't -# publish — needs Docker Hub push rights on apache/skywalking-ui. +# apache/skywalking-ui:latest). This step only CONFIRMS the two +# expected tags are present; publishing is CI's job. There is no +# local-push fallback — if the tags are missing, re-run the +# publish-image workflow and re-run this script. # # Usage: bash scripts/release-finalize.sh # # The script is idempotent-ish and confirms before every irreversible step -# (SVN move, SVN delete, gh release, each image push). Nothing destructive -# happens without a y/N. +# (SVN move, SVN delete, gh release). Nothing destructive happens without +# a y/N. The Docker Hub image is published by CI, not here. set -e -o pipefail @@ -80,7 +80,7 @@ svn_exists() { note "Step 1 — Tool + auth preflight" MISSING=() -for t in svn gh git docker shasum curl node; do +for t in svn gh git docker shasum curl; do command -v "$t" >/dev/null || MISSING+=("$t") done if [ ${#MISSING[@]} -gt 0 ]; then @@ -89,8 +89,8 @@ if [ ${#MISSING[@]} -gt 0 ]; then fi if ! docker buildx version >/dev/null 2>&1; then - err "docker buildx is required (Step 5 uses 'imagetools create' to copy" - err "the CI-built multi-arch manifest from GHCR to Docker Hub)." + err "docker buildx is required (Step 5 uses 'imagetools inspect' to" + err "verify the CI-published Docker Hub tags)." exit 1 fi @@ -101,21 +101,6 @@ if ! gh auth status >/dev/null 2>&1; then fi echo "gh: $(gh auth status 2>&1 | grep -m1 'Logged in' | sed 's/^[[:space:]]*//')" -# Docker Hub: confirm a stored login. The push itself will 403 if the -# logged-in account lacks push rights to the apache org — surface the -# identity now so a wrong account is caught before the long build. -DOCKER_USER=$(printf 'https://index.docker.io/v1/' | docker-credential-desktop get 2>/dev/null \ - | node -e "let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(s).Username||'')}catch(e){}})" 2>/dev/null || true) -if [ -z "${DOCKER_USER}" ]; then - echo "Could not read a Docker Hub login from the credential store." - echo "If you are not logged in, run: docker login" - confirm "Continue anyway (the push will fail if not authorized)?" || { echo "Aborted."; exit 1; } -else - echo "Docker Hub login: ${DOCKER_USER}" - echo " NOTE: pushing to ${DOCKERHUB_REPO} needs this account to have push rights" - echo " in the 'apache' Docker Hub org. The push 403s otherwise." -fi - # ========================== Step 2: Detect version ========================== note "Step 2 — Detect release version" @@ -263,55 +248,31 @@ else fi fi -# ========================== Step 5: Docker Hub multi-arch image ========================== -note "Step 5 — Docker Hub image: ${DOCKERHUB_REPO}" +# ========================== Step 5: Verify Docker Hub image ========================== +note "Step 5 — Verify Docker Hub image: ${DOCKERHUB_REPO}" # CI (.github/workflows/publish-image.yaml) mirrors the multi-arch image # to Docker Hub automatically on every `v*` tag push, so by the time -# you're finalizing a passed vote this should already be live. We just -# verify the two expected tags are present. -# -# Fallback: if CI didn't publish (workflow failed / secrets missing / -# tag pushed before this workflow shipped), we fall back to the manual -# `docker buildx imagetools create` mirror from the GHCR canonical tag -# — same operation CI does, run locally. That needs Docker Hub push -# rights on `apache/skywalking-ui`. +# you're finalizing a passed vote it is already live. This step only +# VERIFIES the expected tags are present — publishing is CI's job, there +# is no local-push fallback. DH_VERSION_TAG="${DOCKERHUB_REPO}:horizon-${RELEASE_VERSION}" DH_LATEST_TAG="${DOCKERHUB_REPO}:latest" -GHCR_SRC="ghcr.io/apache/skywalking-horizon-ui:${RELEASE_VERSION}" echo "Expected on Docker Hub:" echo " ${DH_VERSION_TAG} (immutable, this release)" echo " ${DH_LATEST_TAG} (moving — newest Horizon release)" if docker buildx imagetools inspect "${DH_VERSION_TAG}" >/dev/null 2>&1; then - echo "✓ ${DH_VERSION_TAG} already on Docker Hub — CI's publish-image mirror succeeded." - echo " Verify: docker buildx imagetools inspect ${DH_VERSION_TAG}" + echo "✓ ${DH_VERSION_TAG} is on Docker Hub — CI's publish-image mirror succeeded." + echo " Inspect: docker buildx imagetools inspect ${DH_VERSION_TAG}" else - echo "✗ ${DH_VERSION_TAG} NOT on Docker Hub yet." - echo " This is the expected outcome only if the publish-image workflow" - echo " failed or didn't run on tag ${TAG}. Check:" - echo " https://github.com/apache/skywalking-horizon-ui/actions/workflows/publish-image.yaml"; - if ! docker buildx imagetools inspect "${GHCR_SRC}" >/dev/null 2>&1; then - err "Source ${GHCR_SRC} not on GHCR either — CI didn't produce a multi-arch" - err "image to mirror. Re-run publish-image on ${TAG} from the Actions UI" - err "and then re-run this script." - exit 1 - fi - if confirm "Fall back to a manual local mirror from ${GHCR_SRC}?"; then - docker buildx imagetools create \ - -t "${DH_VERSION_TAG}" \ - -t "${DH_LATEST_TAG}" \ - "${GHCR_SRC}" - echo "Pushed multi-arch manifest to ${DOCKERHUB_REPO}." - else - echo "Skipped Docker Hub push — fix CI and re-run, OR run the imagetools" - echo "create manually:" - echo " docker buildx imagetools create \\" - echo " -t ${DH_VERSION_TAG} \\" - echo " -t ${DH_LATEST_TAG} \\" - echo " ${GHCR_SRC}" - fi + err "✗ ${DH_VERSION_TAG} is NOT on Docker Hub." + err " CI's publish-image workflow did not mirror tag ${TAG}. The SVN promote +" + err " GitHub release above already succeeded; only the image is missing. Re-run" + err " the workflow (workflow_dispatch with tag ${TAG}), then re-run this script:" + err " https://github.com/apache/skywalking-horizon-ui/actions/workflows/publish-image.yaml"; + exit 1 fi # ========================== Done ==========================
