Metrics
A metric is one number about your protocol, kept over time and shown as a chart: a treasury’s balance, a vault’s share price, swap fees per hour.
Two kinds of metric
Every metric is either a state metric or an activity metric. The Metrics page marks each one.
| Kind | What it measures | Example | Chart |
|---|---|---|---|
| State | How something stands at a moment | Treasury ETH balance, stETH total supply, a vault’s share price | A line |
| Activity | What happened over a window | Swaps per hour, fees earned per day, deposits per day | Bars per period |
A state metric answers “what is it now?”. An activity metric answers “how much happened?”.
State metrics
A state metric is a point-in-time reading: a balance, a supply, a rate, a price or a function’s result. It is read every minute, and its chart shows the value at each point in time. It can be:
- A function result — What a view function returns, such as
totalAssets()orutilisation(). - A token balance — The ERC-20 balance a contract or wallet holds.
- A native balance — ETH, or the chain’s own coin.
- A formula — Several reads at the same block and an expression over them, such as
pooled / shares. - A group total — The same read on every member of a group, added up, such as available liquidity across every market. Each member can also be kept as its own line.
- A table total — A state table’s column added up across its active rows, or its active rows counted.
When a state metric is created, contract.dev reads back its earlier values where history is available. The metric’s page shows how far back it reaches.
Activity metrics
An activity metric is built from events. Each window’s figure is the count, sum, average, lowest or highest of the events in it.
- Counts — Swaps per hour, loans opened per day.
- Sums — Fees in USD, volume in tokens. Dollar values are priced on the day each event happened, where a price for the token is available.
- Splits — The same figure broken down by contract or by an event field, such as by pool, each split its own series.
- Conditions — Only the events you want, such as swaps over $10,000.
An activity metric reads its history first, then stays current as new events arrive.
Activity metrics count events, not distinct values: unique active wallets are a report line, not a metric. Each watched contract’s page shows its transactions, events, transfers and wallets without any setup.
Metrics from tables
| Figure | Metric |
|---|---|
| Total outstanding debt across open loans | State: the Loans table’s Owed column, added up |
| Number of currently open loans | State: the Loans table’s active rows, counted |
| Loans opened per day | Activity: LoanOpened events, counted |
| Big swaps per day | Activity: the Big swaps table’s rows, counted per day |
See Tables.
The Metrics page
The Metrics page lists every metric in your workspace with its kind and type, what it is on, its chain, its current value, its change over the last 24 hours and its 24-hour trend.
In place of the change, a metric can show:
| Status | Meaning |
|---|---|
| Indexing… | Its history is still being read. |
| Paused | It is not being read. |
| Stale | Its events have stopped arriving when they usually would. Shows the time of its last record. |
| Failed | Its definition no longer works, such as one over a deleted table. Shows the reason. |
Select a metric to open its page.
- A state metric shows its value over time as a line, over 24 hours, 7 days, 30 days or 90 days, with pan and zoom. Its readings list each change in value, with its block and time.
- An activity metric shows bars per hour or per day, its splits, and the events behind each figure, each linked to its transaction on the chain’s explorer.
Periods not yet read are shown as missing, never as 0.
A metric made for one report or alert stays off the Metrics page and is deleted with it.
Use metrics elsewhere
- Condition alerts — Alert when a metric crosses a line, falls against a day ago or runs above its usual level. See Condition alerts.
- Activity alerts — Send a message each time a metric changes. See Activity alerts.
- Reports — Include any metric in a scheduled report. See Reports.
- Questions — Ask your agent about a metric’s value, its trend or what changed.
Create a metric
Metrics are created and changed by your coding agent or the CLI, with metric define. The app shows them, and deletes them.
A state metric names what it is on and what to read:
contract-dev metric define "stETH supply" --on steth --call "totalSupply()"A formula over several reads:
contract-dev metric define "stETH per share" --on steth \
--call "pooled=getTotalPooledEther() decimals 18" --call "shares=getTotalShares() decimals 18" \
--value "pooled / shares"An activity metric names the event and what to add up:
contract-dev metric define "Swap fees" --on tag:pools --each Swap \
--read "fee=fee()" --read "t0=token0()" \
--value "usd(abs(amount0) * fee / 1000000, t0)" --split contractA table total:
contract-dev metric define "Outstanding" --on table:"Withdrawal requests" --column OutstandingSee the CLI reference for every flag.
Inspect a metric from the terminal
contract-dev metrics
contract-dev metric show "Swap fees" --days 7
contract-dev metric show "stETH supply" --range 30dAsk your agent
Describe the figure you want. Your agent finds the contracts and data, defines the metric and links to it in the app. See Agent Integration.
Track our vault's totalAssets() and show its history.Create a metric for swap fees earned in USD, broken down by pool.The metric appears on the Metrics page in the contract.dev app.