Why does raw output from the Docker Engine API's /containers/{id}/logs look corrupted?

### The symptom You pull a container's logs straight off the Engine API and the output has junk in it: ``` curl -s --unix-socket /var/run/docker.sock \ 'http://localhost/v1.43/containers/pdfsign/logs?stdout=1&stderr=1' ``` Every few lines there is an unprintable byte, a run of NULs and a few more odd bytes. Nothing is broken. You are looking at Docker's multiplexed stream format, and `docker logs` looks clean only because the CLI decodes it before printing. ### Why the framing exists A container has two output streams, stdout and stderr, and the API returns them over one HTTP response body. Something has to mark where one ends and the other begins, so the daemon wraps each chunk in a small header: - **byte 0** — the stream: `0` stdin, `1` stdout, `2` stderr - **bytes 1-3** — zero padding - **bytes 4-7** — the payload length, a big-endian unsigned 32-bit integer - **then** exactly that many bytes of payload and repeats. A reader that wants the two streams apart reads eight bytes, switches on the first, reads the length, then reads exactly that many bytes before looking for the next header. This is a length-prefixed framing scheme, not a text protocol: the payload can contain anything, including newlines and bytes that look like headers, which is why you cannot recover the streams by scanning for delimiters. ### The TTY case is different The framing appears only when the container was created with `Tty` false. Ask for a TTY — `docker run -t`, or `Tty: true` in the create body — and the daemon allocates a pseudo-terminal for the process. A pty has *one* output side by construction: the process's stdout and stderr are both connected to it, and by the time the daemon sees the bytes there is nothing left to distinguish. So the response is a raw byte stream with no headers, and requesting `stderr=1` cannot separate anything, because the separation was lost inside the container. That is a real tradeoff, not a detail. Consider a PHP-FPM application image for a PDF-signing service that writes access lines to stdout and errors to stderr. Run it without a TTY and a log pipeline can route errors differently from access lines, because the frames say which is which. Run it with `-t` because the colours look nicer interactively, and every error is now indistinguishable from an access line for everything downstream. ### Where else the rule applies The same choice governs `GET /containers/{id}/attach`, its websocket variant, and the response to `POST /exec/{id}/start`. In each case the stream is framed if the container (or the exec instance) has no TTY, and raw if it does. Those endpoints hijack the connection after the response headers, so a client reads the frames directly off the socket. On recent API versions the response's `Content-Type` tells you which you are getting — a raw-stream media type for the TTY case and a multiplexed-stream media type otherwise — which is the robust way for a client to decide, rather than remembering how the container was created. ### How clients handle it The Go SDK ships `stdcopy.StdCopy(dstOut, dstErr, src)`, which reads the frames and writes each payload to the matching destination writer; the docker CLI uses exactly that, which is why `docker logs` and `docker logs 2>/dev/null` behave the way a shell user expects. Other SDKs expose an equivalent demultiplexing option. If you are writing a client by hand the decoder is a dozen lines, and writing it is worth doing once because it makes the format concrete. The wrong fixes are worth naming. Stripping non-printable bytes with `tr` destroys binary-safe payloads and still leaves the length bytes. Splitting on newlines and dropping short lines corrupts multi-line output. Requesting only `stdout=1` does remove the interleaving but still returns framed data — the framing is a property of the stream, not of how many streams you asked for. ### What an interviewer is testing This is a curiosity question rather than a screening one, and it separates people who have written a container-driving tool from people who have only used the CLI. The good answer names the header, explains why it exists, and knows that a TTY removes the framing at the cost of merging stderr into stdout for good.