Skip to content

Observability & diagnostics

Venturi runs as a dedicated tenant data plane (in your cloud when self-hosted, or in your contracted residency lane in SaaS mode), so you should never have to take its health on faith. Venturi self-reports: exposing its degradation state, freshness, coverage, and queue health where you read attribution, over the API, and in a form your own monitoring stack can ingest. This page is the operator’s guide to the signals Venturi emits and how to act on them.

The signals that matter

Signal What it answers
Degradation state Is attribution being produced normally, or on a fallback?
Connector freshness When did each source last sync successfully?
Index freshness How current are dashboard and API results?
Coverage What fraction of AI spend is being attributed?
Queue depth Is the processor keeping up with event volume?
Decision-time interceptor latency Is the decision-time path inside its budget?
Export status Did governed exports complete and get signed?

Degradation state

Every customer-visible attribution result carries a degradation state as part of its evidence, and the same signal is exposed over the API on each attribution record. This is how Venturi tells you whether a number was produced normally or by the heuristic-baseline fallback.

degradation_state Meaning What to do
none This result has no degraded condition. Stage origin distinguishes deterministic Stage A resolution, Stage B inference, and separate Stage C allocation. Inspect stage origin, evidence, and freshness; this marker alone does not establish chargeback eligibility.
degraded_serving The trained model is unavailable or missed its timeout; attribution is produced on the deterministic heuristic baseline of RAIL (Resource Attribution & Inference Layer) Stage B; see The attribution pipeline Results remain usable; treat newly-fallback attributions as provisional and review their evidence
disabled Stage B inference is turned off for the scope by configuration Ask your Admin to re-enable it if the change was unexpected
model_recalled The active model version was recalled; the prior validated model version served the result Nothing required; affected records are marked so you can review them

Examples on this page use https://<your-venturi-instance>. In SaaS mode, substitute https://api.venturi.systems; when self-hosted, substitute your own instance host. See Deployment modes.

Bash
# Read the degradation state on a specific attribution record
curl "https://<your-venturi-instance>/v1/attribution/attr_01HF8Z6Q4R2M7N3P9K5T1V8W0X" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

The degradation and freshness signals sit in the record’s interpretation evidence card (abridged here; the full shape is in the REST API reference):

JSON
{
  "id": "attr_01HF8Z6Q4R2M7N3P9K5T1V8W0X",
  "cost_usd": "12.40",
  "output_state": "strongly_inferred",
  "interpretation": {
    "stage_origin": "stage_b",
    "confidence": 0.91,
    "confidence_band": "chargeback_ready",
    "degradation_state": "none",
    "freshness": "fresh"
  }
}

interpretation.confidence is the operational confidence coper, capped at 0.95. Money, energy, and carbon values are decimal strings.

A fallback never hides itself

When the trained model is unavailable, attribution processing continues on the heuristic baseline and the result is marked degraded_serving; it is never silently presented as if the model produced it. Stage B runs in the asynchronous processor, off your request path, and the decision-time interceptor’s separate fail-open guarantee protects your AI traffic, so this degradation never reaches your traffic and stays fully visible to you. See Confidence & evidence.

Freshness and coverage

Freshness

Every attribution result carries a freshness state in its evidence card: fresh, index_stale, or source_stale. A stale view also shows the as-of timestamp of the data behind it. Two freshness objectives are instrumented and you can hold the platform to them:

  • Index freshness P99 ≤ 90 s: the lag from an invocation arriving to its appearing in the attribution index/API. Premium and Regulated also carry a 5-minute index-freshness SLA (see Commitments by support tier).
  • Reconciliation freshness ≤ 24 h: the window within which attributed cost is reconciled against authoritative provider billing.

Connector freshness is a separate, per-source signal: when each connector last synced successfully. A connector that has stopped syncing is the most common root cause of a coverage drop, so connector freshness is the first thing to check when attribution looks low. A freshness lag is also surfaced as a degraded state in-product, so a stale number is never presented as current.

Coverage

Coverage answers a different and equally important question: of the AI spend Venturi can see, how much is being attributed? Coverage is a first-class signal: a healthy serving plane with low coverage tells you a connector is missing or misconfigured, not that your costs dropped.

Bash
# Read the per-pathway coverage map (requires the attributions:read scope)
curl "https://<your-venturi-instance>/api/v1/coverage" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

GET /api/v1/coverage returns your per-pathway coverage map, including deployed capture layers, missing sources, and discovery-only pathways. See Coverage in the REST API reference.

When coverage drops, Venturi tells you why, never with a blank screen. An empty or suppressed view explains its cause: no connector configured, data not yet fresh, or rows withheld by cohort privacy suppression (minimum cohort of 5). A coverage-drop notification carries the affected scope and a deep link to resolve it. See Reporting & exports for the coverage report and Ingestion for connector setup.

Throughput and latency

Two operational signals tell you the pipeline is keeping pace:

  • Queue depth: whether the asynchronous processor is keeping up with event volume. Sustained growth indicates backpressure and usually precedes a freshness lag.
  • Decision-time interceptor latency: whether the fast index lookup is inside its 50 ms P99 end-to-end budget (15 ms internal). The separate asynchronous processor has a 100 ms P99 budget; Stage B has a 20 ms timeout inside it and falls back to the heuristic baseline on breach. Neither path slows or blocks customer traffic. See SLAs and SLOs.

Wiring Venturi into your monitoring stack

Venturi is built to be observed by the tools you already run, not only through its own UI. Authenticated diagnostic endpoints are read-only and tenant-scoped.

Tenant-scoped diagnostics

Authenticated diagnostic endpoints, such as the degradation and rate-limit reads below, are read-only and bound to the tenant of the calling credential. A request for another tenant returns 403 TENANT_MISMATCH; tenant activation does not complete until that negative test passes. The /healthz and /readyz probes are different: they are unauthenticated, return the same tenant-free response to every caller, and on the SaaS tier report the shared API host rather than your data plane (see Health endpoints).

Read degradation, freshness, coverage, and rate-limit headroom on a schedule and feed them into your existing dashboards and alerting.

Bash
# Live degradation classes for your tenant (feature, severity, since, user impact).
# Use an access token issued to your tenant; the response covers only that tenant.
curl "https://<your-venturi-instance>/api/v1/system/degradation" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

# Current rate-limit headroom for an API client (principal is required).
# The token needs the keys:manage scope.
curl "https://<your-venturi-instance>/api/v1/rate-limit?principal=$VENTURI_CLIENT_ID&route_class=default" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

principal is the OAuth client_id or API key ID whose bucket you read. See Reading your budget for every parameter and the response body.

Use webhooks to react to coverage drops (coverage.degraded), Stage B degraded transitions (degradation.state.changed), export completion (export.completed), connector health changes (connector.health.changed), and API key rotations (apikey.rotated): push, not poll.

Critical events route to in-app, email, Slack, Microsoft Teams, and signed webhook with consistent rules. Critical in-app, Slack, and Microsoft Teams notifications deliver at P95 ≤ 30 s, and a missed delivery is alarmed rather than dropped silently; email and signed-webhook notices carry no delivery-latency objective. Configure channels, severities, and quiet hours in Budgets & alerts.

Diagnosing common conditions

A diagnostic warning is not automatically a billing defect. The product labels which outputs are affected (chargeback, coverage, adoption, optimization, exports, or only freshness) so you can scope the impact precisely.

Observed conditions, their likely causes, and evidence to inspect:

For attribution degradation, read degradation_state; for index and source freshness, read freshness. The index-stale diagnostic also applies when results lag more than 90 seconds. For empty or suppressed views, the view’s own empty-state explanation provides the evidence.

Observation Cause Evidence
degraded_serving Trained model temporarily unavailable; baseline in use while model recovery is pending Status & incidents
index_stale Index materialization behind objective, or growing queue depth SLAs & SLOs
Coverage dropped for a scope Connector down, credential expired, or new uncaptured pathway Troubleshooting; event ingestion
A view is empty or partially suppressed No data yet, or cohort suppression (k=5) View explanation
source_stale A connector has not synced within its expected window In-product connector freshness; Troubleshooting guide
API returns 429 Rate limit reached Versioning & rate limits

What you do not have to monitor

You do not have to monitor whether a Venturi dependency behind the interceptor is blocking your AI traffic, because it cannot. The decision-time path is fail-open within a 50 ms P99 end-to-end budget, bounded by a cooperative timeout against a cumulative deadline; a failure behind the interceptor degrades your visibility into attribution, not your production inference. The exception is the endpoint your requests are sent to: with the drop-in proxy, monitor the proxy endpoint’s reachability from your application, or configure client-side failover to the provider’s direct base URL, as described in Proxy endpoint reachability.

Give feedback on this page

Sign in to send feedback. Opens in a new tab.

Copy page details 
Docs feedback: Observability & diagnostics
Page: https://docs.venturi.systems/operations/observability-and-diagnostics/