# How Logging Is Handled in LoopX: A Layered Privacy-First Strategy

> Discover how LoopX implements a five-layer logging strategy to protect sensitive data. Learn about its privacy-first approach ensuring no private information leaks.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-13

---

**LoopX employs a five-layer logging architecture that strictly separates public-safe diagnostic output from sensitive internal data, using forbidden-field constants, dedicated trace directories, and best-effort exception handling to ensure no private information leaks into standard logs or structured event records.**

The LoopX project (huangruiteng/loopx) implements a privacy-centric logging system designed for scenarios where log data must remain safe for public inspection. Rather than treating all diagnostic output equally, logging in LoopX categorizes information into distinct layers—standard Python logs for humans, structured JSONL events for automation, and quarantined trace files for internal debugging—while explicitly blocking sensitive fields like credentials and raw system logs from ever reaching persistent storage.

## The Five Layers of LoopX Logging

LoopX organizes its diagnostic infrastructure into five distinct layers, each serving a specific purpose in the observability stack.

### Standard Python Logging for Human Diagnostics

At the application layer, LoopX components expose an optional `self.logger` attribute that receives a standard `logging.Logger` instance created via `logging.getLogger(__name__)`. This pattern appears throughout the codebase, notably in [`loopx/terminal_bench_agent.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/terminal_bench_agent.py) (lines 749–752), where diagnostic calls are wrapped in defensive `try/except` blocks to prevent logging failures from crashing the agent.

Scripts such as [`scripts/skillsbench_automation_loop.py`](https://github.com/huangruiteng/loopx/blob/main/scripts/skillsbench_automation_loop.py) demonstrate direct usage of `logging.getLogger(__name__)` for standalone automation tasks. When an exception occurs during operation, the agent captures it via `logger.exception()` but continues execution, ensuring that diagnostic gaps never halt the workflow.

### Structured JSON Event Logs (rollout-event-log.jsonl)

For machine-readable observability, LoopX writes compact **rollout event logs** to a JSONL file named `rollout-event-log.jsonl`. The implementation in [`loopx/rollout_event_log.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/rollout_event_log.py) provides the `append_rollout_event()` function (lines 368–421), which appends public-safe event records to a specified path.

These events deliberately exclude sensitive payload fields. The constant `WORKER_BRIDGE_BENCHMARK_RUN_FORBIDDEN_PUBLIC_FIELDS` enumerates prohibited keys—including `raw_logs` and `credential_values`—ensuring that only sanitized data enters the event stream. Each event may include a `claim_boundary` field describing the public claim scope of the data. To locate the correct log path, use the `rollout_event_log_path()` helper, which constructs filenames from runtime roots and goal identifiers.

### HTTP Server Logging with Conditional Verbosity

The status server in [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) (lines 779–822) overrides `BaseHTTPRequestHandler.log_message()` to suppress routine HTTP diagnostics unless explicitly enabled. When the server starts, it prints its URLs to stdout, but request logging only occurs when instantiated with `verbose=True`. This design prevents noisy production logs while allowing detailed tracing during development or debugging sessions.

### Worker-Bridge Trace Directory

Internal diagnostics that might contain sensitive context—such as counter traces and benchmark run metadata—are isolated to a dedicated trace directory, typically `/logs/agent`. The constants defining these locations reside in [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py) (lines 15–28), which specifies filenames like `loopx-counter-trace.jsonl` and [`loopx-worker-benchmark-run.json`](https://github.com/huangruiteng/loopx/blob/main/loopx-worker-benchmark-run.json).

These files serve as high-fidelity debugging targets that are explicitly filtered before exposure to external systems. By segregating raw traces from public event logs, LoopX maintains a hard boundary between developer-facing diagnostics and user-facing audit trails.

### Best-Effort Logging Patterns

Throughout the codebase, LoopX adopts **best-effort logging semantics**. Components attempt to write diagnostic files or emit log records, but any I/O or formatting exceptions are caught and logged via the optional logger without re-raising. This pattern appears in [`loopx/terminal_bench_agent.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/terminal_bench_agent.py) (lines 749–752), where the agent gracefully degrades if the filesystem becomes unavailable, ensuring that observability failures never cascade into workflow failures.

## Privacy Controls and Forbidden Fields

The safety of LoopX logging relies on explicit deny-lists rather than implicit trust. The system enforces privacy through three mechanisms:

- **Forbidden Field Constants**: The `WORKER_BRIDGE_BENCHMARK_RUN_FORBIDDEN_PUBLIC_FIELDS` constant acts as a definitive blocklist. Any event payload containing these keys is either stripped or rejected before serialization.

- **Claim Boundaries**: Event construction includes metadata describing what portions of the data are safe to publish, allowing downstream consumers to make informed redaction decisions.

- **Physical Isolation**: Raw traces live in separate directory structures (`/logs/agent`) with distinct access patterns from the main event log, preventing accidental inclusion in log aggregation pipelines.

## Implementation Examples

The following patterns demonstrate how to interact with LoopX's logging infrastructure in application code.

### Using the Optional Logger Component

```python
import logging

class MyAgent:
    def __init__(self):
        # Optional logger injection for diagnostic flexibility

        self.logger = logging.getLogger(__name__)

    def execute_task(self):
        try:
            # Critical task execution

            self.process_data()
        except Exception:
            # Best-effort: Log the exception but never crash the agent

            if self.logger:
                self.logger.exception("Task execution failed in MyAgent")

```

### Appending Structured Rollout Events

```python
from pathlib import Path
from loopx.rollout_event_log import append_rollout_event, rollout_event_log_path

# Initialize paths

runtime_root = Path("/var/loopx/runtime")
goal_id = "benchmark-run-001"
log_path = rollout_event_log_path(runtime_root, goal_id)

# Construct a public-safe event (no raw_logs or credentials)

event = {
    "event": "goal_started",
    "timestamp": "2026-08-13T12:00:00Z",
    "goal_id": goal_id,
    "log": "public-safe diagnostic info"
}
append_rollout_event(log_path, event)

```

### Starting the Status Server with Verbose Logging

```python
from loopx.status_server import serve_status

serve_status(
    registry_path=Path("/tmp/registry"),
    scan_roots=[Path("/data/scans")],
    host="127.0.0.1",
    port=8000,
    verbose=True,  # Enables HTTP request logging to stdout

    enable_reward_write_api=False,
    enable_control_plane_write_api=False,
)

```

## Summary

LoopX handles logging through a sophisticated five-layer architecture that prioritizes data privacy without sacrificing observability:

- **Standard Python logging** provides human-readable diagnostics via optional `self.logger` attributes wrapped in exception-safe blocks.
- **Structured JSONL event logs** capture public-safe automation data through `append_rollout_event()` while blocking forbidden fields like credentials.
- **HTTP server logging** remains silent in production unless explicitly enabled via `verbose=True`.
- **Trace directories** quarantine sensitive internal diagnostics in `/logs/agent`, physically separating them from public event streams.
- **Best-effort semantics** ensure that logging I/O failures never interrupt critical agent workflows.

## Frequently Asked Questions

### How does LoopX prevent sensitive data from leaking into standard logs?

LoopX prevents leakage through a combination of forbidden-field constants (`WORKER_BRIDGE_BENCHMARK_RUN_FORBIDDEN_PUBLIC_FIELDS`) that explicitly list prohibited keys such as `raw_logs` and `credential_values`, and centralized event construction that validates payloads against these lists before writing to `rollout-event-log.jsonl`. Additionally, raw diagnostic data is written to isolated trace directories rather than the standard log stream.

### What distinguishes the structured event logs from standard Python logging in LoopX?

Standard Python logging in LoopX targets human operators and uses conventional `logging.Logger` instances for diagnostic messages, while structured event logs are JSONL files optimized for machine parsing and automation. The structured logs reside in specific paths constructed via `rollout_event_log_path()` and are strictly filtered for public-safe fields, whereas standard logs may contain more verbose context intended for developers.

### Can LoopX operate with logging disabled for high-security environments?

Yes. Because LoopX uses optional logger injection and best-effort logging patterns, components function correctly when `self.logger` is `None` or when log directories are unwritable. The status server explicitly supports disabling HTTP request logging by setting `verbose=False`, and the rollout event system fails gracefully if the event log file cannot be accessed.

### Where are high-fidelity diagnostic traces stored in LoopX?

High-fidelity traces containing potentially sensitive internal state are stored in the worker-bridge trace directory, typically located at `/logs/agent`, with specific filenames defined in [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py) (lines 15–28) such as `loopx-counter-trace.jsonl` and [`loopx-worker-benchmark-run.json`](https://github.com/huangruiteng/loopx/blob/main/loopx-worker-benchmark-run.json). These files are intended for debugging only and are filtered before any public exposure.