Reading what your application actually used

Summary#

Every unit of work your application does is measured as it runs — the CPU it used, the bytes it sent back, the statements it ran against its database. osy usage is how you read that for the code in front of you, before it is deployed anywhere.

The figures are counted, not estimated. They are the same measurements a deployed application is billed and limited on, taken the same way, which is the point: you can see the shape of what something costs while it is still cheap to change.

Signature#

osy usage [path] [--days <n>] [--all] [--json] [--devname <name>]

Description#

What you get#

One row per meter, totalled over the range:

osy usage

╭─────────────┬───────────────────────┬───────────┐
│ Application │ Meter                 │     Total │
├─────────────┼───────────────────────┼───────────┤
│ Billing     │ CpuMicros             │     2.1 s │
│             │ DbRequests            │     1 284 │
│             │ ResponseBytes         │ 143.6 KiB │
│             │ Requests              │       155 │
╰─────────────┴───────────────────────┴───────────╯

Each meter is printed in its own unit. That matters more than it looks: CpuMicros is microseconds and CpuMs is milliseconds, and nothing in the number itself tells them apart — so the unit is read from the meter's name rather than guessed at.

A meter this version of the CLI has never heard of is printed as a plain count rather than dropped. The platform names its own meters, and hiding the ones a reader did not recognise would hide the newest thing it measures.

"Not measuring" is not "nothing used"#

Two different answers, and they are never printed the same way:

• "This platform is not measuring application usage" — nothing on this host is collecting. There is no figure.
• "Nothing measured in the last N days" — collecting happened, and found nothing. Your application has not run.

A tool reading --json gets the same distinction as a measuring field, for the same reason: told "0 used" for a host that is not measuring, you would go looking at an idle application instead of a missing component.

Where the numbers live, and for how long#

They are written to the platform this project runs on, roughly every fifteen seconds, and kept for 40 days. They are not sent anywhere: a local platform is not a zone, nothing collects from it, and nothing about your code leaves your machine.

A deployed application's measurements travel differently — the zone running it reports them to the control plane, where they become the usage its team reads and its plan's limits are enforced against. Same measurements, same units; this command is the local half.

Examples#

osy usage                          # this project, last 30 days

osy usage --days 7                 # just this week

osy usage --all                    # every application this platform has measured

osy usage --json | jq '.days[0].meters.CpuMicros'

⚠ --json writes only the answer to stdout — the line naming which platform answered goes to stderr, so a pipe stays machine-readable.

See also#

The inner loop — where the local platform this reads from comes from.

Seeing what happened when your code ran — what HAPPENED when the code ran, as opposed to what it cost.

Seeing what a page cost — the same question for one page's render, while you are looking at it.