---
title: "Observability"
description: "How to use Norcaster traces, citations, run history, node outputs, latency, cost, and errors to debug production AI behavior."
canonical: https://www.norcaster.com/docs/observability
---
<!-- Generated at build time from the rendered page by portal/scripts/generate-llms.mjs. The page is the source of truth; edit it, not this file. -->

Production visibility

# Observability: traces, citations, and run history

Norcaster records the execution path for AI requests so you can debug production behavior without guessing: what ran, what was blocked, what reached the provider, which sources were used, and where time or cost went.

## Run history

Every execution with status, request ID, deployment/workflow, model/provider, latency, cost estimate, and error state.

## Traces

A timeline of gateway, workflow, retrieval, model, agent, function, policy, and citation events.

## Node outputs

Workflow node inputs and outputs, including MCP results, redaction summaries, model requests, agent steps, and function responses.

## Citations

Retrieved chunks, source names, document IDs, scores, and citation metadata for RAG and answer\_with\_citations flows.

## Errors

Provider failures, policy blocks, validation issues, timeouts, retries, and fallback behavior.

## Set up useful run history

1. Run traffic through a Norcaster deployment or workflow instead of calling the provider directly.
2. Use stable request IDs from your app so production incidents can be searched later.
3. Keep prompt\_field, result\_field, and node names meaningful so traces are readable.
4. For RAG, use retrieval or answer\_with\_citations so citations and retrieval events are recorded.
5. For agents and tools, configure function names clearly so agent\_steps explain what happened.
6. Review Observability after test runs before sending production traffic.

## Fields to inspect first

### trace\_id

Correlates spans and node executions for one request path.

### request\_id

Use this to connect your app logs to Norcaster run history.

### status

Shows running, completed, failed, blocked, or waiting approval states.

### latency\_ms

Helps identify slow provider calls, retrieval, tools, or agent loops.

### cost\_estimate

Shows compute, token, retrieval, and total estimated cost where available.

### model\_request

The provider payload after workflow transforms, redaction, and policy decisions.

### agent\_steps

Each native tool-calling iteration, requested tool, function result, and final answer.

### citations

Document/chunk evidence used for grounded answers.

## Debugging playbooks

### A workflow failed

1. Open Dashboard -> Observability and search by run ID, request ID, workflow, or deployment.
2. Check the failed node and error category first: validation, policy block, provider error, timeout, or tool failure.
3. Inspect the node input and output payloads around the failure.
4. If retry or fallback ran, compare retry\_count and fallback\_node\_id behavior.

### Claude or another model did not receive expected data

1. Open the workflow run and find the model node.
2. Inspect model\_request.messages or agent\_request.messages.
3. Compare that payload with upstream mcp\_input, retrieval, transform, or redact\_text outputs.
4. Fix the prompt\_field if the model is reading the wrong field.

### A RAG answer has weak or missing citations

1. Inspect retrieval candidates, scores, source\_name, source\_url, and chunk metadata.
2. Check top\_k, min\_score, filters, and rerank output.
3. Confirm answer\_with\_citations received retrieval.candidates.
4. Add eval questions once you have a stable set of expected answers.

### A privacy or policy issue was reported

1. Check enforcement events and policy decisions for the request.
2. Inspect redaction\_summary before the model or agent node.
3. Open model\_request.messages or agent\_request.messages to prove what reached the provider.
4. Export audit evidence if the incident needs compliance review.

### An agent or tool call is slow

1. Open agent\_steps and compare each model/tool iteration.
2. Check function\_request and function\_response for slow external endpoints.
3. Review max\_iterations, timeout\_ms, retry policy, and budget gates.
4. Move expensive tools behind approval, router, or condition nodes if needed.

## What observability does not replace

Observability shows what happened. Boundary enforcement decides what is allowed to happen. Use traces with schema validation, guardrails, budgets, redaction, and evals for production control.