Skip to content

Features

Dashboards

Grafana-style dashboards over PromQL, and Kibana-style panels over the stored logs, stored by orbit-api and drawn by the Deck at /deck/dashboards. Five ship with the product and are read-only; everyone who holds dashboards.write can create more, edit them, copy the built-in ones, start one from a template and import dashboards exported from Grafana. The model and its limits are CONTRACT.md Addendum v0.5; the log panels are its Addendum log-dashboards.

Built-in dashboards

Embedded in the orbit-api binary, the same on every install, and read-only for everyone: "Save as copy" makes an editable one. Their uids start with orbit-, a prefix no saved dashboard can take.

uidTitleReadsVariables
orbit-k8s-clusterKubernetes / Clusterkube-state-metrics and the kubelet's cAdvisornone
orbit-k8s-workloadsKubernetes / Workloadskube-state-metrics and cAdvisor, for one namespacenamespace, pod
orbit-nodesNodesnode-exporterinstance
orbit-apm-redAPM / Service REDThe span metrics the engine derives from traces (apm.md)service
orbit-selfSRE Orbit / Self-monitoringThe metrics orbit-api, nocturne and orbit-stack servejob

A panel whose metric nobody sends says "No data in this range." rather than drawing anything. The three Kubernetes ones and orbit-self need the telemetry feed the chart and the plain manifests install (install/helm.md → "Telemetry"). On compose nothing scrapes, so only orbit-apm-red fills, from the demo shop.

Where the numbers come from

Every panel query goes through orbit-api's GET /api/v1/query_range with the cluster the Deck has selected, after the browser has replaced the variables, and orbit-api hands the expression to the engine at ORBIT_STACK_URL. That holds on demo data too: a dashboard is always real PromQL on the real engine, and with no ORBIT_STACK_URL every panel is refused. Variables and the query editor's suggestions read the engine's label routes through orbit-api the same way.

Creating and editing

New dashboard on the list, or Save as copy on any dashboard you can open. In edit mode:

  • Add → Visualization adds a panel and opens the panel editor; Add → Row adds a full-width row that groups the panels under it and can open collapsed.
  • The panel editor takes up to 8 PromQL queries, A to H, each with a legend template where {{pod}} prints that label of the series (empty names the series by its labels). Ctrl + Enter runs them, Ctrl + Space suggests metrics, functions, labels, values and variables at the cursor.
  • Data source over the queries is PromQL or Logs: a log panel reads the stored logs instead (see "Log panels" below).
  • Visualization is one of time series, stat, gauge, bar, pie, table, log list and text. The standard options are the unit, the decimals, a minimum and maximum, and up to 10 thresholds coloured OK, warning or critical; a time series can stack its series and show its legend as a list, a table of mean, max and last, or not at all. A text panel is Markdown, and HTML in it is shown as text, as is an image, by its alt text.
  • Panels sit on a 24-column grid: drag one by its title bar, resize it from its lower right corner, or focus it and use the arrow keys (Shift with the arrows resizes, Enter edits). Moving panels needs a wide window; on a narrow one panels still open in the editor.
  • Apply keeps a panel's changes in the dashboard; Save stores the dashboard as a new version; Discard goes back to the last saved version.

Every save carries the version it started from. When someone else saved in between, orbit-api refuses the save with 409 conflict and names who saved which version, and the Deck offers three ways out: Overwrite with yours, Save as copy, or Load theirs and drop your changes. Nothing is ever overwritten silently.

Settings holds the title, description, tags, the default time range (15 minutes to 30 days), the auto refresh (off, 10 s, 30 s, 1 min, 5 min, or the viewer's choice), the variables and the JSON model.

Variables

A variable turns part of every query into a picker at the top of the dashboard.

TypeValues come fromExample
queryThe engine: label_values(metric{selector}, label) or label_values(label)label_values(kube_pod_info{namespace=~"$namespace"}, pod)
customA comma-separated list you typeprod-use1, prod-euc1
intervalA comma-separated list of durations1m, 5m, 1h

Use one in an expression as $name, ${name} or [[name]]. A variable may be multi-value and may include All: several values reach the query as a|b (each value regex-escaped) and All as .*, so match them with =~, for example {namespace=~"$namespace"}. A variable whose query names another variable is resolved again when that one changes.

Two built-ins, the way Grafana spells them: $__interval is the panel's step, and $__rate_interval is the step plus one 15-second scrape, never under 60 s, which is the window a rate() needs to always hold at least four samples. The step itself is chosen for about twenty points per grid column and never goes under 15 s. From 7 days on, the grid ends on a multiple of the step, as Grafana's does: every viewer inside one step asks the engine the same question, and the last point can be up to one step old. Other Grafana built-ins, such as $__range, are not supported.

The page's address carries the selection, var-namespace=shop,payments, and the time range, range=6h (or from-to in epoch seconds), so a copied link opens on what its sender saw.

Log panels

A panel can read the stored logs instead of PromQL: switch Data source over its queries to Logs. Its query is the Logs explorer's language, with the same keys, terms and meaning (logs.md → "The query language"), over the dashboard's time range.

VisualizationDraws
Time seriesThe matching lines over time as stacked bars, or lines, split by a field: one series per top value, the rest summed as Other, the lines without the field as No value
Bar, pie, tableThe split's top values over the whole window, with lines and share each, then Other and No value
Stat, gaugeThe matching lines, or with Share of a sub-query's share of them in percent (errors over every line), with thresholds and a sparkline
Log listThe newest 100 matching lines in the columns chosen; a row opens the line in the Logs explorer

The split is a field: the level, service (the resource's service.name), namespace (k8s.namespace.name), pod, container, node, the message pattern, or any attribute as @name (the line's own, else its resource's). The message pattern is the JSON msg or message when the line is a JSON object, else the line: its first 40 words, every word that holds a digit or a hex id of 16 or more turned into *, so lines that differ only in ids, counts or durations share a pattern. Split by it, a table shows the top error messages. Top is 1 to 50 values, 10 by default; a chart draws the first 8 in colour and folds the rest into Other.

The dashboard's filter

A dashboard with a log panel shows a log filter above its variables: terms in the same language, each a chip that one click removes or turns around. Every log panel's query holds it as well as its own. A click on a value adds its term to the filter, Kibana's "filter for value": a row of a top-values panel, a slice's legend, a series under a count over time. The minus beside it excludes the value ("filter out"), and the same click again takes the term away. Other and No value filter nothing; a message pattern filters on its longest run of fixed words, as a phrase. The filter lives in the address, lq=, beside the time range and the pickers, so a copied link opens on what its sender saw.

Variables over logs

A variable of type logs lists a log field's values: its query is the field (service, namespace, pod, container, node, severity or @name), its options the 50 values with the most lines in the window. Use it as service:$service: under All the term drops out of the query, and one value matches exactly. The log language has no OR, so a logs variable takes one value or All, and a multi-value variable of another type gives a log query its first value. A PromQL panel reads a logs variable as any other ({service=~"$service"}).

What a log panel counts

The counts are of the lines the engine stored. When ingestion control dropped lines that arrived in the window (ingestion.md), the panel says how many, from the engine's counters of what arrived: those of the query's levels when it names levels, else those of its one service when it names exactly one, else every line. The counters hold the last 24 hours and start with the engine's process, so an older window says nothing.

Every read is bounded. A split names at most 50 values and a count over time at most 240 buckets (the panel asks for about one per 20 pixels). A read stops at 3 s for a window of up to an hour, 6 s up to a day and 10 s beyond, or past 4, 8 or 16 GiB of data read; one cut short says Partial and counts what it read, newest data first. A scan thread keeps 1,024 distinct values of the split; past that the panel says so, its top values are among the first it met, and the rest count as Other.

Logs overview

Templates → Logs overview on the list creates a starter dashboard in your language, saved as yours to change: lines, errors, the error share and warnings; errors and warnings over time by service; the level split; log volume by namespace; the top error messages; and the recent errors. Its service and namespace pickers scope every panel.

A demo build draws the log panels from the demo estate's own lines, the ones its Logs page reads, on the demo's clock.

The JSON model

Settings → JSON model shows the whole dashboard as orbit-api stores it, to edit and apply, copy or download; Export JSON on the list downloads the same thing. The shape:

text
{uid, title, description, tags[], time: {from: "now-6h", to: "now"}, refresh: "30s",
 variables: [{name, label, type: "query" | "custom" | "interval" | "logs", query, options[],
              multi, includeAll, current[]}],
 panels: [{id, type: "timeseries" | "stat" | "gauge" | "bar" | "pie" | "table" | "logs"
                 | "text" | "row",
           title, description, gridPos: {x, y, w, h}  (24 columns),
           targets: [{refId, expr, legend}], unit, decimals, min, max,
           thresholds: [{value, color: "ok" | "warn" | "crit"}], stack, legend, text,
           collapsed, logs: {query, by, top, ratio, columns[], style}}]}

orbit-api validates every save and refuses a violation with 400 invalid_request, naming the field (panels[2]: gridPos: x from 0, w from 1, x + w at most 24). An unknown field is refused too, so a misspelt option never vanishes silently.

FieldAccepted
uid1 to 40 letters, digits, - or _, starting with a letter or digit; empty on create mints 12 characters
title1 to 120 characters; description up to 1000
tagsUp to 16, each up to 32 characters
time.fromnow-15m, now-1h, now-6h, now-24h, now-7d or now-30d; time.to is now
refreshEmpty (the viewer's choice), off, 10s, 30s, 1m or 5m
variablesUp to 20; a name is a letter or _ then letters, digits or _, up to 32 characters, not starting with __; up to 500 options
panelsUp to 100, each id unique and 1 to 1000000
gridPosx from 0, w from 1, x + w at most 24; h 1 to 60; y 0 to 10000
targetsUp to 8 per panel; refId one capital letter, unique; expr up to 2000 characters
unitEmpty, or one of Grafana's ids none, short, percent, percentunit, s, ms, bytes, Bps, reqps, ops
decimals, min, maxdecimals 0 to 6; min below max
thresholdsUp to 10, colour ok, warn or crit
legendlist, table or hidden
textMarkdown, up to 16000 characters
logsquery and ratio up to 2000 characters each; by one of service, namespace, pod, container, node, severity, message or @ and an attribute name; top 1 to 50; up to 12 columns of severity, service, namespace, pod, container, node, message, trace_id, span_id or @name; style bars or lines. A logs panel needs it; a text panel or a row refuses it, and a panel with it has no targets
A logs variableIts query is one of service, namespace, pod, container, node, severity or @name, and multi is false

A row is pinned to x 0, w 24, h 1 and carries no queries; collapsed folds the panels under it when the dashboard opens. A variable's current holds $__all when All is picked. Optional panel fields are left out when unset, so two clients saving the same intent store the same bytes.

Importing from Grafana

Import on the list takes a JSON model, pasted or from a file, either this product's or a Grafana dashboard's JSON model. A Grafana model is converted in the browser before anything is sent:

GrafanaBecomes
timeseries, graph panelstimeseries
stat, singlestatstat
gaugegauge
bargauge, barchartbar
piechartpie
table, text, rowThe same; a collapsed row keeps its panels and stays collapsed
Each target's expr and legendFormatA query and its legend, up to 8 per panel
The unit, decimals, minimum and maximumKept; the unit only when it is one of the ids above
Threshold stepsRed becomes critical, orange and yellow warning, anything else OK
query, custom and interval variablesThe same types, with their definition as the query
The time range and refreshKept when they are among the values above

Left out: data sources (every query runs on this engine), transformations, overrides, links, annotations, panel types outside the list, variables of other types, and panels past the 100th. The dialog says how many panels it dropped before you import. A Grafana dashboard always gets a new uid; one of this product's models keeps its own, and when that uid is taken the dialog offers Import as a copy.

The API takes this product's model only: POST /api/v1/dashboards refuses a Grafana model, because its fields are unknown to the schema above. Convert it in the Deck, or write the model yourself.

Permissions

ToNeeds
List and open dashboardsdashboards.read
Draw their panels and resolve their variablestelemetry.query as well
Draw their log panels and list a logs variable's valueslogs.read as well; without it each log panel says so and reads nothing
Create, save, copy, import and deletedashboards.write
Change a built-in dashboardNobody: save a copy

The built-in viewer role reads and draws every dashboard; editor and admin also write. There is no per-dashboard access list: whoever holds dashboards.write can edit or delete any saved dashboard, which the audit trail records with a summary of before and after (dashboard.create, dashboard.update, dashboard.delete; see audit.md).

The API

Every route needs a session; the permissions are the ones in the table above. With an editor's SESSION (identity.md → "Signing in from a shell"), copy the built-in Nodes dashboard under a new title, then delete the copy:

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  localhost:8080/api/v1/dashboards/orbit-nodes \  | python3 -c 'import json,sys; d=json.load(sys.stdin)["dashboard"]; d["uid"]=""; d["title"]="Nodes (team copy)"; print(json.dumps({"dashboard": d}))' > copy.jsoncurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \  --data @copy.json localhost:8080/api/v1/dashboardscurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -X DELETE \  localhost:8080/api/v1/dashboards/NEW_UID

A log panel reads GET /api/v1/logs/aggregate and GET /api/v1/logs/query under logs.read (logs.md → "Over the API").

NEW_UID is dashboard.uid in the answer to the create call. PUT takes {dashboard, version} with the meta.version you read; when the stored version has moved it answers 409 with version, updatedBy and updatedAt of the stored one beside error. A body is at most 1 MiB. The full list of routes and shapes is in api.md.

Where they are stored

One JSON document per saved dashboard, ORBIT_DATA_DIR/dashboards/<uid>.json, holding the model, its version, and who created and last saved it and when. They share the data directory, and therefore the backups and the single-replica ceiling, with users and the audit trail (identity.md → "Where the state lives").

Where to go next

  • The span metrics behind orbit-apm-red, and how to send traces: apm.md.
  • The PromQL the engine answers, function by function: orbit-stack.md.
  • Roles, and how to grant dashboards.write without the rest of editor: identity.md.