Docs · Concepts

Investigations

A runbook filed against a Check — the steps somebody would take at 07:00, written down once.

A Check tells you that Store 014 is short by 312. An investigation is what somebody does next, written down so they do not have to remember it.

It is the investigation that starts where a reconciliation stops: a runbook filed against a Check, with steps that query the systems, ask questions of the answers, and end on a conclusion.

#Six kinds of step

Each step is named for the question this step asks, not for the table it reads. What the tills closed with is a step name. SELECT FROM POS_CLOSE is not.

#How a step knows which row it is about

Three mechanisms, and you will use all of them.

Row tokens. Once a row is chosen, its values are available as tokens — one per key, and one per carried column. Paste one into any field of the query a step runs: a WHERE clause, a URL, a header, a bind value. Mosaic puts the row's value there before the query goes out, quoted and typed for the engine.

Until a row is chosen, every step runs unfiltered.

Fill this query's own names. To use a query written for another system without rewriting it: name what the query already asks for on the left, and the row value that fills it on the right. There is an Automap button, and it only takes exact matches once case and punctuation are ignored — a near miss would bind the wrong column, which is worse than not binding it.

Only when. A step can be guarded so it runs on one side of an earlier question. Left on Always, it runs every time.

#Saying what a good answer looks like

A step can declare what a pass looks like: how many rows, or a value, read as text, a number, a date or yes/no — then one of two dozen operators, worded the way a person would say them: is there, is not there, is empty, contains, is greater than, is on or after, and so on.

And then the sentence that turns a result into a conclusion, under What the answer means:

"No rows here means it never reached the staging table."

That is the line that makes it a runbook rather than a saved query.

#Conclusions

A conclusion step ends the investigation with one of three outcomes:

• Answered — this is the cause
• Ruled out — look elsewhere
• Inconclusive — cannot tell from here

plus What to take away.

#Running one

Press Investigate. Steps run in order, guards decide which ones apply, and you end on a conclusion or run out of steps.

A step can run a whole Check — any Check in this workspace, including this one. It runs with the row's values available as tokens, and its own investigations are not run, so there is no recursion to worry about. A sub-check's answer opens as its own tab, capped, and says so: "A step brings back at most 200 rows. Every disagreement is among them, so the rows left out all agreed."

Executions are recorded — when they started, how many steps passed and failed, and how long they took. A single step run on its own is not recorded: its answer lives only as long as the tab showing it.

#Running automatically

An investigation can be set to Run on every disagreeing row. It then runs as part of the Check, for the rows that disagree, and writes what it ended on into a column at the end of the table.

Read the cost before turning it on: every disagreeing row costs one pass of this runbook against the systems its steps name, and it also happens on a schedule. There is a cap — 50 rows per run by default — and a Check can set its own limits on rows and seconds.

Real disagreements are investigated first, then rows a system could not be read for.

#Letting published readers investigate

Two independent switches, and it is worth being clear about the second.

Publishing a Check lets its figures be read. Readers may investigate is a different thing, and it is off until you say otherwise:

Anybody with the link can run these investigations against the systems their steps name, and read the figures of any check a step runs — including checks that are not themselves published.

That is why it is an admin's decision. It lets a reader with no account cause queries to run against a production system.