> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operator observability: dashboards, logs, and audit — what to look at when

> Frame your operator surface end-to-end: when a moment-level answer lives in the delivery log or live tail, when trend questions belong to dashboards and Insights, when a durable record means webhooks or exports, and where alerting hooks in.

# Operator observability: what to look at when

Orbit exposes four operator surfaces for watching your traffic — **delivery logs**, **live request/event streams**, **analytics dashboards and Insights**, and **the audit trail** — plus three ways to feed data into your own systems (webhooks, polling exports, scheduled reports). This page frames what each surface is for, so you stop opening a dashboard to find a single message, or paging over an ephemeral event stream when you need a durable record.

## The surfaces at a glance

| Surface                                     | Question it answers                                                                                                                                                        | Access                                                                                                                |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [Delivery log](/guides/delivery-log)        | "Did this one message get there?" — a single-message lookup by `msg_…` id, provider reference, recipient, or sender, across SMS, WhatsApp, email, and voice.               | Dashboard (**Messages → Tools → Delivery log**) or `GET /messages` filtered.                                          |
| [Live request log](/api-reference/log-tail) | "What is my tenant doing right now?" — every API request handled for your tenant over SSE, sub-second after the response completes. For live debugging only.               | Dashboard **Live tail** toggle, or `GET /logs/tail`.                                                                  |
| [Events firehose](/api-reference/events)    | "What just happened in the workspace?" — the recent platform-wide event buffer (message sent, agent run, flow step, contact updated). Bounded, in-memory, \~15-minute TTL. | `GET /events` (poll) or `GET /events/stream` (SSE).                                                                   |
| [Analytics API](/api-reference/analytics)   | "How is traffic trending?" — message volume, deliverability, cost, and goal-conversion aggregates, served from a read-replica (1–3 s lag).                                 | `GET /analytics/…`, dashboard **Analytics** pages.                                                                    |
| [Insights API](/api-reference/insights)     | "What are my AI agents costing and returning?" — LLM spend, ROI, containment, benchmarks; also read-replica-backed.                                                        | `GET /insights/…`, dashboard **Insights** pages.                                                                      |
| \[Audit & exports]                          | "Show me the durable, tamper-evident record." — signed per-conversation exports and bulk exports for handover, archive, or reconciliation.                                 | [Conversation export (vCon)](/guides/conversation-export-vcon), [Conversation archive](/guides/conversation-archive). |

## Delivery logs vs dashboards vs audit — three different questions

Operators reach for a surface by habit; the honest distinction is the granularity of the question.

**Moment-level (a single thing).** The [delivery log](/guides/delivery-log) and [live tail](/api-reference/log-tail) resolve individual messages and requests. A correlated lookup on a `msg_…` id in the delivery log is the canonical way to answer "did this exact send arrive" — no aggregate can tell you that, and an aggregate *blurred by replica lag* can disagree with it for up to three seconds.

**Trend-level (a shape over time).** The [Analytics API](/api-reference/analytics) and [Insights API](/api-reference/insights) are read-replica-backed deliberately: they are cheap to call for dash-rendering precisely because they accept a 1–3 second lag behind the primary. Treat either as the answer to "what does the last N days look like," and *not* as the answer to "what happened to message X two seconds ago." Delivery outcome aggregates also exclude [operational sentinels](/concepts/operational-sentinels) (test sends, suppressions, deletes) from their denominators — mirror that discipline in your own reporting or your delivery-rate math drifts.

**Durable record (keep it, prove it).** The [Events firehose](/api-reference/events) is explicitly *not* durable — it is a bounded, in-memory replay buffer (\~5000 events, \~15-minute idle TTL) that degrades open when the real-time store is unavailable. Anything you would build a system of record, reconciliation job, or compliance archive off of must come from [webhooks](/webhooks/overview) (durable, retried, signed delivery to your endpoint) or from exports — the [vCon conversation export](/guides/conversation-export-vcon) signs each export at emit time, and the [conversation archive](/guides/conversation-archive) produces bulk CSV/JSON for filtered slices. The read-facing [Events API](/api-reference/events) page itself says this; treat it as a convenience for live dashboards, not an audit log.

## Push, poll, or schedule — feeding your own systems

Three transport shapes exist; pick by *how often* and *who owns the storage*.

* **[Webhooks](/webhooks/overview) — push, real-time, durable.** The preferred feed for anything with a retention requirement. Orbit delivers the event envelope to your endpoint with signature headers, retries, and a dead-letter queue; your system owns the record from then on. Use webhooks when you need a durable event history, when you drive a downstream workflow (Sync to CRM, kick a ticket, update a contact), or when the 1–3 s replica lag on dashboards matters.
* **Polling the APIs — on demand, latest-window.** The [Events `GET`](/api-reference/events) and per-message `GET /messages/:id` calls are right for ad-hoc reconciliation, or for operator UIs that poll the current state of a message after an operator delete/cancel (no webhook fires for those flows). Do not build a polling loop on the events buffer as your system of record — evicted ids are gone.
* **[Scheduled exports](/channels/analytics#scheduled-exports) — batch, emailed.** For the daily/weekly trend rollup that a stakeholder reads, `POST /analytics/scheduled-reports` registers a recurring report and Orbit renders and emails it. Prefer this over building a polling job that re-derives the same aggregate. Creating or editing a schedule requires an `owner` or `admin` role because the payload carries per-tenant PII (top contacts, spend).

## Alerting — where thresholds live

Alerting is not one surface; each metric class has its own rule surface, and the right home depends on the thing being measured.

* **AI spend alerts** live on the [Insights budget](/api-reference/insights): `PUT /insights/llm-spend/budget` sets the daily-cap and threshold that the `by-feature` endpoint reports breaches against. The overview endpoint returns `cap_percentage` so your wallboard can render it.
* **Queue / voice alerts** live as [wallboard alarm rules](/guides/wallboard-alarm-rules): each rule binds a metric (`waiting`, `longest_wait`, `service_level`, `abandon_rate`, `agents_available`), a comparator, and a threshold; omit `queue_id` for a tenant-wide rule. The wallboard raises while the breach persists, so wire only the thresholds you intend to supervise.
* **QA review workload alerting** lives on the [QA workload surface](/guides/qa-workload-management): due-date windows and per-evaluator caps surface the backlog before it builds. The dashboard renders it; agents see only their own scores.
* **Webhook-health alerting** is on you: watch for dead-letter entries ([webhooks troubleshooting](/webhooks/troubleshooting-signature-failures)) and alert on your endpoint's failure rate.

## Putting it together

A healthy operator posture uses all four surfaces on purpose:

1. **Dashboards** ([Analytics](/api-reference/analytics), [Insights](/api-reference/insights)) answer trend questions, accepting the read-replica lag that makes them cheap.
2. **Moment-lookup surfaces** ([delivery log](/guides/delivery-log), [live tail](/api-reference/log-tail)) answer "what exactly happened to this thing."
3. **Durable history** ([webhooks](/webhooks/overview), [vCon export](/guides/conversation-export-vcon), [archive](/guides/conversation-archive)) backs anything retention or compliance touches.
4. **Alerts** are placed on the right rule surface ([Insights budget](/api-reference/insights), [wallboard alarm rules](/guides/wallboard-alarm-rules), [QA workload](/guides/qa-workload-management)), not rolled ad-hoc.

The failure modes this map exists to prevent: treating the events buffer as an audit log; polling dashboards as a delivery mechanism and missing the replica lag; treating sentinel statuses as delivery outcomes; and piling every alert onto one surface where it drowns.

## See also

* [Analytics API](/api-reference/analytics) — message metrics, scheduled reports, conversion goals
* [Insights API](/api-reference/insights) — LLM spend, ROI, containment, benchmarks
* [Events API](/api-reference/events) — the bounded recent-event buffer (not an audit log)
* [Live request log](/api-reference/log-tail) — SSE stream of tenant API requests
* [Delivery log](/guides/delivery-log) — single-message lookup
* [Webhooks overview](/webhooks/overview) — durable, retried event delivery to your endpoint
* [Conversation export (vCon)](/guides/conversation-export-vcon) — signed per-conversation export
* [Conversation archive](/guides/conversation-archive) — bulk CSV/JSON export
* [Wallboard alarm rules](/guides/wallboard-alarm-rules) — queue-metric alert thresholds
* [QA workload management](/guides/qa-workload-management) — review-backlog alerting
* [Operational sentinels](/concepts/operational-sentinels) — the statuses that are not delivery outcomes
* [Using Orby, the in-dashboard operator assistant](/guides/orby-in-dashboard) — ask the assistant instead of opening the raw surface