Observability

Purple8 Builder exposes structured logs, agent execution metrics, distributed traces, and code coverage all through a single /api/observability prefix.

Endpoints

Endpoint	Description
GET /api/observability/agents	Per-agent execution stats (duration, token usage, retries)
GET /api/observability/system-metrics	CPU, memory, queue depth
GET /api/observability/logs	Structured log stream with level/phase/session filters
GET /api/observability/traces	Distributed trace tree per pipeline session
GET /api/observability/coverage	Test coverage summary
POST /api/observability/run-tests	Trigger test suite and stream results

Agent metrics

Each pipeline run records:

• Agent name, phase, and category
• Wall-clock duration (ms)
• LLM tokens consumed (prompt + completion)
• Retry count (if the auto-retry loop fired)
• Exit status (success, skipped, error)

GET /api/observability/agents?session_id=abc123

{
  "session_id": "abc123",
  "agents": [
    {
      "name": "ArchitectureAgent",
      "phase": "design",
      "duration_ms": 3120,
      "tokens": { "prompt": 1840, "completion": 614 },
      "retries": 0,
      "status": "success"
    }
  ]
}

Structured logs

All log lines are emitted as JSON with level, phase, session_id, agent, and message fields so they can be shipped directly to any log aggregation backend (Loki, CloudWatch, Datadog).

{
  "timestamp": "2025-01-15T10:23:44Z",
  "level": "info",
  "phase": "generation",
  "session_id": "abc123",
  "agent": "BackendAgent",
  "message": "Generated 14 route handlers"
}

Distributed traces

Each pipeline session has a root span. Sub-spans are created for every agent call and every LLM request, giving you a full waterfall view of where time is spent.

GET /api/observability/traces?session_id=abc123

The trace tree maps directly onto the pipeline phases: design → plan → generate → refine → validate.

Grafana integration

The deploy/grafana/ folder in the repository ships a pre-built Grafana dashboard that wires up all the above metrics via the Builder API. Import it into any Grafana 10+ instance.