On this page
Monitoring
A watch is one question /monitor asks on every run, such as which systems are failing or where the cloud bill moved. The code plugin matches each answer to a node on the repo's board and pushes it as an insight. Each watch also produces one stat: a number, a short list or a status for every node it reaches, which you can pin to the canvas. The people reading the board then see what production says about it.
Before you start
- The repo is analysed and synced: run
/analyze, then/sync. - Each source is connected in your coding agent, or reachable from your terminal. Connect a source lists what each one needs.
Set up
Run /monitor setup in the repo. It lists the watches below, you pick the ones you want, and it writes them to .provenmap/monitoring/config.json. Then it prints how to connect each source you picked.
Run /monitor setup again to add a watch later. The watches already in the file stay.
Stats on nodes
A watch produces exactly one stat, even when it reads more than one source. A node can carry several stats, one from each watch that reaches it, so a server node can show its errors, its cost and its traffic side by side.
A stat is one of three types:
A value says how its number is written: a count, money in the bill's currency, a percentage, a duration, bytes, or a number with a unit of your own such as req/s. A bar or a ring needs a full scale, so it takes a percentage or a maximum.
/monitor setup writes each watch's stat into .provenmap/monitoring/config.json, beside the watch. The three watches above come with theirs and ask nothing. Edit the stat block in that file to change one.
Each run pushes a watch's stat as one insight, named after it (Errors by node). On ProvenMap, pin that insight to keep its numbers on the canvas.
Watch something else
Describe the watch after setup, in a sentence:
Or pick Something else in /monitor setup. You can describe the watch, or pick from the watches /monitor suggests for your repo. Pick several, and it sets them up one at a time.
For each watch, /monitor finds a source that can answer it, pulls a few rows, and shows you a dry run. The dry run lists the signals it would make, how many matched a node, the matches it is unsure of, and the stat it proposes. Nothing is pushed. When you confirm the watch, you also choose its stat's type and, for a value, whether it is drawn as a number, a bar or a ring.
A watch needs a source that gives each problem its own id, such as an issue number or an alarm name. Without one, every run would file the same problem as a new insight, so /monitor declines to save the watch and says why.
Connect a source
/monitor reads a source through a connector in your coding agent, through the gh or aws command, or from a file you export. It never asks you to paste a token into the chat.
Sentry can also be connected on ProvenMap itself. A Sentry project bound to an app board files insights on the app's node every hour, with no repo involved; see Automations. Use /monitor when you want each error on the node whose code threw it.
AWS bills each Cost Explorer request. A run makes a fixed handful of them, not one per service.
Run it
Run /monitor. It pulls every watch, matches the signals to nodes, and pushes the insights in one batch.
A signal finds its node by the file path in a stack frame, a resource or service name, a route, or a tag. When a match is uncertain, /monitor asks you once and remembers the answer in .provenmap/monitoring/map.json. A signal that matches nothing becomes an insight on the board itself, tagged unmatched.
Each run brings the board up to date with what the sources say now. A problem the run still finds keeps its insight, with the new numbers, so a work item promoted from it stays linked. A problem the run no longer finds loses its insight, unless an architect moved it past draft. That is why a run pulls every watch. If one source can't be reached, the run stops before pushing and names the watch. A partial run would remove the other watches' insights with nothing to replace them.
On the board, an architect promotes an insight to a work item, and a developer picks it up with /work-items.
Schedule it
One sentence covers every watch. Add it to the repo's scheduled run:
In a repo with no scheduled task yet, /start prints the whole task to create, with /monitor in it. A scheduled run asks nothing. It leaves uncertain matches in its report, and proposes draft work items from the insights that carry a fix and a high priority. An architect reviews those drafts before anyone can pick them up.
FAQ
Can I run one watch on its own?
No. A run replaces the last run's unreviewed insights, so it has to carry every watch. To look at one area, add a focus after the command, such as /monitor checkout errors only, and expect the board to show only that until the next full run.
Why did the cloud cost watch ask so many questions on its first run?
Cost lines name services and resources, not files, so the first run has to ask which node each one belongs to. Every answer is saved, and later runs don't ask again.
Why are some cost insights on the board and not on a node?
A cloud bill covers the whole account, and a board covers one repo. A cost that belongs to another repo's resources matches no node here, so it lands on the board itself, tagged unmatched. When /monitor asks about it, choose to ignore it and later runs leave it out. A cost allocation tag that names this repo's resources keeps the watch to them.
What happens to an issue or an error once it is fixed?
The next run that finds any signal no longer reports it, so its insight is removed. A run that finds nothing in the window pushes nothing, and the last run's insights stay until a later run replaces them. An insight an architect moved past draft stays on the board.
What's next
Last updated November 15, 2026



