Observability

Structured logs, metrics, traces, and alerts. Single pane of glass across all providers.

Logs

Every agent emits structured, level-tagged logs (debug, info, warn, error). Logs are streamed in real time via WebSocket and persisted to PostgreSQL for querying. Filter by session, agent, level, or free-text search.

logs.ts

// Stream logs in real time via WebSocket
const stream = theazo.logs.stream({
  sessionId: class="cb-str">'ses_...',
  level: class="cb-str">'error',        class="cb-cmt">// only errors
})

for await (const entry of stream) {
  console.log(entry.timestamp)  class="cb-cmt">// ISO 8601
  console.log(entry.level)      class="cb-cmt">// 'error'
  console.log(entry.agentId)    class="cb-cmt">// 'agt_...'
  console.log(entry.message)    class="cb-cmt">// structured log message
}

Querying historical logs

query-logs.ts

const { logs, total } = await theazo.logs.list({
  sessionId: class="cb-str">'ses_...',
  agentId: class="cb-str">'agt_...',
  level: class="cb-str">'warn',
  search: class="cb-str">'timeout',
  since: class="cb-str">'2025-05-01T00:00:00Z',
  until: class="cb-str">'2025-05-08T00:00:00Z',
  limit: class="cb-num">100,
  offset: class="cb-num">0,
})

Metrics

Theazo collects platform-level metrics you can query for dashboards and alerting. Key metrics include agents.active, agents.boot_time, cost.total, and error_rate.

metrics.ts

const metrics = await theazo.metrics.query({
  metric: class="cb-str">'agents.active',
  interval: class="cb-str">'1h',           class="cb-cmt">// 1m, 5m, 1h, 1d
  since: class="cb-str">'2025-05-01',
  until: class="cb-str">'2025-05-08',
})

// Returns time series:
// [
//   { timestamp: '2025-05-01T00:00:00Z', value: 12 },
//   { timestamp: '2025-05-01T01:00:00Z', value: 15 },
//   ...
// ]

Traces

In orchestrator mode (Full Platform and Primitives-only), Theazo creates per-tool-call spans within each agent run. Every model call, tool invocation, and file operation is captured as a span with timing and metadata. In infra-only mode, traces are limited to compute-level events (boot, exec, destroy).

traces.ts

const { traces } = await theazo.traces.list({
  agentId: class="cb-str">'agt_...',
})

for (const trace of traces) {
  console.log(trace.traceId)     class="cb-cmt">// 'trc_...'
  console.log(trace.spans)       class="cb-cmt">// Span[]
  class="cb-cmt">// Each span: { name, startTime, endTime, attributes, status }
}

Alerts

Theazo fires alerts for conditions that need attention. Alerts appear in the dashboard and can trigger webhooks.

Failed agents — an agent threw an unrecoverable error or exceeded max retries.
Cost limit warnings — a session has used 80% or more of its maxCost budget.
Long-running agents — an agent has been running for more than 30 minutes without completing.

alert-webhook.json

// Subscribe to alerts via webhook
// POST https://yourapp.com/webhooks/theazo
{
  class="cb-str">"event": class="cb-str">"agent.failed",
  class="cb-str">"data": {
    class="cb-str">"agentId": class="cb-str">"agt_...",
    class="cb-str">"sessionId": class="cb-str">"ses_...",
    class="cb-str">"error": class="cb-str">"Max retries exceeded",
    class="cb-str">"duration": class="cb-num">847,
    class="cb-str">"cost": { class="cb-str">"amount": class="cb-num">42, class="cb-str">"currency": class="cb-str">"usd" }
  }
}

Observability by mode

The depth of observability data depends on which mode you operate in. Full Platform and Primitives-only modes provide the richest data because Theazo controls the agent loop. Infra-only mode provides compute-level metrics only.

Capability

Full Platform

BYOI Primitives

Infra-only

Structured logs

Full

Compute only

Tool-call spans

Yes

Model token tracking

Yes

Compute metrics

Yes

Alerts

Full

Failures only

Observability works across all providers — one dashboard for E2B, Fly, and Docker. Logs, metrics, and traces are normalized into a single schema regardless of the underlying compute backend.

Method reference

theazo.logs.stream(filters)AsyncIterable<LogEntry>Stream logs in real time via WebSocket. Filter by session, agent, level.

theazo.logs.list(filters)Promise<{ logs, total }>Query historical logs with filters, pagination, and search.

theazo.metrics.query(opts)Promise<TimeSeries[]>Query metric time series by name, interval, and time range.

theazo.traces.list(filters)Promise<{ traces }>List traces with spans for a given agent or session.

theazo.traces.get(traceId)Promise<Trace>Fetch a single trace with all spans and metadata.