Logs and Diagnostics

Logs and diagnostics

The aggregated feed

Logs in the sidebar combines the running containers and machines into one feed, on This Mac and on every paired host, each line tagged with where it came from. It answers "what has everything been saying" without visiting each container's detail tab in turn.

It was per-source blocks first, which reads well with two containers and turns into a scrolling exercise with five. One stream you can filter is almost always what you actually want.

The feed is a table: Object (the container or machine, which opens it), Host once a host is paired, and Message, with an optional Received column. Select lines with the usual table selection, or all of them with the checkbox at the left of the toolbar.

The toolbar

The same band every other section has, in icons, with the words in each tooltip:

• Output or Boot — process output, or a machine's boot log.
• Lines — read the last 100, 200, 500 or 1,000 lines from each source.
• Sources — All, Containers or Machines, then any individual source that is running. Filled when it narrows the feed, hollow when it does not, the same signal as every other filter.
• Display — Wrap lines, and Show timestamps, which adds the Received column.
• Search, beside the filter, as in every section.
• Export CSV, Live and Refresh on the right.

Stopped things are not in the feed, and not in the source list either: logs has nothing to read from them, and a control that cannot work should not be offered. Changing a filter re-reads on its own, and so does starting or stopping something.

Why the times say "Received"

container logs has no --timestamps — the captured help confirms it — so the only clock Flotilla has is the moment it read a chunk, which is the same for every line in that chunk. The column is called Received to say so: it is not a time the container wrote.

That is also why a fetched feed is not chronological across sources and does not pretend to be. Lines keep their source's own order, and sources follow a stable order. Sorting by a fabricated time would look authoritative and order lines by nothing at all. The Sources filter is what actually answers "just show me this one".

Live

Live follows the selected sources as they write, through container logs --follow, on This Mac and on hosts through each host's own follow. While streaming, every line is appended as it arrives, so arrival order across sources is genuine ordering — the sequence in which the runtime handed Flotilla the lines, to within 120 milliseconds. The interleaving the fetched feed refuses to fake is exactly what Live earns.

Live follows at most eight sources at once. Each is its own process, and a source column stops being scannable at about that many names anyway. Above eight, Live is refused with a reason rather than quietly following a subset: a live view that silently omits sources is worse than one that will not start, and the fix — narrowing the Sources filter — is named in the tooltip.

A source that could not start, or that ended by itself, is shown above the feed the way a failed fetch is. A stream that died must not just stop producing lines. A host whose Flotilla predates streaming appears there too, saying so.

Export

Export CSV saves what you selected, or everything you can see, and its tooltip says which — "Export 12 selected lines" and "Export all 847 lines" are different enough that the button has to say which it is about to do. A failed save says so rather than doing nothing.

Settings

Three on the Advanced tab — see Settings:

• Lines requested when opening logs — how many are asked for per source.
• Log buffer cap per container — how many are retained in memory.
• Show timestamps.

A container's own Logs tab has the same Live and Refresh, in the same place, so the control you reach for is where you expect it on either screen. See Containers.

Output ceilings

Each stream of each command is capped at 4 MiB. Past the ceiling, output is read and discarded rather than the read being stopped — stopping the read is what re-creates the deadlock the ceiling exists to prevent.

When it happens, the result is reported as truncated rather than presented as complete. A truncated log that says so is usable; one that silently ends is misleading.

Live follow is the one place output is read without an end, and it is never asked of the ordinary runner: a streaming command never reaches end-of-file, so through a runner that reads to the end it would be an infinite read followed by a guaranteed timeout. Following has its own streaming path.

Activity

Activity, beside Logs in the sidebar, is the other half: not what containers said, but what happened — containers, groups and machines starting and stopping, images, volumes and networks created and removed, the container service started or found stopped, and Macs paired and updated. Each Mac's page under Hosts has an Activity tab of what happened to that Mac: updates, pairing, container installs, and the runtime starting and stopping. See Overview.

Support bundle

Help ▸ Create Support Bundle… — also in the menu-bar menu, and under Settings ▸ Advanced ▸ Diagnostics — assembles a redacted diagnostics bundle: a snapshot of the app's state, its settings with sensitive keys left out entirely, its error log, and a manifest.

It shows you exactly what is in it before anything is written. Every file is listed with its size and a plain description, and any file can be read in full. A bundle you cannot inspect is one people either send blindly or never send at all, and both are worse than not offering it.

Save… writes it where you choose, as a folder of plain files rather than an archive, so every one is readable without unpacking anything. Nothing is uploaded; Flotilla has no server to upload it to.

The error log is only there if Keep a local error log is on in Advanced. It is off by default.

Redaction is the point of it

It is tested adversarially. The redactor covers home directory paths, credentials embedded in URLs, private keys and certificates, tokens, and bare account-name fields.

That last category exists because of a real failure: the machine Inspect panel printed "Secrets are redacted" above userSetup.username: <the account name>. Every rule matched a path like /Users/<name>; nothing matched a bare account field — so the host user's own name was displayed and handed out by Copy JSON, under a note promising otherwise. A note claiming a protection is a promise the code has to keep.

Bare user is deliberately not redacted, because container configuration uses it for the runtime user and redacting it would destroy information you need.

A leak is a refusal, not a warning. After redaction, a second, deliberately simpler audit reads every byte of the bundle. If it finds anything that looks like a secret, the bundle is withheld: the sheet says what kind of thing was found and in which file, without reproducing it, and that it is a bug in Flotilla's redaction, not something you did. Nothing is written. Redacting harder and carrying on would hide exactly the bug that needs reporting.

Inspect

Containers, machines, volumes and networks all have an Inspect view, and all use one implementation — the same table, the same flattening walk, the same Table or JSON switch. They did not always: the machine tab shipped JSON-only because the row view was private to the container view, which meant a fix to one could not reach the other. Volumes and networks would have made four copies.