Skip to content
macOSHow-To Published Updated 3 min readViews unavailable

How to Diagnose macOS Problems with log stream, Predicates, and Signposts

A privacy-conscious macOS unified-log workflow using process and subsystem predicates, levels, time bounds, signposts, collection, and reproducible evidence.

macOS unified logging combines structured messages, subsystem/category metadata, privacy controls, persistence policy, and signposts. log stream is most useful when a narrow predicate and reproduction window are defined before the failure. Running an unfiltered stream for hours creates noise, may expose private context, and still misses messages whose level was not persisted.

Establish identity and time

Record the affected app version, macOS build, user session, exact symptom, and wall-clock time with timezone. Prefer a stable logging subsystem chosen by the developer over filtering only the process name, because helpers and extensions run in separate processes and process IDs change.

Start with metadata fields rather than a free-text grep:

log stream --style compact --level info \
  --predicate 'subsystem == "com.example.product"'

To isolate one execution during a live reproduction, combine fields:

log stream --style json --level debug \
  --predicate '(process == "Example") && (category == "network")'

Predicate syntax follows Apple’s documented log filtering model. Quote it so the shell does not interpret operators. --level debug changes what the command displays; it does not guarantee historical debug messages were persisted before collection.

Reproduce one controlled action

Clear application state only if that is part of a separately recorded experiment. Start streaming, mark the time, perform one action, wait for the visible result, and stop. Keep stdout/stderr and the application response alongside the log. A message adjacent in time is correlation, not proof of causation; trace identifiers, request IDs, and signpost intervals make the link stronger.

Signposts represent begin/end intervals and discrete events under an OSLog. Instruments can visualize duration and concurrency without developers hand-parsing timestamps. Use stable names and avoid placing user documents, tokens, URLs, or raw payloads in signpost fields. Privacy annotations should be intentional—marking everything public makes support easier by weakening the user’s data boundary.

Query history with bounded windows

For a past incident, use log show with a precise start/end or --last window and the same predicate. Export only the needed fields and retain the original timestamp basis:

log show --style compact --last 10m \
  --predicate 'subsystem == "com.example.product" AND messageType >= error'

Check the installed log help for fields and options; examples should be validated on the target macOS release. A log collect archive is broader and appropriate when Apple or a vendor needs a reproducible diagnostic package. Treat it as sensitive data, inspect the collection scope, transfer it securely, and delete it under a retention policy.

Repeated-message compression, privacy redaction, persistence levels, and storage pressure can explain absent text. Do not disable redaction system-wide or conclude “the event did not happen” from one missing string. Compare application state, crash reports, network traces gathered with authorization, and subsystem health.

Turn observations into a test

The useful outcome is a timeline: trigger, subsystem event, operation interval, returned status, cleanup, and user-visible result. Add a signpost or structured error at the missing boundary, then reproduce again. Verify the fix by running the same predicate and acceptance action on both the failing and corrected builds.

Keep the predicate, command, OS build, app build, reproduction steps, and a hash of any exported log archive with the defect report. Another engineer should be able to rerun the same window without searching the entire log store. If the fix changes logging, assert both that the new diagnostic appears on failure and that normal operation does not emit secrets or an unbounded message rate.

Unified logging is strongest when queries are narrow and planned. Subsystems, categories, privacy annotations, and signposts create durable diagnostic structure; log stream then becomes a microscope rather than a fire hose.

Related:

Sources:

Comments