Logging from Code

## The mechanism: a dispatch, not a write Postman scripts run inside a **sandbox** — an isolated JavaScript execution context created for the run. That context owns no file descriptors: no stdout, no stderr, no log file. The `console` object a script can see is therefore not the host's console. It is built by `PostmanConsole`, and every member it exposes does the same single thing: it **dispatches an `execution.console` event** across the sandbox boundary. So `console.log('hello')` does not print. It assembles a message that says *this execution, at this level, produced these values*, and hands that message outward. Whatever embedded the sandbox is on the other side of the boundary, and what happens next is entirely that host's business. ## What travels in the message Three things ride along with each dispatched `execution.console` event: - the **cursor** — the execution's own position, which tells a receiver *which* run, iteration and item produced the message, so that interleaved output can be attributed rather than guessed at; - the **level** — `log`, `warn`, `debug`, `info` or `error`, recorded as a **field on the event** rather than as a choice of destination; - the **serialised arguments** — your values, converted into a form that can cross the boundary. `clear` fits the same shape. It is a console event whose meaning is *discard what you are showing*, addressed to the receiver; the sandbox has nothing of its own to clear. ## Stream write versus event dispatch | | writing to a stream | dispatching a console event | |---|---|---| | destination | a descriptor the process owns | a listener outside the sandbox | | what is sent | bytes | cursor, level, serialised args | | role of the level | picks stdout or stderr | one field on a single event | | who decides visibility | whoever redirects the stream | whatever embeds the sandbox | | if nobody listens | the bytes still land somewhere | the message is simply not shown | | back channel | the process can read what it wrote | none; nothing returns to the script | ## Why the distinction is practical, not pedantic Four consequences follow directly from "message, not stream", and each of them surprises somebody at least once: 1. **Visibility is not yours to guarantee.** The host may render the message in a console pane, forward it somewhere, or drop it. A host with no display attached is a perfectly legitimate receiver; your call still succeeds and still produces nothing anybody sees. 2. **There is no back channel.** The call returns immediately, tells you nothing about who received the message, and raises nothing if nobody did. A script cannot read what it logged, so control flow can never legitimately depend on log output. 3. **Values are snapshots, not references.** The arguments are serialised at the moment of the call. What a reader eventually sees is a rendering of that serialisation — not a live window onto an object that your script may since have changed. 4. **Everything logged leaves the sandbox.** The serialised arguments cross the boundary to whoever is on the other side. That is fine for a request id and considerably less fine for a credential. ## How to think about it while writing scripts Treat `console.log` as **emitting a diagnostic about the run for a human who may or may not be looking**, in the same spirit as any structured logging call in application code — and specifically *not* as any of the following: a print statement, a value store, a return channel, or a way to make something happen. The level you choose is a label on the message that helps whoever is reading triage it; it is not a routing decision, because there is only ever one event type and one boundary. The useful habit that falls out of this is to make each message self-describing. Because the host decides how much context it shows around your line, a message that reads well on its own — naming the item, the value and why you cared — survives every host. A bare `console.log(x)` does not. ## Common misreadings - Believing the sandbox writes to the host process's stdout, and reasoning about redirection, buffering or pipes on that basis. None of those concepts apply to an event dispatch. - Assuming `console.error` reaches a different, more reliable place than `console.log`. Both dispatch the same event; only the recorded level differs. - Expecting a log line to be a durable record. Whether anything is retained is decided outside the sandbox entirely. - Using log output as a synchronisation or hand-off mechanism between parts of a run. There is no reader inside the sandbox to pick it up.