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.
| uid | Title | Reads | Variables |
|---|---|---|---|
orbit-k8s-cluster | Kubernetes / Cluster | kube-state-metrics and the kubelet's cAdvisor | none |
orbit-k8s-workloads | Kubernetes / Workloads | kube-state-metrics and cAdvisor, for one namespace | namespace, pod |
orbit-nodes | Nodes | node-exporter | instance |
orbit-apm-red | APM / Service RED | The span metrics the engine derives from traces (apm.md) | service |
orbit-self | SRE Orbit / Self-monitoring | The metrics orbit-api, nocturne and orbit-stack serve | job |
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,
AtoH, each with a legend template where{{pod}}prints that label of the series (empty names the series by its labels).Ctrl + Enterruns them,Ctrl + Spacesuggests 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.
| Type | Values come from | Example |
|---|---|---|
query | The engine: label_values(metric{selector}, label) or label_values(label) | label_values(kube_pod_info{namespace=~"$namespace"}, pod) |
custom | A comma-separated list you type | prod-use1, prod-euc1 |
interval | A comma-separated list of durations | 1m, 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.
| Visualization | Draws |
|---|---|
| Time series | The 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, table | The split's top values over the whole window, with lines and share each, then Other and No value |
| Stat, gauge | The 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 list | The 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:
{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.
| Field | Accepted |
|---|---|
uid | 1 to 40 letters, digits, - or _, starting with a letter or digit; empty on create mints 12 characters |
title | 1 to 120 characters; description up to 1000 |
tags | Up to 16, each up to 32 characters |
time.from | now-15m, now-1h, now-6h, now-24h, now-7d or now-30d; time.to is now |
refresh | Empty (the viewer's choice), off, 10s, 30s, 1m or 5m |
variables | Up to 20; a name is a letter or _ then letters, digits or _, up to 32 characters, not starting with __; up to 500 options |
panels | Up to 100, each id unique and 1 to 1000000 |
gridPos | x from 0, w from 1, x + w at most 24; h 1 to 60; y 0 to 10000 |
targets | Up to 8 per panel; refId one capital letter, unique; expr up to 2000 characters |
unit | Empty, or one of Grafana's ids none, short, percent, percentunit, s, ms, bytes, Bps, reqps, ops |
decimals, min, max | decimals 0 to 6; min below max |
thresholds | Up to 10, colour ok, warn or crit |
legend | list, table or hidden |
text | Markdown, up to 16000 characters |
logs | query 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 variable | Its 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:
| Grafana | Becomes |
|---|---|
timeseries, graph panels | timeseries |
stat, singlestat | stat |
gauge | gauge |
bargauge, barchart | bar |
piechart | pie |
table, text, row | The same; a collapsed row keeps its panels and stays collapsed |
Each target's expr and legendFormat | A query and its legend, up to 8 per panel |
| The unit, decimals, minimum and maximum | Kept; the unit only when it is one of the ids above |
| Threshold steps | Red becomes critical, orange and yellow warning, anything else OK |
query, custom and interval variables | The same types, with their definition as the query |
| The time range and refresh | Kept 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
| To | Needs |
|---|---|
| List and open dashboards | dashboards.read |
| Draw their panels and resolve their variables | telemetry.query as well |
Draw their log panels and list a logs variable's values | logs.read as well; without it each log panel says so and reads nothing |
| Create, save, copy, import and delete | dashboards.write |
| Change a built-in dashboard | Nobody: 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:
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_UIDA 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.writewithout the rest ofeditor:identity.md.