Recording a run

Summary#

Records every step of every run, so that Seeing what happened when your code ran 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#

osy trace start
osy trace start --full
osy trace stop

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.

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 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) and stays on until you stop it. It covers everything that runs there — your tests, your pages, your API calls alike.

Examples#

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#

Seeing what happened when your code ran — open a run and read it (works with recording off, too).

Running a local platform — the local platform that holds the traces.