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

# AI observability

> Trace generations, tool calls, sessions, and users across your AI workflows in Squasher.

Squasher AI observability gives you an observation-first view of how your agents, chat workflows, and LLM requests behave in production.

Use it when you need to answer questions like:

* Which prompts are expensive?
* Which model calls are slow?
* Which tool calls are failing?
* What happened in this chat session or agent run?
* Which users or sessions are driving the most AI traffic?

## What Squasher captures

Each AI observation row can include:

* Session and user identity
* Trace and parent-child relationships
* Model and provider (with the AI SDK's `.chat` / `.responses` suffix stripped)
* Prompt, completion, total, **reasoning, and cached input** tokens
* Assistant **text output**, plus provider-supplied reasoning text only when the SDK caller explicitly opts in
* Input messages and tool call input/output when privacy mode is disabled
* OpenTelemetry `gen_ai.system_instructions`, input/output messages, and
  OpenInference `input.value` / `output.value` content when emitters opt in
* **Cost in USD** — captured automatically when the provider exposes it (e.g. OpenRouter's `providerMetadata.openrouter.usage.cost`), sent explicitly via the SDK / raw ingest, or computed server-side from the token counts × a maintained model rate table when neither path is available
* Latency, completion start time
* Environment, release, version, and metadata attributes

The Agent SDK's AI SDK integration sends this data directly from `streamText()` callbacks. Sessions, spans, generations, tool calls, token counts, cached-input tokens, reasoning tokens, cost, and selected prompt/output payloads arrive as structured observations instead of log text.

Local redacted files or NDJSON written during development are useful for debugging an agent run on your machine. They complement the remote Squasher dataset, but the dashboard and APIs use Squasher's ingested telemetry as the production system of record.

## Pages in the dashboard

### Overview

See aggregate AI activity for the selected time range: request volume, prompt/completion/cached/reasoning token totals, spend, prompt-cache hit rate, average and p95 latency, and error rate. Switch the trend chart between requests, errors, latency, cost, and tokens, and read the model, provider, tool-call, session, and user breakdowns to see where volume and spend are going.

Hosted fixer workflows also expose dispatch metrics, provider/source breakdowns, requester breakdowns, and webhook-delivery history through the public AI API and the built-in **AI Fixer Operations** dashboard template.

### Requests

Search and filter individual generations, tool calls, agent spans, and retrievals. Filter by observation type, model, provider, status, tool name, session, and user, or search prompt text, model output, tool names, and propagated metadata. Every row shows tokens, cost, latency, and status, and opens the full request record with recorded input, output, attributes, tags, and links to its trace, session, and user.

### Traces

Open a trace to see its spans as a nested execution tree: agent spans, generations, tool calls, and retrievals, each with its type, model or tool name, tokens, cost, latency, and status. Select a span to inspect its details and jump to the full request record.

### Sessions

Group related AI activity by chat thread or run. Use the session timeline to follow a single user journey across traces and tool calls.

### Users

See which users are driving traffic, cost, and sessions. Drill from user -> session -> request -> trace.

### Feedback

See user ratings, thumbs, reviewer annotations, and automated evaluation scores in
one quality view. The dashboard shows positive-feedback rate, average numeric
score, score breakdowns, and recent comments, with links back to the exact trace
or generation that was judged.

Use `captureFeedback()` with a stable `feedbackId` to make end-user feedback
editable. A later call with the same ID replaces the visible value; sending
`deleted: true` removes it from current analytics while preserving append-only
telemetry ingestion.

### Evaluation and training datasets

Scores from users, human reviewers, and automated judges stay attached to the
exact trace and generation they evaluate. Export bounded examples through the
Agent Observations API or `squasher agent-observations export` for offline
evaluation, supervised fine-tuning, or preference/RL workflows.

Raw dataset export requires the dedicated `ai:export` API-key scope. Identity
and arbitrary metadata are excluded by default and must be requested
explicitly.

Use `squasher agent-observations quality --fail-under 100 --min-observations <expected-volume>` in CI to block instrumentation releases
that lose trace linkage, prompts, outputs, model/provider attribution, token
usage, or cost evidence. Empty windows and invalid token totals fail the gate.
Add `--min-scored-observations` and `--min-scores` to prove feedback and
evaluation signals are still reaching Squasher.

## How to send data

You have three main paths:

1. **Agent SDK**: use [`@squasher-ai/agent`](/sdks/agent) for agent backends and server-side AI workflows. Wraps the Vercel AI SDK with a single set of callbacks; cost and usage flow automatically, while reasoning text is opt-in and privacy mode suppresses content-bearing fields.
2. **Direct HTTP ingest (no SDK)**: POST a Langfuse-compatible batch to `POST /v1/ai/ingest/:projectId` from any language or runtime. See the [worked curl example](/integrations/openrouter#direct-http-ingest-no-sdk).
3. **OpenTelemetry**: emit OTLP spans with `gen_ai.*` attributes and let Squasher classify them into generations, tool calls, and agent sessions.

For non-agent server errors, the Node and Edge SDKs can attach actionable attributes such as `error.why`, `error.fix`, `error.link`, and `error.status`. Those attributes make related failures easier to correlate with AI workflow incidents and give AI triage better input when an error group is created.

## What counts toward usage

Squasher meters **completed generations** as AI requests for billing and quota purposes. Tool calls and agent/session spans are stored and queryable, but they are not the primary metered unit.

Free plans hard-cap AI request volume. Once the monthly AI request quota is exhausted, Squasher drops additional AI observations for that period instead of ingesting them.

Paid plans include monthly AI request quotas and continue ingesting beyond the included amount. Any completed generations above the included quota are recorded as overage usage for billing. AI request quotas reset every month, and unused volume does not roll into the next period.

## Good fit

* Internal copilots and support bots
* Multi-step agent workflows with tool use
* Customer chat assistants
* OpenRouter- or OpenAI-compatible inference traffic
* Vercel AI SDK apps

## Next steps

* Follow the [Agent SDK guide](/sdks/agent)
* Follow the [OpenRouter integration guide](/integrations/openrouter)
* Query the [Agent Observations API](/api-reference/agent-observations)
* Export a score-filtered evaluation or training dataset from the
  [Agent Observations API](/api-reference/agent-observations#export-an-evaluation-or-training-dataset)
* Create an **AI Fixer Operations** dashboard from the dashboard templates gallery to monitor hosted fixer dispatches, tool calls, and completion trends

## Agent handoff

Use this prompt when another agent needs to instrument or inspect AI workflows:

```text theme={null}
Add or inspect Squasher AI observability for project <project_id>. If editing code, use @squasher-ai/agent and privacyMode when prompts, model output, reasoning, or tool payloads should stay private. Leave reasoning capture disabled unless explicitly required. If querying data, start with Agent Observations filters for time range, session_id, trace_id, agent_id, workflow_id, model, tool_name, or q.
```

For live data, use `squasher agent-observations ...`, the [Agent Observations API](/api-reference/agent-observations), or MCP `search("agentObservations")` followed by `execute`.