Observability Overview

An agent you cannot observe cannot be operated. Velerion records every run as a trace, exposes metrics derived from those traces, and keeps both queryable long enough to be useful during an incident review rather than only during the incident.

What is recorded

Signal	Granularity	Retention
Traces	One per run, with a span per model call and tool call	30 days
Metrics	Pre-aggregated counters and histograms, 1-minute buckets	400 days
Logs	Whatever your tools write through ctx.logger	30 days
Usage	Token and request counts per agent, environment and model	400 days
Audit	Every mutating control-plane action	400 days

Traces are sampled in production and complete in dev. Sampling is head-based at the run level, so a sampled run is recorded whole — you never get a trace with holes in it.

The request ID ties it together

Every run returns an ID, surfaced as run.id in the SDK and as the x-velerion-request-id response header. That single value looks up the trace, the logs for that run and the matching audit log entry.

const run = await velerion.agents.run('support-triage', { input });
logger.info({ velerionRunId: run.id }, 'triage complete');

Put that ID in your own application logs. Without it, correlating a customer complaint with a specific run means guessing from timestamps.

Where to look first

Symptom	Start here
One run behaved oddly	velerion traces show <id> — read the tool calls in order
Latency regression after a deploy	Metrics, p95 by revision
Spend climbing	velerion usage --group-by agent
A tool is failing	Metrics, tool error rate, then a sampled trace
Answers went stale	Your own pipeline, not Velerion — see the RAG architecture

Caution

Traces contain prompts, tool arguments and model output. That is production data. Access is governed by the traces:read permission, which is not granted to viewer by default — keep it that way unless the role genuinely needs it.

Next steps

• Traces — the span model, and how to read one.
• Metrics & Alerts — what to alert on, and what to ignore.