Borealis-Github-Replica/Docs/logging-and-operations.md

Logging and Operations

Back to Docs Index | Index (HTML)

Purpose

Describe Borealis operational logging, retention, and core runtime checks.

Log Locations

• Engine primary log: Engine/Logs/engine.log (daily rotation).
• Engine error log: Engine/Logs/error.log.
• Engine API access log: Engine/Logs/api.log.
• Service logs: Engine/Logs/<service>.log (per-domain).
• VPN logs: Engine/Logs/VPN_Tunnel/tunnel.log and Engine/Logs/VPN_Tunnel/remote_shell.log.
• Agent logs: Agent/Logs/agent.log and Agent/Logs/agent.error.log (daily rotation).

Log Retention

• Retention is managed via /api/server/logs endpoints.
• Retention overrides are stored in Engine/Logs/retention_policy.json.

Operational Health

• GET /health returns liveness status.
• GET /api/server/time returns server clock information after login.

API Endpoints

• GET /health (No Authentication) - liveness probe.
• GET /api/server/time (Operator Session) - server time.
• GET /api/server/logs (Admin) - list logs and retention metadata.
• GET /api/server/logs/<log_name>/entries (Admin) - tail log entries.
• PUT /api/server/logs/retention (Admin) - update retention policies.
• DELETE /api/server/logs/<log_name> (Admin) - delete log file(s).

Related Documentation

• Engine Runtime
• Security and Trust
• API Reference

Codex Agent (Detailed)

Engine log formatting

• Service logs are written via service_log in Data/Engine/services/API/__init__.py.
• Format: [YYYY-MM-DD HH:MM:SS] [LEVEL][CONTEXT-<SCOPE>] message.
• Context values are derived from agent context headers or message patterns.

Log retention implementation

• Data/Engine/services/API/server/log_management.py manages retention.
• Retention overrides are stored in Engine/Logs/retention_policy.json.
• The API never deletes the active log file automatically.

Operational checks

• Startup warnings appear in Engine/Logs/engine.log.
• API access metrics appear in Engine/Logs/api.log (method, path, duration, status).
• VPN-specific logs are under Engine/Logs/VPN_Tunnel/.

Agent logging notes

• Logs are scoped by context (SYSTEM vs CURRENTUSER) in prefixes.
• Role-specific logs live under Agent/Logs/<service>.log.
• VPN logs are kept in Agent/Logs/VPN_Tunnel/.

Debug workflow

• Start with the log file closest to the symptom.
• Use API log lines to confirm the request reached the Engine.
• Use service logs to diagnose domain-specific behavior.
• If troubleshooting WireGuard, inspect both Engine and Agent VPN logs.

Operational safety

• Do not delete logs by hand while debugging; use the log API or archive first.
• Keep runtime artifacts inside Engine/ and Agent/ to preserve boundaries.
• If you change log formats, update this document and engine-runtime.md.