Logging and observability
Correlate runtime, agent, security, memory, tool, gateway, and database activity without leaking secrets.
Logging principles
- Prefer structured JSON or logfmt over prose-only logs
- Treat stable event names as an interface
- Shape errors with kind, code, message, and stack where available
- Whitelist safe fields and redact by default
Correlation fields
Requests should carry `trace_id`, `span_id`, and `request_id`. Session, tenant, user, agent, service, component, environment, version, and timing fields add context only where they apply.
Severity model
- TRACE for feature-gated token and transformation detail
- DEBUG for developer decisions and cache behavior
- INFO for lifecycle and completed operations
- WARN for recoverable degradation and fallback
- ERROR for failed requests or subsystems
- FATAL when the process cannot continue safely
Event families
The repository defines stable event families for runtime lifecycle, security and ledger, memory, tools, gateway, and database work. Examples include `runtime_ready`, `capability_denied`, `memory_redaction_applied`, `tool_invoke_failed`, `gateway_rate_limited`, and `db_tx_rollback`.
Sensitive data
Logs exist for operational truth and auditability, but secrets, credentials, raw private prompts, and unrestricted payloads do not belong in them. Redaction remains part of the logging contract rather than an optional cleanup step.