Observability

Observability & Logging

CortexPrism ships with a structured logging and observability stack. All components are opt-in.

Log Levels

Level	Description
trace	Extremely verbose — every round, chunk, span
debug	Internal state: turn start, tool calls
info	Operational events: server start, plugin load
warn	Recoverable problems: policy denials, retries
error	Failures that need attention (default)
silent	No output whatsoever

Configuration

{
  "logging": {
    "level": "info",
    "fileEnabled": true,
    "fileMaxBytes": 10485760,
    "fileMaxFiles": 5
  }
}

Or via environment variable:

CORTEX_LOG_LEVEL=debug cortex chat

Log file: ~/.cortex/data/logs/cortex.log

CLI

cortex log show                          # Last 100 entries
cortex log show --lines=200 --level=warn # Filter
cortex log tail                          # Live tail
cortex log clear                         # Truncate
cortex log path                          # File location
cortex log set-level info                # Update config
cortex log status                        # Current config

Namespaces

Namespace	Subsystem
agent:loop	Main agent loop
server	HTTP server
server:ws	WebSocket handler
tools:executor	Tool calls
trace	Distributed tracing
plugin:<name>	Per-plugin logger
langfuse	Langfuse integration

Prometheus / Grafana

Metrics exposed at GET /metrics with 29 metric families. Scrape config:

scrape_configs:
  - job_name: cortex
    static_configs:
      - targets: ['localhost:3000']

OpenTelemetry (OTLP)

{
  "logging": {
    "otlp": {
      "endpoint": "http://localhost:4318",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Langfuse (LLM Observability)

{
  "logging": {
    "langfuse": {
      "publicKey": "pk-lf-...",
      "secretKey": "sk-lf-...",
      "baseUrl": "https://cloud.langfuse.com"
    }
  }
}

Each agent turn creates a Langfuse trace with spans per tool call and generations per LLM call (with token usage and cost).

See Also

• Configuration — Full logging config reference
• Security — Cortex Lens audit log