# Recording a run

> Turns on step recording, so a trace carries the steps that LED to a failure and not only the failure itself. Faults are captured either way — you only need this when the question is "how did it get here?". `--full` also captures the values in scope at every step, for when the question is "why is this value wrong?".

<!-- id: local-recording-a-run · area: local · stability: stable · html: https://osysharp.com/reference/local/recording-a-run/ -->

## Summary        {#summary}

Records every step of every run, so that [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) can show you the path the code took. It is off
by default, because recording every step is the expensive half of tracing — and it is the half you usually do not need.

## Signature      {#signature}

```console
osy trace start
osy trace start --full
osy trace stop
```

## Description    {#description}

**Read this before turning it on:** a **fault is always captured**, recording or not. If a run throws, the place it
threw and the values that were in scope there are retained regardless — that capture costs nothing until something
actually throws. So if your question is *"why did this fail?"*, you do not need `osy trace` at all. Just run
[Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/).

Turn recording on when your question is different: **"how did it get there?"** — which branch it took, whether a loop
ran at all, what order things happened in. That is the story recording adds, and it is why the switch exists rather
than being always on: a step-by-step record of every run on the server is real overhead, so you turn it on for the run
you care about and off again afterwards.

What plain `osy trace start` records is the **path**, not the state at every step — where execution was, statement by
statement. The full state is captured where it earns its cost: at the fault. This is what keeps recording affordable
enough to leave on while you reproduce something.

**When the path is not enough, `--full` adds the state.** A wrong *result* — not a crash — is the case the path alone
cannot answer: you can see which branch ran, but not what the values were. `osy trace start --full` captures the locals
in scope at **every** step, on both sides of a client↔server run, so [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) shows each variable
as it changes. It is the heaviest mode — a snapshot of the stack at every step of every run — so turn it on for the run
you are chasing and off again after. A record is shown exactly as everywhere else: as its type and id, never fetched.

Recording applies to the local platform ([Running a local platform](https://osysharp.com/reference/local/running-a-local-platform/)) and stays on until you stop it. It covers
everything that runs there — your tests, your pages, your API calls alike.

## Examples       {#examples}

```console
osy trace start        # record the steps too
osy test               # reproduce the thing you are chasing
osy inspect            # ...then read what happened
osy trace stop         # done

osy trace start --full # ...or also capture the locals at every step, for a wrong-value bug
```

## See also       {#see-also}

[Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) — open a run and read it (works with recording off, too).

[Running a local platform](https://osysharp.com/reference/local/running-a-local-platform/) — the local platform that holds the traces.