User guide

Everything you can do on the diagram list and in the editor.

The diagram list

The start page lists every diagram with its owner and dates. Click anywhere on a row to open it. The row actions duplicate, download (JSON) or delete a diagram; select several rows to download or delete them together.

• New diagram opens an empty canvas in edit mode.
• Upload imports one or more .json files in a single write. They are validated against the schema; if a diagram with the same id exists, the upload gets a new id. The list refreshes as soon as the lookup serves the new rows.
• ⓘ About shows the version, the author and links to the source code and these docs.
• ⚙ Storage administration lists the app's lookup files and can delete one.

The editor toolbar

Adding components

In edit mode, the palette on the left lists every kind of component. Custom component is pinned on top. Below it, type in Filter components to narrow the list by name, category or Smartscape type — for example lambda, kubernetes or K8S_POD. Drag a component onto the canvas, or click it to drop it in the middle; its editor opens docked on the right.

Entity components represent one or more real entities. There are 49 of them, grouped by category. Endpoint components list the endpoints of your services (they aren't Smartscape nodes, so they come from the endpoint.name dimension of the request metric) and show the problems of their service; Synthetic components are browser, HTTP and network availability monitors.

On the Data tab:

1. pick the component type — type in the list to filter it; changing it clears the selection;
2. open the entities combo box, type to search and pick one or more entities. It lists the entities of that type seen in the last 7 days, sorted by name (web frontends for frontend, mobile frontends for mobile). Types that cover several Smartscape types show which one each entity is. When an environment has more than 2,000 entities of a type, the list shows the first 2,000 and what you type is searched across all of them.

The component then reflects the Davis problems that affect any of the picked entities and were open at any time during the timeframe — a snapshot of that moment: with Last 5 minutes you see what is open now, and with a past day you see what was open that day, even if it closed later. Frontends and synthetic monitors also match their classic id (APPLICATION-…, SYNTHETIC_TEST-…), so problems raised on either id count.

Next to the status icon, the component says how many: 0 problems, 1 problem, 3 problems. Click the count to list those problems — each opens in the Problems app, marked as still active or closed — or to open the component's details with all of them.

Components created from a query — the sample diagram, an imported file or the agent skill — keep working: the panel shows the query, and picking entities replaces it with a fixed selection.

On the Status tab you set when the component changes color:

• Warning threshold — number of problems open in the timeframe to turn orange.
• Failing threshold — number of problems open in the timeframe to turn red (red wins when both are equal).
• Match — an optional DQL fragment appended as | filter … to the problem query, e.g. event.category == "ERROR".

Custom components (containers)

A custom component is a resizable container with one row per child. A child is either an entity returned by your own DQL query or an SLO you pick. Every row has its own status light, and the container's color sums them up.

How the container color is computed

A container with a single entity shows that entity as one large block in the container's color instead of a list.

Entities mode

Write a DQL query that returns one row per child. Use it to group entities that belong together — the databases of a domain, the services of a team, the hosts of a cluster.

smartscapeNodes "DB_INSTANCE_*"
| filter contains(name, "orders", caseSensitive: false)
| fields id, name
| limit 20

SLOs mode

Pick one or more SLOs. Each row shows the SLO's current value and error budget and is green when the SLO meets its target, orange when it is below its warning and red when it is below its target. Each SLO is evaluated with the timeframe defined in the SLO itself, not the page timeframe.

Visual options

KPI blocks

Any node can show a list of KPIs under it. On the KPIs tab, turn on Show KPIs under the node, give the block a title and add as many KPIs as you need with Add KPI.

Ready-made KPIs

Entity components come with ready-made KPIs for their type, built for the entities you pick on the Data tab: each KPI shows one line per picked entity — pick three services and Request count lists three services. New components start with the type's main KPIs (in bold below); Add KPI offers the rest, plus Custom KPI for your own query. KPIs added this way are marked Ready-made; editing the query turns one into a custom KPI.

When you pick several entities, each KPI shows its title above its lines — Request count, then one line per service, then Response time… — so you always know what you are reading; with a single entity, the line itself carries the title. Ready-made KPIs bring their title; for your own KPIs named from a column, type one in Name.

Their queries use placeholders that the app fills with the component's selection right before running them, so they follow the selection when you change it. The query editor paints them in blue and validates them as regular values. You can use them in your own KPIs too (entity components only):

timeseries requests = sum(dt.service.request.count, scalar: true), by: {dt.smartscape.service},
  filter: { in(toString(dt.smartscape.service), array($entityIds)) }
| fieldsAdd name = getNodeName(dt.smartscape.service), value = requests
| fields name, value
| sort value desc

Run in the editor fills the placeholders too, and the details panel shows each KPI's query as it ran.

KPI settings

Each KPI has its own query and its own settings:

A single value with a custom name:

timeseries rt = avg(dt.service.request.response_time, scalar: true)
| fieldsAdd avg_ms = rt / 1000
| fields avg_ms

One line per service, named from the service column:

timeseries rt = avg(dt.service.request.response_time, scalar: true), by: {dt.smartscape.service}
| fieldsAdd service = getNodeName(dt.smartscape.service), avg_ms = rt / 1000
| fields service, avg_ms
| sort avg_ms desc
| limit 5

Connections

Drag from the dots on the side of a node to another node. The connection editor opens so you can choose:

• Normal — a plain line with an optional label.
• KPI relation — a query that returns a single value (first row; the chosen column or the first numeric one), a unit (common units or a custom one), decimals and a threshold. above means high values are bad, below means low values are bad.

A new KPI relation starts with the request count of the page timeframe, without limits — set them on the Threshold tab:

timeseries requests = sum(dt.service.request.count, scalar: true)
| fields requests

For the average response time in milliseconds:

timeseries r = avg(dt.service.request.response_time, scalar: true)
| fieldsAdd v = r / 1000
| fields v

Every connection has a direction — source to target, target to source, or no arrow. KPI connections show a pill with the value, color the line by status and animate dots in the arrow's direction (off when the system asks for reduced motion).

Changing where a connection starts or ends

• On the canvas: select the connection; its two ends show a small circle. Drag an end onto another dot — on the same component or on a different one. The connection keeps its type, query and label.
• In the editor: on the Visual tab, Connection points sets the side (top, right, bottom or left) where it starts and where it ends.

Editing like a dashboard

• Select a node to get the floating toolbar: its size, Duplicate, Edit and a ⋮ menu with View details and Delete. Selected connections get Edit and Delete.
• Resize any node from the grips in its bottom corners.
• Edit in the panel docked to the right. There is no Apply button: names, icons and labels change on the canvas as you type, Run applies a query, and threshold, filter and selection changes refresh the status after a short pause.
• The element you are editing is highlighted on the canvas with a blue outline and an Editing badge, and becomes the selection.
• While the editor is open, click another element to switch to it.
• Each editing session is one undo step.

View mode and details

In view mode, click a node or a KPI connection to open its details on the right:

• the applied timeframe, in your time zone;
• the picked entities (name, id and classic id) or the entity query, and the full problem query with the timeframe and ids already filled in — copy it or open it in Notebooks;
• each KPI with its query and its current lines;
• the problems in the timeframe, each linking to the Problems app;
• the breakdown per child or per SLO, and for KPI connections the raw value and how the threshold was evaluated.

Saving, sharing and versions

The timeframe and the auto-refresh are part of the diagram: whoever opens it starts with the ones it was saved with. Changing either one shows Unsaved changes — in edit or view mode — and Save keeps it. Save a relative window such as Last 5 minutes for a live wall screen, or a fixed date range to always show the same incident or demo window.

Save writes the diagram to the lookup table. If someone else saved it after you opened it, the app asks whether to Overwrite their version or Reload theirs. Export JSON downloads a file you can upload again without losing anything — use it to move diagrams between environments or to keep them in Git.

Keyboard shortcuts