Overview
Vigie knows requests, tasks, traces and errors. It does not know your app's words: that parcelo.ship creates a shipment, that an order goes from payment to parcel, or that INVOXA_INVALID_COUNTRY means a customer's country is wrong. You teach it in definitions/.
definitions/
├─ renderers/ how an event reads
├─ processes/ flows across several tasks
├─ pages/ screens of your own
├─ dashboards/
├─ alerts/
├─ monitors/ URLs checked every minute
├─ tools/ more MCP tools
├─ redactors/ secrets in your paths
├─ catalog/ providers, task kinds, SLOs, rules
└─ status.ts the public status page
The folder names are only a convention. Vigie loads every .ts file and looks at what each one exports.
Where it lives
Keep definitions/ in your app's repository, so it is reviewed with the code it describes. Point Vigie at it:
- On your machine, run
bunx vigiefrom the folder that holdsdefinitions/. - On a server, set
VIGIE_DEFINITIONSto the folder.
Files import from vigie/sdk, which resolves from anywhere: no install, no path alias.
Typed all the way
import { defineStatusPage } from 'vigie/sdk'
import { api, shop } from './monitors/acme.ts'
export const status = defineStatusPage({
title: 'Acme status',
components: [
{ name: 'API', from: api },
{ name: 'Shop', from: shop },
],
days: 90,
})
from takes the monitor itself, not a string, so a renamed or deleted monitor fails to compile. days: 45 fails too: only 30, 60 and 90 exist.
Reloading and errors
Locally, a saved file applies within a second. A file that fails to load shows its error on Settings, Extensions, and everything else keeps working. Check them all before you deploy:
bunx vigie check
Everything you can define
| Define | With | What you get |
|---|---|---|
| How an event reads | defineLogRenderer | Sections in the event panel, phrases in log rows, text for agents |
| Why and how to fix an error | defineErrorRenderer | The why and fix when the app does not say itself |
| A business process | defineProcess | Instances, funnel, what is stuck and why |
| A page | definePage | A screen in the nav, plus an MCP tool that reads it |
| A dashboard | defineDashboard | Widgets from SQL |
| An alert | defineAlert | Evaluated every 30 s, sent to your channels |
| An uptime check | defineMonitor | A URL checked every minute |
| The status page | defineStatusPage | What /status shows |
| An agent tool | defineTool | One more MCP tool |
| Secrets in your paths | defineRedactor | Masked at ingest |
| Providers, task kinds, SLOs, rules | defineCatalog | Names, clocks, objectives and production rules |
| Views, channels, enrichers, health rules, people | More |