# Reading what your application actually used

> CPU, egress, database statements — counted by the machine that ran your code, not estimated. Read from your local platform with no account, so you can see what something costs while you are still writing it.

<!-- id: local-reading-what-your-app-used · area: local · stability: stable · html: https://osysharp.com/reference/local/reading-what-your-app-used/ -->

## Summary        {#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      {#signature}

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

| option | what it does |
|---|---|
| `--days <n>` | how far back to read, 1–365 (default 30) |
| `--all` | every application this platform has measured, not only this project's |
| `--json` | the platform's answer verbatim, on stdout — for a tool |
| `--devname <name>` | read a named instance instead of this project's |

## Description    {#description}

### What you get      {#what-you-get}

One row per meter, totalled over the range:

```console
osy usage
```

```text
╭─────────────┬───────────────────────┬───────────┐
│ 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"   {#not-measuring}

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   {#retention}

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       {#examples}

```console
osy usage                          # this project, last 30 days
```

```console
osy usage --days 7                 # just this week
```

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

```console
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       {#see-also}

[The inner loop](https://osysharp.com/reference/local/the-inner-loop/) — where the local platform this reads from comes from.

[Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) — what HAPPENED when the code ran, as opposed to what it cost.

[Seeing what a page cost](https://osysharp.com/reference/local/seeing-what-a-page-cost/) — the same question for one page's render, while you are looking at it.