Vigie
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

BlockShows
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

MacroBecomes
$__timeFilter(col)The time range picked on screen.
$__from, $__toIts bounds, in seconds.
$__envThe 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.

Copyright © 2026