PixelBullet writes each run to a session directory that can be inspected while the process is active. The neutral API is pixelbullet/logging/log.h through //engine:pixelbullet_logging. Application startup supplies binary/log-root data through logging::StartupInfo and app/client version fields through logging::SessionMetadata.

Log Root

Windows: LOCALAPPDATA%\PixelBullet\Logs
Linux: $XDG_STATE_HOME/pixelbullet/logs or ~/.local/state/pixelbullet/logs
macOS: ~/Library/Logs/PixelBullet

Override precedence is:

--log-dir <path>
PB_LOG_DIR
platform default

Relative overrides resolve from the current working directory.

Session Layout

Each run creates:

<root>/<binary-stem>/<YYYY-MM-DD>/<timestamp>_pid-<pid>/

The directory contains:

session.log: the run narrative;
core.log: core and core.*;
client.log: client and client.*;
validation.log: vulkan.validation records;
events.ndjson: structured records;
session.json: session metadata.

The binary root contains latest.json pointing to the newest session. LogConfig::retained_session_count controls per-binary pruning; zero disables pruning.

Logger Identities

Canonical engine-side families are:

core, including core.app, core.graphics, core.image, core.assets, and core.shader;
client, with first-party descendants such as client.editor;
vulkan.validation.

Routing matches the exact family or a dot-delimited descendant. Similar string prefixes such as coreextra do not join the family. All validation records go to validation.log and events.ndjson; only validation warnings and errors are mirrored to session.log.

Inspection Order

Start with latest.json, then use session.log for the overall run, core.log for engine/graphics lifecycle, client.log for application-specific behavior, validation.log for Vulkan validation, and events.ndjson for machine filtering.

Applications and products define only their client.* identity and metadata; they do not own logging storage or routing.