log-analysis

Filter in the journal, not in your context

journalctl with no arguments is tens of thousands of lines, and pulling it into the conversation costs more than the answer is worth — a large result is spilled to a locator and you end up paging through it anyway. Every filter below happens on the machine, so what comes back is already the part that matters.

check_errors first, always. It is the dedicated tool, it costs one call, and on a machine with an obvious problem it is the whole investigation.

The filters worth knowing

Each of these answers a different question, and picking the right one is most of the skill:

• What is broken, this boot — journalctl -p 3 -b --no-pager (-p 3 is err and worse; -p 4 adds warnings when err is empty).
• What does this unit say — journalctl -u <unit> -n 100 --no-pager. The last lines before it stopped are the ones that matter; read the tail.
• When did it start — journalctl --since "2 hours ago" or --since "2026-08-24 09:00". Narrow by time before narrowing by content: an error that has been there for a month is not the one that broke this morning.
• The boot before this one — journalctl -b -1 -p 3. This is how you read a crash: the evidence is in the boot that ended, not the one you are in.
• Follow, bounded — journalctl -u <unit> -f never returns, so it is a job and never a plain command. job_start, work, then job_abort. Waiting on a follow with job_wait is waiting forever.

Add -o short-iso when you need to line events up against something else, and --no-pager always — a pager on a non-interactive command hangs waiting for a keypress nobody can send.

Files that are not in the journal

Application logs still live under /var/log and in home directories. run_command "grep -n <pattern> /var/log/<file>" beats read_file for a large one: grep returns the matching lines and read_file returns the file. For something genuinely huge, make the grep a job.

terminal_read is the other half people forget: it shows what a person typed in the shared terminal as well as what the agent ran. When the question is "what happened just before it broke", that is often where the answer is.

What an answer looks like

A log line pasted on its own is evidence without a claim. Say what you think happened, quote the line that says so, and give the timestamp. If the log does not answer the question, say what you searched and over what window — a negative result with its scope is useful, and a bare "nothing found" makes somebody redo the search.

Logs carry secrets

A trace can hold a token, a connection string, or a session cookie. You are reading into a conversation that is recorded, so quote the line that proves your point and not the twenty around it — and if the proof itself is a credential, say what you found without reproducing it.