docs: update tracing

website/observability/tracing/feedback.md

@@ -0,0 +1,23 @@
+---
+title: Trace Feedback
+---
+
+import MediaPanel from "@site/src/components/docs-widgets/MediaPanel";
+
+# Trace Feedback
+
+Use Feedback to tie human judgment to a specific trace so you can validate fixes and catch regressions early. It turns "this felt wrong" into a trackable signal you can compare across runs.
+
+What to look at:
+
+- **History and source**: confirm the trace was rated and where it came from (app, API, model).
+- **Key and score**: keep signals consistent (for example, satisfaction) so you can compare runs.
+- **Comments**: capture short context that explains why the output was good or bad.
+
+<MediaPanel
+  src="https://cdn.voltagent.dev/docs/observability/tracing/feedback.gif"
+  alt="Trace feedback"
+  width={520}
+/>
+
+<br/>

website/observability/tracing/logs.md

@@ -0,0 +1,18 @@
+---
+title: Trace Logs
+---
+
+# Trace Logs
+
+Use Logs to review structured events tied to the trace and span context. This is the fastest way to inspect errors and metadata without opening each span.
+
+<video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
+
+  <source src="https://cdn.voltagent.dev/docs/observability/tracing/logs-2.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+<br/>
+<br/>
+
+Logs are best when you need a fast answer to "what happened and why." Start with errors, then use search or level filters to narrow down, and follow the trace/span context to the exact step.

website/observability/tracing/node-based.md

@@ -0,0 +1,15 @@
+---
+title: Node-Based View
+---
+
+# Node-Based View
+
+The node-based view shows the same trace as a visual flow. It helps you understand the overall path at a glance and see how agents, tools, memory, and model calls connect.
+
+Use this view when you want the big picture, then drill into a specific node for details.
+
+<video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
+
+  <source src="https://cdn.voltagent.dev/docs/observability/tracing/node-based.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>

website/observability/tracing/overview.md

@@ -4,70 +4,42 @@ title: Overview
 
 # VoltOps Tracing
 
-Tracing is the process of recording and visualizing the execution path of your AI applications in real-time. It shows you exactly what your AI agents are doing, which tools they're using, and how data flows through your system from start to finish.
+Tracing shows how a single user request runs from start to finish. As a developer, you use it to answer:
+
+- Why did the agent respond this way?
+- Which step failed?
+- Where did latency or cost spike?
 
 <video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
 
   <source src="https://cdn.voltagent.dev/docs/voltop-docs/voltops-observability.mp4" type="video/mp4" />
   Your browser does not support the video tag.
 </video>
 
-## Why Tracing Matters for LLM Applications
-
-<details>
-<summary>
-Understanding Complex AI Workflows
-</summary>
-
-Large Language Model applications often involve complex, multi-step processes that can be difficult to debug and optimize. Unlike traditional applications with predictable execution paths, LLM apps feature:
-
-- **Dynamic decision-making**: AI agents make context-dependent choices that vary between runs
-- **Multi-step reasoning**: Complex tasks are broken down into multiple sequential or parallel operations
-- **Tool integration**: AI agents interact with external APIs, databases, and services
-- **Non-deterministic behavior**: The same input can produce different execution paths
-
-</details>
-
-<details>
-<summary>
-Key Benefits of Tracing
-</summary>
-
-**Debug with Confidence**
-
-- Identify exactly where errors occur in your AI workflow
-- Understand why certain decisions were made by your AI agents
-- Track the flow of data through complex processing chains
-- Pinpoint performance bottlenecks in real-time
-
-**Monitor Performance**
-
-- Track response times for each component of your AI system
-- Monitor token usage and costs across different LLM calls
-- Identify slow operations that impact user experience
+<br/>
+<br/>
 
-**Optimize Your AI Applications**
+When you select a trace from the list, you can open the [Waterfall view](https://voltagent.dev/observability-docs/tracing/waterfall/) or the [Node-Based view](https://voltagent.dev/observability-docs/tracing/node-based/) and then dig into [Logs](https://voltagent.dev/observability-docs/tracing/logs/) and [Feedback](https://voltagent.dev/observability-docs/tracing/feedback/).
 
-- Analyze which tools and prompts perform best
-- Identify redundant or inefficient processing steps
-- Optimize prompt engineering based on actual execution data
-- Fine-tune your AI workflows for better performance
+## Trace Filters
 
-**Collaborate Effectively**
+Filters help you find the right trace fast.
 
-- Share detailed traces with team members for debugging
-- Document AI behavior patterns for future reference
-- Enable non-technical stakeholders to understand AI decision-making
-- Create reproducible test cases from real execution traces
+:::tip
+For example use:
 
-</details>
+- Status + Duration to see where a failure started,
+- Token usage + Cost to catch expensive runs, and
+- User ID + Conversation ID to inspect a specific user flow.
+:::
 
-### Common Use Cases
+![Trace filters overview](https://cdn.voltagent.dev/docs/observability/tracing/overview-trace-filters.gif)
 
-- **Agent Debugging**: When your AI agent produces unexpected results, tracing shows exactly what happened
-- **Performance Optimization**: Identify which LLM calls or tool executions are taking too long
-- **Cost Analysis**: Track token usage and API costs across your entire application
-- **Quality Assurance**: Verify that your AI workflows behave consistently across different scenarios
-- **Compliance**: Maintain audit trails of AI decision-making for regulatory requirements
+<br/>
 
-Tracing transforms the black box of AI applications into a transparent, observable system that you can understand, debug, and optimize with confidence.
+- **Status**: isolate failed or retry-heavy runs.
+- **Agent ID / Entity type**: narrow down which agent or step is involved.
+- **Token usage / Cost**: find expensive or abnormal runs.
+- **Duration**: spot slow traces and latency outliers.
+- **Feedback source / key**: review feedback by source.
+- **User ID / Conversation ID**: drill into one user journey.

website/observability/tracing/users.md

@@ -0,0 +1,50 @@
+---
+title: User Analytics
+---
+
+# User Analytics
+
+The Users page groups traces by user so you can see who is impacted and where issues concentrate. It helps you go from "something feels off" to a specific user, session, and trace.
+
+<video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
+
+  <source src="https://cdn.voltagent.dev/docs/observability/tracing/tracing-users.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+<br/>
+<br/>
+
+## Key Metrics
+
+Quick read of volume, success rate, latency, and cost over time. Use it to decide if the problem is quality, performance, or spend, and to link regressions to model switches.
+
+<img
+src="https://cdn.voltagent.dev/docs/observability/tracing/tracing-charts.gif"
+alt="Trace filters overview"
+style={{  maxWidth: "100%", borderRadius: "12px", display: "block", margin: "0 auto" }}
+/>
+
+<br/>
+
+## User Feedback
+
+Feedback turns user sentiment into signals you can track. Use it to confirm whether fixes improved the experience and to see which issues users feel most.
+
+<img
+src="https://cdn.voltagent.dev/docs/observability/tracing/tracing-feedback.gif"
+alt="Trace filters overview"
+style={{  maxWidth: "100%", borderRadius: "12px", display: "block", margin: "0 auto" }}
+/>
+
+<br/>
+
+Use the charts to see feedback volume, sentiment trends, score clusters, dominant feedback keys, and when users leave comments.
+
+## Conversations
+
+Conversations group traces by session so you can follow a user flow end to end.
+
+Use the cards (status, time range, model, cost) to pick the most suspicious session, then filter traces to that path.
+
+![conversation](https://cdn.voltagent.dev/docs/observability/tracing/tracing-conversation-2.png)

website/observability/tracing/waterfall.md

@@ -0,0 +1,25 @@
+---
+title: Waterfall View
+---
+
+# Waterfall View
+
+Use Waterfall to understand timing and execution order. It shows spans as a hierarchy so you can see where time is spent, how retries fan out, and which step failed first.
+
+<video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
+
+  <source src="https://cdn.voltagent.dev/docs/observability/tracing/waterfall.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+<br/>
+<br/>
+
+Use Waterfall when you need the root cause of a failure or a latency spike. The details panel gives the context you need to confirm tool usage, memory behavior, and LLM settings without digging through logs.
+
+Key signals to check:
+
+- **Failure path**: error badges + child spans to see the first break and its causes.
+- **Latency hotspots**: duration bars and timing to find the slowest steps.
+- **Model context**: input/output and UI vs model messages to verify prompts and responses.
+- **Configuration**: LLM config, memory config, and knowledge base usage for this span.

website/sidebarsObservability.ts

@@ -28,7 +28,14 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Tracing",
-      items: ["tracing/overview", "tracing/concept"],
+      items: [
+        "tracing/overview",
+        "tracing/waterfall",
+        "tracing/node-based",
+        "tracing/logs",
+        "tracing/feedback",
+        "tracing/users",
+      ],
     },
     {
       type: "doc",

website/src/components/docs-widgets/MediaPanel.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+
+type MediaPanelProps = {
+  src: string;
+  alt: string;
+  width?: number | string;
+};
+
+const MediaPanel = ({ src, alt, width = "100%" }: MediaPanelProps) => (
+  <div className="my-6 w-full">
+    <div
+      className="w-full rounded-2xl p-5"
+      style={{
+        background: "linear-gradient(180deg, #15161a 0%, #0f1013 100%)",
+        border: "1px solid #2b2d2f",
+        boxShadow: "0 20px 40px rgba(0,0,0,0.35)",
+      }}
+    >
+      <img
+        src={src}
+        alt={alt}
+        style={{ width: typeof width === "number" ? `${width}px` : width }}
+        className="mx-auto block max-w-full rounded-xl"
+      />
+    </div>
+  </div>
+);
+
+export default MediaPanel;