Presentation Overview

See it in the scaffold: settings/presentations/microservice.sty in the 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 settings/main-menu.sty.

Overview

Defines columns shown in overview tables.

Columns may override or extend columns defined by other matching presentations.

Main menu

Controls whether matching components appear in the main menu. The menu item will open an overview page with components that match the binding query.

mainMenu:
  group: "Open Telemetry"
  icon: !icon "service.svg"
  order: 2

When the icon field is left empty, the icon on the ComponentPresentation itself will be used. The group matches a main menu group by name. The order field determines the position of the menu item in the group. An item with a higher value comes closer to the top.

The referenced menu group must be defined separately using MainMenuGroup:

_type: MainMenuGroup
identifier: urn:...:main-menu-group:<group-name>
name: string
description: string           # Optional description
defaultOpen: boolean
order: number                 # Optional. Determines the position of the group in the main menu.
specificity: number           # Optional. Higher specificity overrides less specific definitions of the same group.
iconbase64: string            # Either a base64-encoded image, or a `!icon` reference to a separate image file
items:                        # Optional - kept for backwards compability, not needed for component presentations
  - viewIdentifier: string    # identifier for a (legacy) view

The order field determines the position of the group in the main menu. A group with a higher value comes closer to the top, consistent with the ordering of menu items within a group. Groups without an order are placed at the bottom.

For backwards compatibility it is possible to list views in a group under items. Component presentations are added automatically to the group; they do not need to be added explicitly.

Overriding a main menu group

Main menu groups are merged by name: defining several MainMenuGroup settings with the same name results in a single group. The specificity field controls how the merge resolves conflicts:

  • Scalar fields (defaultOpen, order, description, iconbase64) are taken from the definition with the highest specificity. This is how a built-in group can be customized — for example, defining a more specific MainMenuGroup with defaultOpen: false to collapse a group that ships open by default.

  • items are always merged across all definitions, never replaced.

A definition without a specificity is treated as the lowest specificity (0). The recommended ranges, matching the convention used elsewhere in the presentation system, are:

Range Use

1–99

Environment & infrastructure

100–199

Platform & orchestration (Kubernetes, base integrations)

200–299

Application / service

300–399

Runtime / SDK / language

400+

User overrides

Although the field name suggests otherwise, the icon can be specified as !icon path-to-the-icon. This is again for backwards compatibility.

Columns

The overview section in the component presentation defines which columns should be shown and in what order. It also specifies what columns should remain in-view when scrolling horizontally, when the browser windows is too narrow to show all columns in full.

Column definitions can be completely spelled out, including title and projection, but it is also possible to inherit from other presentations. Based on the binding query, other component presentations with the same query or a strictly more generic one are considered.

Sorting

The sort field defines the default sort order for the overview table. Each entry references a columnId from the columns list and an optional direction.

overview:
  columns:
    - columnId: "health"
      title: "Health"
      projection:
        _type: HealthProjection
        value: healthState
    - columnId: "name"
      title: "Name"
      projection:
        _type: TextProjection
        value: name
  sort:
    - columnId: "health"
      direction: Descending

If direction is omitted, it defaults to Ascending. When no sort is defined at all, the overview table sorts by the first sortable column in ascending order.

Which columns are sortable

Not every projection type supports sorting. The table below shows which projections are sortable:

Projection Sortable

HealthProjection

TextProjection

1

NumericProjection

1

ComponentLinkProjection

1

ContainerImageProjection

1

RatioProjection

2

MetricProjection

DurationProjection

MapProjection

1 Sortable only when the CEL expression is fully index-based (uses indexed component attributes only).
2 Sortable only when the status expression is present and fully index-based.

Validation and runtime behavior

Sort configuration is checked at two stages:

Ingestion validation

When a ComponentPresentation is ingested, the following is validated:

  • The columnId in each sort entry must reference a column defined in overview.columns.

  • If the referenced column has a locally defined projection, that projection must be sortable.

  • If the column’s projection is not locally defined (it will be inherited from a more generic presentation), validation is deferred to runtime.

Runtime resolution

At runtime, after all matching presentations are merged, any sort entries that reference non-sortable columns are silently filtered out. A warning is logged when this happens. If all configured sort entries are filtered out, the overview falls back to sorting by the first sortable resolved column in ascending order.

Filters

Defines filters shown for overview pages. They can inherit their definition from more generic component presentations, in which case just specifying the filterId is sufficient. Other properties (displayName, filter and menuSection) are merged. The most specific component presentation with a property set for a filter, determines its value.

The menuSection is relevant when there are more filters than fit in the available area in the overview menu. Filters with the same menuSection are then grouped together in a dropdown.

There is currently one type of filter available: * TagFilter: allows filtering on a tag key-value combination

- filterId: "otel_service"
  displayName:
    singular: "OTEL service"
    plural: "OTEL services"
  filter:
    _type: "TagFilter"
    tagKey: "service.name"
  menuSection: Otel

The intention is for filters to persist when navigating between overview pages. So if at all possible, try to reuse the same filter ids (with the same semantics) across different component presentations. The filters defined for all OTEL components are

  • otel_namespace (tag key service.namespace, menu section "Otel")

  • otel_service (tag key service.name, menu section "Otel")

  • k8s_namespace (tag key namespace, menu section "K8s")

  • k8s_cluster (tag key cluster-name, menu section "K8s")