Dashboard Spec

A dashboard file is a Perses-style resource with three top-level keys. Everr validates it on everr apply and again on read; the whole document is stored verbatim, so unknown Perses fields (at the top level or inside spec) survive a read/apply round-trip unchanged. (The folder path is the one piece of state kept outside the document: it's derived from the file's directory, not declared in the file.)

kind: Dashboard
metadata:
  name: <slug>
  project: platform        # optional; defaults to "default"
spec:
  { ... }

spec

Display

display:
  name: API Latency        # optional
  description: ...         # optional

Panel

<panel-key>:
  kind: Panel
  spec:
    display: { name: ..., description: ... }   # description optional
    plugin:
      kind: TimeSeriesChart | Table | StatChart
      spec: { ... }                            # see Visualizations reference
    queries:                                    # optional
      - kind: ClickHouseSQL
        spec:
          plugin:
            kind: ClickHouseSQL
            spec:
              query: "SELECT ..."

Query parameters

Every dashboard query (panel queries and variable options queries alike) is run with these ClickHouse parameters bound. They are always provided (referencing them never errors, and unreferenced parameters are ignored), but they are not injected into the SQL: the query must reference them. Usage guide: Time range parameters.

Grid layout

layouts:
  - kind: Grid
    spec:
      display: { title: ..., collapse: { open: true } }   # optional
      items:
        - x: 0
          y: 0
          width: 12
          height: 8
          content: { $ref: "#/spec/panels/<panel-key>" }

Variables

A discriminated union on kind. Full guide: Variables.

TextVariable:

- kind: TextVariable
  spec:
    name: search
    value: ""
    display: { name: Search, hidden: false }   # optional
    constant: false                            # optional

ListVariable:

- kind: ListVariable
  spec:
    name: service
    display: { name: Service, hidden: false }   # optional
    defaultValue: ""        # string, or [..] when allowMultiple   (optional)
    allowMultiple: false    # optional
    allowAllValue: false    # optional
    customAllValue: ""      # optional; substituted when "All" is selected
    sort: none              # optional; see below
    capturingRegexp: ""     # optional; accepted, no runtime effect
    plugin:
      kind: StaticListVariable | ClickHouseSQLVariable
      spec:
        values: [a, b]      # StaticListVariable
        # query: "SELECT ..."   # ClickHouseSQLVariable (first column = options)

sort accepts: none, alphabetical-asc, alphabetical-desc, numerical-asc, numerical-desc, alphabetical-ci-asc, alphabetical-ci-desc.

Slug rules

The slug (from metadata.name; set it explicitly under the <slug>.dashboard.yaml naming convention) must:

• use only lowercase letters, digits, and hyphens,
• not start or end with a hyphen,
• be 1 to 200 characters.

A slug must be unique within a project; applying two files that resolve to the same slug within the same project fails.

Time defaults

Use timeRange for a dashboard's default range:

timeRange:
  from: now/M
  to: now

Everr date math supports fixed windows such as now-24h and calendar-aligned ranges such as now/M (the start of this month). Everr seeds missing URL time-range parameters from timeRange and refreshInterval. Explicit URL parameters always win, so shared links keep their exact range.

Perses dashboards that declare duration are still accepted. At the resource boundary, Everr converts duration: 24h to { from: now-24h, to: now }. If both fields are present, timeRange wins. Everr-authored dashboards should use timeRange.

Compatibility boundaries

The format mirrors Perses so files stay portable, but a few fields are accepted without runtime behavior in Everr today: datasources, variable capturingRegexp, and variable chaining/aliases (see Variables → Not supported). The only query plugin executed is ClickHouseSQL.