Definitions
Pages
definePage adds a screen of your own to the nav, built from SQL blocks, and an MCP tool that reads it.
definitions/pages/invoxa.ts
import { definePage, eventList, funnel, row, series, stateLine, table, ui } from 'vigie/sdk'
const sync = `FROM logs WHERE $__timeFilter(Timestamp) AND Environment = $__env AND TaskKind LIKE 'invoxa.%'`
export default definePage({
id: 'invoxa',
title: 'Invoxa',
nav: { group: 'Processes', order: 30 },
process: 'billing-sync',
layout: [
stateLine({
sql: `SELECT countIf(Outcome != 'succeeded') AS failed, count() AS total ${sync}`,
text: (r) => (r.failed / Math.max(r.total, 1) > 0.05 ? ui.text('Invoxa sync is failing', { tone: 'error' }) : ui.text('Invoxa sync is healthy.')),
}),
funnel({
title: 'Invoxa sync, from start to finish',
steps: [
{ label: 'Customers sent', sql: `SELECT uniqExactIf(TaskId, TaskKind = 'invoxa.customer.sync') AS n ${sync}` },
{ label: 'Invoices sent', sql: `SELECT uniqExactIf(TaskId, TaskKind = 'invoxa.invoices.sync' AND Outcome = 'succeeded') AS n ${sync}` },
],
}),
row(
table({ title: 'Why it fails', span: 6, sql: `SELECT LogAttributes['taskOutcome.reason'] AS code, count() AS attempts ${sync} AND Outcome != 'succeeded' GROUP BY code ORDER BY attempts DESC LIMIT 10` }),
series({ title: 'Attempts', span: 6, kind: 'bars', sql: `SELECT $__bucket(Timestamp) AS t, countIf(Outcome = 'succeeded') AS ok, countIf(Outcome != 'succeeded') AS error ${sync} GROUP BY t ORDER BY t` }),
),
eventList({ title: 'Failed attempts', where: { 'task.integration': 'invoxa', outcome: 'failed' }, limit: 12 }),
],
})
Blocks
| Block | Shows |
|---|---|
stateLine({ sql, text }) | One sentence from the first row of a query. |
stat({ title, sql, unit?, format?, tone? }) | One number. |
series({ title, sql, kind?: 'bars' | 'lines' }) | A time series: the first column is the bucket, the others are series. |
table({ title, sql, link? }) | Rows of a query. |
funnel({ title, steps }) | Each step is a query returning n. bad: true colours it as a loss. |
eventList({ title, where, limit? }) | The latest wide events matching fields. |
row(...blocks) | Side by side. span is out of 12. |
SQL macros
| Macro | Becomes |
|---|---|
$__timeFilter(col) | The time range picked on screen. |
$__from, $__to | Its bounds, in seconds. |
$__env | The environment picked on screen. |
$__bucket(col) | A time bucket sized to the range. |
Queries run read-only against ClickHouse. The tables are logs (wide events, with LogAttributes holding every field), spans, metrics_gauge, metrics_sum, metrics_histogram, and per-minute rollups req_1m and task_1m.
access limits a page to a role: viewer, operator, admin or owner. Every page is also an MCP tool, so an agent can read the same screen.