SDK
An expectation settles against readings, and the readings usually come from somewhere that isn't Ledger — a cron job, a webhook, a warehouse export, your own product. The SDK is the shortest path from there to here.
npm install @zerowidth/ledger-sdkimport { createLedgerClient } from "@zerowidth/ledger-sdk"
const ledger = createLedgerClient({ apiKey: process.env.ZEROWIDTH_API_KEY! })
ledger.event("demo_booked") // one happened
ledger.event("tokens_used", 45) // 45 more happened
ledger.measure("triage_time_minutes", 4.2) // a level you observedIt needs a key carrying ledger:metrics:write — the Push metric readings scope is exactly that and nothing else, which is what you'd hand a cron job.
Events and measures
The two calls match the two kinds of metric:
event()a thing that happenedA reading with no value counts as one occurrence; with a number, that many. Send what happened since the last reading — 45 means 45 more. A running total would be counted again in every bucket it falls into.
measure()a level you observedThe reading carries the value, and it's the level at that moment. An absolute number is exactly right here.
Recording can't break your code
event() and measure() return immediately and never throw. Writes are buffered and sent in batches, and anything that goes wrong goes to your onError callback instead of into the path of whatever you were doing. A metrics outage shouldn't take down the thing being measured.
You don't register a metric first
Writing to a slug that doesn't exist creates it. The metric shows up in your gallery marked as auto-created, and stays that way until someone gives it a name and a unit. So instrumenting something is one line, not a setup step and then a line.
Where the readings land
A reading is evidence, not just a number on a chart. When it arrives, every open entry whose expectation watches that metric hears about it — which is the difference between writing here and writing to a metrics database.
Open source
The SDK is public and Apache-2.0, at @zerowidth/ledger-sdk. Its README is the full reference; the HTTP contract underneath is the same one documented in Metrics, so anything that can POST JSON can do this without the package.