Data expectations: what each page needs

Provantix verifies and stores whatever arrives, and it also watches for the gap between what you connected and what your telemetry actually delivers. When a page has nothing to show, the cause is almost always one of the inputs on this page. Data-health findings in the app surface each gap automatically; this page is the reference for fixing them.

The one-line mental model

  • Records and Investigate need batches. Fed by the SDK or direct HTTP.
  • Agents and attribution need agents registered and records carrying agent_hint.vendor + agent_hint.vendor_agent_id.
  • Candidates need telemetry for non-human principals you have not claimed as agents.
  • Coverage needs attested pairs: which systems each agent is allowed to touch.
  • Findings need the signal fields below, otherwise a finding reads as "all clear" when it should read as "no data".

Records and Investigate

Any sealed record from a registered emitter. If these are empty: the emitter is not shipping. Check the emitter process, its spool directory, and the path to POST /v1/batches. The app flags a silent emitter after 6 hours, or after 24 hours for one that never shipped.

Agents and attribution

Two conditions, both required:

  1. The agent exists in the inventory (display_name, vendor, vendor_agent_id).
  2. Records carry matching agent_hint.vendor and agent_hint.vendor_agent_id.

The match is exact on both fields. A record whose hint matches nothing lands as unattributed and shows in Investigate with a low-confidence badge, not on an agent.

Candidates (shadow-agent discovery)

A principal appears as a candidate automatically when a record shows a non-human principal that has no agent mapping and no vendor_agent_id hint. If Candidates is empty while records flow, your telemetry only covers principals you already claimed. To activate discovery, stream records for every non-human principal in the environment: helper scripts, cron jobs, service accounts, legacy bots. Anything unmapped and agent-like surfaces here for review.

Coverage

Coverage compares observed activity against attested pairs (agent + system, state include or exclude). Attest each system an agent is allowed to touch from the Coverage page, where every pair seen in the last 30 days that nobody attested is listed with an attest button, or:

POST /v1/pairs
{ "agent_id": "agt_…", "system": "erp", "state": "include", "reason": "registered agent surface" }

With no attested pairs, Coverage cannot distinguish expected from unexpected activity and stays empty. After attestation, activity on unattested systems is listed under "Observed, not attested" on the Coverage page.

Each attested pair is judged on the evidence available for it. A pair is independently observed when a destination or identity connector for that system is connected. That describes where the pair's evidence comes from. It does not mean results were confirmed: only actions in a reconciled scope have a destination-confirmed state, and the product says which. A pair is self-reported when the only evidence is the agent's own telemetry (the SDK emitter or the hosted OTLP intake) and that telemetry attributed activity on the system in the window. Both count as covered; the Coverage page shows the split, because an auditor will ask which pairs rest on the agent's own word and which on a source the agent does not control.

Findings (risk signals)

The findings engine runs on a schedule, but each finding family needs its input. If the input has never been observed, the app raises a data-health finding instead of staying silently empty:

Finding family Required input How to send it
Aged credential ext.credential_age_days on any record for the principal one numeric field
Shared credential login actions with ext.interactive: true for principals that also act as agents occasional login events alongside agent activity
Reach mismatch / standing admin grant actions with ext.permission and a target_system grant events when permissions change
Unowned agent Agents with no owner set set owners in the app
Inactive agent Agents with no recent records resolves as activity flows

All three signal fields live in the record's ext object, which the SDK passes through (redacted) as-is:

emitter.emitAAR({
  // …fields as usual…
  ext: { credential_age_days: 214 },
});

Home

Home aggregates all of the above. It fills in as soon as records, pairs, and findings exist; there is nothing to configure on Home itself.

Model quality and coverage

Charts that show latency, tokens or failure rate describe only the records that carry those fields. The Settings → Data coverage card states, per field, what fraction of the last 30 days of evidence actually carries it — a latency chart drawn over 40% of calls is a chart of that 40%.

Which fields are optional

All metric fields are emitter-reported, so every one can be absent:

Field Set when Absent means
Model, tokens, latency The action is a model call and the instrumentation reports them Not a model call, or the emitter does not report usage/timing
Tool name, target The action is a tool call and the instrumentation names it Not a tool call, or unnamed tool surface
Input/output summaries The SDK's redaction layer captured them Instrumentation without the redaction layer, or summaries disabled
External recipient The action is a send with a declared recipient Not a send, or recipient not declared
Outcome The span carries a status Status not reported (older instrumentations)

A gap is a property of the telemetry, not of the agent's behaviour: it says what your instrumentation does not report, not what your agents did not do. Data-health findings flag silent emitters and batch gaps; the coverage card flags field-level sparseness. Close a gap by upgrading the emitter (the OTel exporter and current SDK report all of the above), not by re-reading the same records.

Cost is an estimate: it is computed at ingest from the token counts the emitter reported and the prices in your own price table, and an edit to a price restates the estimates of the records it priced. Nothing reconciles it against the provider's billing, so treat cost figures as directional, not invoice-grade.

What "outcome" means. success means only that the call completed without raising an error; failure means the call raised or returned an error. Neither says anything about whether the task itself succeeded — an agent call that returns cleanly after doing the wrong thing is still success. Where outcome matters, read it next to the target, the arguments summary and any joined destination record rather than on its own.

If a page is still blank after the matching input arrived

  • Records are queryable within seconds of a batch landing; findings and coverage recompute on the scheduler's next run (up to 6 hours). Run the check manually from Findings if you do not want to wait.
  • Attribution needs the exact vendor and vendor_agent_id match; a typo sends the record to unattributed instead of the agent.