mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2026-02-04 08:10:32 -07:00
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# Logging and Operations
|
|
[Back to Docs Index](index.md) | [Index (HTML)](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](engine-runtime.md)
|
|
- [Security and Trust](security-and-trust.md)
|
|
- [API Reference](api-reference.md)
|
|
|
|
## 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`.
|