Agent telemetry contract

Perseval maps OpenTelemetry GenAI, OpenInference, and common producer attributes, then applies conservative deterministic detectors. An Error span remains visible even when the trace lacks enough facts for an actionable finding.

Identity attributes

Meaning	Attribute	Where	Example
Project route	`perseval.project.id`	resource	`checkout-agent`
Service	`service.name`	resource	`checkout-agent`
Build	`service.version`	resource	`git-a61c2e1`
Environment	`deployment.environment.name`	resource	`staging`
Session	`gen_ai.conversation.id`	resource or root span	`return-42`
Agent	`gen_ai.agent.id`	resource or agent span	`policy-agent`
Role	`agent.role`	agent span	`verifier`

Behavioral facts

Meaning	Preferred attribute	Valid examples
Operation	`agent.operation`	`submit_return`, `verify_release`
Requiredness	`agent.tool.requirement`	`required`, `optional`
Result	`agent.tool.status`	`succeeded`, `failed`, `timed_out`, `cancelled`
Result boolean	`tool.result.success`	`true`, `false`
Effect	`agent.operation.effect`	`read_only`, `mutating`, `verifying`, `compensating`, `escalating`
Retry safety	`agent.operation.retry_safety`	`idempotent`, `non_idempotent`, `unknown`
Attempt	`agent.tool.attempt`	`1`, `2`, `3`
State predicate	`agent.state.predicate`	`return_created`
State observation	`agent.state.observation`	`verified_changed`, `verified_unchanged`, `unverified`, `ambiguous`
Root outcome	`agent.final.status`	`completed`, `failed`

Equivalent tool.* and operation.* aliases are mapped when available, but using one consistent vocabulary makes producer behavior easier to audit.

Example tool span

{
  "name": "publisher.submit_return",
  "status": { "code": "STATUS_CODE_ERROR", "message": "deadline exceeded" },
  "attributes": [
    { "key": "gen_ai.tool.name", "value": { "stringValue": "returns_api" } },
    { "key": "agent.operation", "value": { "stringValue": "submit_return" } },
    { "key": "agent.tool.requirement", "value": { "stringValue": "required" } },
    { "key": "agent.tool.status", "value": { "stringValue": "timed_out" } },
    { "key": "agent.operation.effect", "value": { "stringValue": "mutating" } },
    { "key": "agent.operation.retry_safety", "value": { "stringValue": "unknown" } },
    { "key": "agent.state.predicate", "value": { "stringValue": "return_created" } },
    { "key": "agent.state.observation", "value": { "stringValue": "ambiguous" } }
  ]
}

That evidence supports an uncertain-mutation finding: the mutation may have succeeded despite the timeout. It does not justify claiming rollback or blindly retrying.

Error is not finding

An optional browser lookup may fail while a fallback succeeds. A required mutating call may time out after committing. A verifier can establish that an earlier error recovered. Treating all three as the same failure would create noisy groups and unsafe remediation advice.

Perseval therefore reports missing facts instead of inventing requiredness, mutation safety, or a root success claim. For an error-only run, open Full Trace, select the error span, and read the Finding inspector. It names the missing facts and points to Attributes.

Payload boundary

Do not put secrets in trace attributes. Prompt, message, reasoning, source-code, input, output, and tool-payload values become blob references; externalization limits automatic display but is not redaction. See Privacy and storage.