xr_ai_logging#

Shared loguru setup for the xr-ai monorepo.

Every process in a sample run (orchestrator, worker, hub, AI services, typed services, cloudxr) calls setup_logging() once at startup. The result is a single, unified logging stack:

  • stderr sink — level controlled by XR_AI_VERBOSE (DEBUG when truthy, INFO otherwise). What the user sees in their terminal.

  • file sink — always DEBUG. Path: /tmp/log_<namespace>_<YYYY-MM-DD_HH-MM-SS>/<name>.log (tmpfs-backed on most distros, so logs are RAM-resident and clear on reboot). One subfolder per run holds every process’s log file for that run; the log_ prefix makes the run folders easy to spot in /tmp and to clean up with one rm glob. Loguru retention="7 days" auto-prunes.

  • stdlib bridge — a logging.Handler (_InterceptHandler) routes any record emitted via logging.getLogger(...) into loguru. This is how utils/xr-ai-launcher/ (stdlib-only by contract) and agent-sdk/xr-ai-hub/ (pyzmq+msgpack-only by contract) end up in the same file/stderr sinks even though they cannot import loguru.

Subprocess coordination#

The orchestrator stamps three env vars into os.environ so subsequent uv run subprocesses inherit them and produce log files inside the same per-run subfolder:

  • XR_AI_LOG_NAMESPACE — sample/process group (e.g. xr-render-demo).

  • XR_AI_LOG_TIMESTAMP — single YYYY-MM-DD_HH-MM-SS stamp per run.

  • XR_AI_LOG_ROOT — absolute path to the directory that holds the per-run log_<namespace>_<timestamp>/ folder. Defaults to /tmp; set explicitly (e.g. in CI or for a debug session) to redirect the whole stack to a different root with one variable.

Functions#

setup_logging(→ pathlib.Path)

Install loguru sinks for this process. Returns the file path.

print_task_done_banner(→ None)

One-shot banner on stderr marking the end of an agent task.

Package Contents#

xr_ai_logging.setup_logging(
name: str,
*,
namespace: str | None = None,
) → pathlib.Path#

Install loguru sinks for this process. Returns the file path.

Args:
name: Process identifier shown in the log filename and stderr

format (e.g. "orchestrator", "worker", "hub", "vlm", "stt").

namespace: Optional grouping for related processes; typically the

sample name (e.g. "xr-render-demo"). Falls back to the XR_AI_LOG_NAMESPACE env var, then to name. Setting it from the orchestrator and propagating via env keeps all subprocess logs together under the same directory.

xr_ai_logging.print_task_done_banner(
label: str,
*,
status: str = 'done',
detail: str | None = None,
duration_s: float | None = None,
) → None#

One-shot banner on stderr marking the end of an agent task.

Mirrors _print_log_dir_banner() styling so begin/end milestones bracket the run with matching dim-grey bars. status selects the headline color (done green, interrupted yellow, error red); unknown statuses fall back to the done color.