From 15eb7fb8d6474b54513bea5f04c348f830904fdd Mon Sep 17 00:00:00 2001 From: Alejandro Acevedo Date: Mon, 13 Jul 2026 16:57:37 +0200 Subject: [PATCH 1/2] STAC-24297: add worked OpenTelemetry webshop example to the generic scaffold template --- .../setup/custom-integrations/otelmappings/concepts.adoc | 5 +++++ .../setup/custom-integrations/presentation/concepts.adoc | 5 +++++ .../setup/custom-integrations/presentation/highlight.adoc | 5 +++++ .../custom-integrations/presentation/interpolation.adoc | 5 +++++ .../custom-integrations/presentation/metrics/README.adoc | 5 +++++ .../setup/custom-integrations/presentation/overview.adoc | 5 +++++ .../setup/custom-integrations/presentation/projections.adoc | 5 +++++ .../setup/custom-integrations/presentation/schemas-ref.adoc | 5 +++++ 8 files changed, 40 insertions(+) diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/otelmappings/concepts.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/otelmappings/concepts.adoc index daa841847..195a92ae6 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/otelmappings/concepts.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/otelmappings/concepts.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Open Telemetry Mappings Concepts +[TIP] +==== +*See it in the scaffold:* the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold builds a *specialization layer on top of the OpenTelemetry StackPack* — extending the generic `otel service` / `otel service instance` components with a domain-specific webshop view (its own types, relations and metrics) rather than re-observing the app. See the mapping examples under `settings/component-mappings/` and `settings/relation-mappings/`. +==== + == Component mappings An `OtelComponentMapping` describes how a topology component is created (or updated) from OpenTelemetry data. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/concepts.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/concepts.adoc index 3056e134f..d8174d68e 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/concepts.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/concepts.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: UI Presentation Concepts +[TIP] +==== +*See it in the scaffold:* the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold contains a worked, commented example of every concept on this page, built around a webshop (microservice instances and a database). Start with https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] and its base https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`settings/presentations/microservice.sty`]. +==== + [IMPORTANT] ==== *Status:* Under active development. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/highlight.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/highlight.adoc index bd5fd1d7b..215293ec7 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/highlight.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/highlight.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Component Presentation Schema +[TIP] +==== +*See it in the scaffold:* https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] in the https://github.com/StackVista/stackpack-templates[scaffold] defines a `highlight` section with fields, provisioning, related resources and events; https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/checkout.sty[`checkout.sty`] adds a `links` entry (string-template `target`/`tooltip` with a CEL `filter`); and https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/database.sty[`database.sty`] shows a related-resources panel in the opposite direction. +==== + == Highlight Defines fields and sections shown on highlight pages. For a component, all applicable presentations can contribute fields to display. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/interpolation.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/interpolation.adoc index e36213d2d..4319a540b 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/interpolation.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/interpolation.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Component Presentation Schema +[TIP] +==== +*See it in the scaffold:* the presentation and mapping files in the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold use both CEL expressions (for example `tags.singleValue('service.namespace')`) and `${...}` string templates throughout — see https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] and https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/component-mappings/microservices.sty[`settings/component-mappings/microservices.sty`]. +==== + == Interpolation When defining Component Presentations, a couple of different types of expressions are used. When selecting a value to xref:/setup/custom-integrations/presentation/projections.adoc[project] in a highlight field, or when controlling whether a highlight link is visible, a CEL expression can be used. Some string fields, such as highlight link `title`, `target`, and `tooltip`, use string templates with embedded CEL placeholders. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/metrics/README.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/metrics/README.adoc index fd5be8c70..ab58951cf 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/metrics/README.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/metrics/README.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: SUSE Observability +[TIP] +==== +*See it in the scaffold:* https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] in the https://github.com/StackVista/stackpack-templates[scaffold] defines a domain metric (the cart's add-to-cart latency) and attaches it to all three UI locations — summary, highlight metric section, and the metric perspective. It deliberately does *not* redefine the generic span metrics (rate / errors / duration): its binding is a subset of the generic OpenTelemetry service-instance presentation's binding, so those metrics are **inherited** by composition rather than duplicated. +==== + == Overview {stackstate-product-name} provides already many metric charts by default on most types of components that represent Kubernetes resources. Extra metric charts can be added to any set of components whenever needed. When adding metrics to components there are two options: diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/overview.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/overview.adoc index 7d2551a11..f1a027a7c 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/overview.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/overview.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Component Presentation Schema +[TIP] +==== +*See it in the scaffold:* https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`settings/presentations/microservice.sty`] in the https://github.com/StackVista/stackpack-templates[scaffold] defines the shared `overview` section with columns, sort, main-menu placement and filters; `cart.sty` and `checkout.sty` inherit that overview and reuse its columns/filters by id, and the menu group is defined in https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/main-menu.sty[`settings/main-menu.sty`]. +==== + == Overview Defines columns shown in overview tables. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/projections.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/projections.adoc index 975f6f681..c62815f73 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/projections.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/projections.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Component Presentation Schema +[TIP] +==== +*See it in the scaffold:* the presentation files in the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold use several projection types — Health, ComponentLink and Text in https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`microservice.sty`], and Metric and Tag in https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`cart.sty`]. +==== + == Projections Projections extract relevant information from a component and define how that should be presented to the user. Generally a xref:/setup/custom-integrations/presentation/interpolation.adoc[CEL expression] is used for data extraction, or a PromQL query string is interpolated. diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc index de8149380..33e1aa1b5 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc @@ -5,6 +5,11 @@ ifdef::ss-ff-stackpacks2_enabled[] :page-revdate: {revdate} :description: Component Presentation Schema +[TIP] +==== +*See it in the scaffold:* the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold has a full, commented `ComponentPresentation` you can copy from — https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] exercises most fields documented below, and https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`settings/presentations/microservice.sty`] shows composition by `rank.specificity` and a named topology `layer` + `domain`. +==== + [IMPORTANT] ==== *Status:* Under active development. From a9c45f21f8507e3c2203f43d3d39c0abb7fc8a50 Mon Sep 17 00:00:00 2001 From: Alejandro Acevedo Date: Tue, 14 Jul 2026 10:51:46 +0200 Subject: [PATCH 2/2] STAC-24297: Fix review comments --- .../presentation/schemas-ref.adoc | 30 +------------------ 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc index 33e1aa1b5..ca9c1d306 100644 --- a/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc +++ b/docs/latest/modules/en/pages/setup/custom-integrations/presentation/schemas-ref.adoc @@ -7,7 +7,7 @@ ifdef::ss-ff-stackpacks2_enabled[] [TIP] ==== -*See it in the scaffold:* the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold has a full, commented `ComponentPresentation` you can copy from — https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] exercises most fields documented below, and https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`settings/presentations/microservice.sty`] shows composition by `rank.specificity` and a named topology `layer` + `domain`. +*See it in the scaffold:* the https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] scaffold has a full, commented `ComponentPresentation` you can copy from — https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/cart.sty[`settings/presentations/cart.sty`] exercises most fields documented below, and https://github.com/StackVista/stackpack-templates/blob/main/templates/generic/settings/presentations/microservice.sty[`settings/presentations/microservice.sty`] shows composition by `rank.specificity`. ==== [IMPORTANT] @@ -67,21 +67,6 @@ rank: presentation: icon: !icon path # Optional icon - topology: # Optional - controls how matching components show up in the topology view - layer: # Optional - layer assigned to matching components - name: string # Layer name (free-form; the same name across presentations resolves to a single layer) - order: number # Vertical ordering of the layer in the view (higher numbers come first) - domain: # Optional - domain assigned to matching components (same shape as layer) - name: string - order: number - groupedByLayers: boolean # Optional - default grouping toggle - groupedByDomains: boolean # Optional - default grouping toggle - groupingEnabled: boolean # Optional - minimumGroupSize: number # Optional - autoGrouping: boolean # Optional - connectedComponents: boolean # Optional - showIndirectRelations: boolean # Optional - overview: # Optional overview page configuration name: # Naming configuration plural: string @@ -237,19 +222,6 @@ Presentation sections are composed when multiple definitions apply to the same c Defines iconography and naming used across the UI. Icons can be included by using the `!icon` yaml tag, followed by the path of an icon relative to the `icons/` folder. E.g. `!icon services/main-menu.svg` can be used when the stackpack includes the file `icons/services/main-menu.svg`. -=== Topology grouping (layer & domain) - -`topology.layer` and `topology.domain` place matching components in the topology view's layers and domains. -Both have the same shape: a `name` (used as the label) and an `order` (used to position it vertically — higher numbers come first). - -When multiple presentations match a component, the *most-specific* one (highest `rank.specificity`) contributes its `topology.layer` / `topology.domain`. -If no matching presentation provides one, the component shows up under `unknown`. - -Two notes worth keeping in mind: - -* *Specificity decides per component, not order.* A less-specific presentation cannot override a more-specific one by declaring a higher `order`. -* When several components contribute different orders for the *same* layer or domain name, the snapshot reports the *highest* order across them. This keeps the vertical position stable regardless of which component is queried first. - === Other sections Other sections of the presentation are described separately: