Skip to Content
CLIMetrics

Metrics

Define, list, inspect and manage metrics. A metric is a state metric (how things stand: a balance, a supply, a view’s result, a table’s column added up) or an activity metric (what happened over a window: swaps, fees, deposits). One command defines either. See Metrics.

Requires contract-dev login. metric and metrics are the same command. A metric is named by its id or, when one has it, its name.

metrics

Every metric, of both kinds: kind, name, what it is on, what it reads, unit, id. (paused) and (hidden) mark a paused state metric and one made for a report or alert.

contract-dev metrics [--kind state|activity] [--hidden] [--on <what>]
FlagDescription
--kindstate or activity alone.
--hiddenInclude the metrics made for one report or alert, kept off the Metrics page.
--on <what>Only the metrics on a contract, wallet, tag:<group> or table:"<table>".
KIND NAME ON READS UNIT ID state stETH supply steth totalSupply() cmh1metr0001supply00000aa state Treasury USDC tag:treasury balanceOf(self) on 0xa0b8…eb48 cmh1metr0002treas000000bb activity Swap fees tag:pools Swap usd cmh1cust0001fees0000000dd

metric define "<name>"

Define a metric. --on says what it is on; --call makes a state metric, --each an activity metric, and --on table:"<table>" takes the table’s rows.

contract-dev metric define "<name>" --on <what> [--chain <id|name>] --call "<read>"… [--value "<expr>"] [--decimals <n>] [--token <t>] [--show usd] [--split contract] contract-dev metric define "<name>" --on <what> [--chain <id|name>] --each <Event>… [--value "<expr>"] [--where "<rule>"] [--read "<name>=<call>"]… [--field "<name>=<expr>"]… [--aggregate sum|count|avg|min|max|latest] [--split contract|<field>] [--unit usd|count|number] [--keep <param>…] [--pair "<Event> [on <field>]"]… [--history <days>] [--line "<what one line is>"] contract-dev metric define "<name>" --on table:"<table>" [--column "<label>"] [--among active|done|all] [--aggregate …] [--value "<expr>"] [--where "<rule>"]

--on is one of:

--onWhat the metric is on
A name or 0x… addressA contract or wallet.
tag:<group>Every member of a group, added up.
table:"<table>"A table’s rows.
workspaceEvery watched contract.

Every define also takes --description "<sentence>" (shown at the top of its page), --hidden (kept off the Metrics page, for one report or alert) and --preview (read it once now and save nothing).

State metrics

How things stand, read every minute from then on. Any address works, watched or not. When a state metric is created, its past is read as well, where available.

FlagDescription
--call "<read>"A read. Repeat for several, each named, and give --value.
--value "<expr>"With several reads: the expression over their names, worked out exactly.
--decimals <n>Display scale for a single read, 0 to 36. Several reads each take decimals <n> inside the read.
--token <t>The value is an amount of this token. Its decimals scale it.
--show usdWith --token: in dollars at the current price.
--split contractOn a group: keep each member’s line as well as the total.

A read is one of:

ReadExample
A view, on what the metric is ontotalSupply()
A token balance; self is what the metric is onbalanceOf(self) on 0xA0b8…eB48
The chain’s own coinbalance(self)
A named read, scaledpooled=getTotalPooledEther() decimals 18
A storage wordcap=slot(self, 7)

On a group, each member is read and the readings add up.

contract-dev metric define "stETH supply" --on steth --call "totalSupply()" contract-dev metric define "Treasury ETH" --on treasury --call "balance(self)" contract-dev metric define "Treasury USDC" --on tag:treasury --call "balanceOf(self) on 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" contract-dev metric define "stETH per share" --on steth --call "pooled=getTotalPooledEther() decimals 18" \ --call "shares=getTotalShares() decimals 18" --value "pooled / shares" contract-dev metric define "Available liquidity" --on tag:markets --call "availableLiquidity()" --split contract
Defined stETH supply — a state metric on steth (cmh1metr0001supply00000aa).

Activity metrics

What happened, added up from events per window. The address is watched if it is not already, and the command says so. Its history is read back, then kept up to date.

FlagDescription
--each <Event>An event counted, by name or signature. Repeat for several.
--value "<expr>"What each event adds. Leave out to count events.
--where "<rule>"Keep only events where this holds: amount0 > 0.
--read "<name>=<call>"A view read as of the start of the event’s transaction: on the emitting contract unless on names another (a parameter, an earlier read, or 0x…); with passes arguments.
--field "<name>=<expr>"A value worked out per event, in order.
--aggregatesum, count, avg, min, max or latest.
--splitcontract (one line per emitting contract) or a parameter, read or field name.
--line "<…>"What one line of the split is, as a reader would say it. Required when --split is a parameter, read or field.
--unitusd, count or number.
--keep <param>…Event parameters kept on every record beyond the ones the expressions read, so query metric can show, filter or group by them.
--pair "<Event> [on <field>]"Another event of the same transaction, its fields read as Event.field.
--history <days>How many days of history to read back.

Expressions use the event’s parameters by name (a struct’s member as swapInfo.fromAmount), the reads, earlier fields, emitter(), sender(), time(), block(), tx(), amount(raw, token), usd(raw, token) at the event’s day’s price (native ETH is token 0x0000000000000000000000000000000000000000, written out in full), price(token), if(), min(), max(), abs() and round(). Dollars come only through a stated token.

--aggregate latest reads a level off the events: each split’s newest value is carried forward until its next event and the splits add up, so the figure is the value now, never a sum over the period. Use it when the event carries a balance or a total.

contract-dev metric define "Loans opened" --on tag:markets --each LoanOpened contract-dev metric define "Swap fees" --on tag:pools --each Swap --read "fee=fee()" --read "t0=token0()" \ --value "usd(abs(amount0) * fee / 1000000, t0)" --unit usd --split contract

On a table

TableMetric
A state table, with --columnThe column added up across its rows: --among active (default), done or all.
A state table, without --columnIts rows counted.
An activity tableIts rows counted, or summed with --value, under the table’s own --where.
contract-dev metric define "Outstanding" --on table:"Withdrawal requests" --column Outstanding contract-dev metric define "Open loans" --on table:"Loans" contract-dev metric define "Big swaps a day" --on table:"Big swaps" --aggregate count

Inline

The same words, as clauses, define a metric inside a report row or an alert. A metric made this way stays off the Metrics page and is deleted with what owns it.

--row "metric:LP value=on table:Positions; column Value" --on "metric:Supply=on steth; call totalSupply()"

metric show <id|name>

A state metric on one contract or wallet: its readings. An activity metric, a group total or a table total: its total, largest contracts, series and the records behind it.

contract-dev metric show <id|name> [--range 24h|7d|30d|90d|all] [--limit <n>] contract-dev metric show <id|name> [--days <n>] [--by hour|day] [--split <contract|key>] [--records <n>] [--newest]
FlagDescription
--range24h, 7d, 30d, 90d or all. Default 30d on one contract or wallet, 7d otherwise.
--limit <n>On one contract or wallet: how many readings to print, newest last. Default 50. Otherwise as --records.
--days <n>The window, in days, in place of --range. Default 7. Not on one contract or wallet.
--byhour or day. Not on one contract or wallet.
--split <contract|key>One split only, a contract by name or address, or a split key. Not on one contract or wallet.
--records <n>How many records to list, up to 50. Not on one contract or wallet.
--newestList the newest records first. Not on one contract or wallet.
contract-dev metric show "stETH supply" --range 7d --limit 3 contract-dev metric show "Swap fees" --days 7 --by day

metric update <name>

Rename an activity metric with --name "<new>", describe it with --description, or replace parts of its definition with any define flag. Its history is read again.

contract-dev metric update "Swap fees" --where "amount0 > 0"

metric export <id|name>

The history of a state metric on one contract or wallet, one row per reading: at, value, block, tx. An activity metric, a group total or a table total has no readings to export: metric show <name> --json prints its series.

contract-dev metric export <id|name> [--range 24h|7d|30d|90d|all] [--format csv|json]
FlagDescription
--range24h, 7d, 30d, 90d or all (default).
--formatcsv (default) or json.
contract-dev metric export "stETH supply" --range 90d > steth-supply.csv

Manage a metric

contract-dev metric rename <id|name> "<new name>" contract-dev metric pause <id|name> # stop reading it, keep history contract-dev metric resume <id|name> contract-dev metric decimals <id|name> <n|clear> # its display scale contract-dev metric delete <id|name>

decimals sets the display scale and re-interprets the stored history. Alerts on the metric compare against the new scale; their thresholds were typed against the old one. decimals clear returns a supply, an ERC-20 balance or a share price to its token’s decimals; any other value shows as the chain holds it.

pause, resume and decimals are for a state metric on one contract or wallet. An activity metric, a group total or a table total has no pause or display scale: change it with metric update, or delete it.

metric monitor <metric>

An alert on an activity metric, a group total or a table total, one formula. On a state metric of one contract or wallet, use notify add alert --on metric:"<name>". To send a message for each record an activity metric keeps, use notify add alert --metric "<name>".

contract-dev metric monitor <metric> --name "<name>" --when "<formula>" [--per total|each] [--to <destination>…]
--whenAlerts when
total(1h) > 5000000An activity metric over a moving window crosses a line (< for below).
total(1h) > before(1h) * 1.1Up more than 10% on the hour before.
total(24h) < before(24h) * 0.5Down more than half on the day before.
total(1h) > 3 * usual(1h, 7d)Over three times its usual hour, averaged over 7 days. Counts and sums only.
value > 50000A group or table total, or a --aggregate latest metric, against a line now.
FlagDescription
--name "<name>"What it watches for. Required.
--when "<formula>"The rule. A window is 5 minutes to 7 days, in whole 5 minutes. Required.
--perOn a split metric: total (as a whole) or each (every contract on its own).
--to <destination>Destination ids, labels ("#alerts") or kinds (telegram). Without one, alerts are kept on the alert’s page in the app.
contract-dev metric monitor "Swap fees" --name "Fee spike" --when "total(1h) > 3 * usual(1h, 7d)" --to "#alerts"
Last updated on