Revamp Observability section #640
Open
abhijaisrivastava15 wants to merge 7 commits intodevfrom
Open
Conversation
Pages rewritten with text matched to actual platform UI (Error Feed Demo project, Past 30D filter): - llm-tracing.mdx: 10 fresh screenshots; removed phantom Spans tab, fixed column list, restored Cost in span detail header. - session.mdx: 6 screenshots; corrected sessions grid columns (was 9 fictional, real is 6), fixed bulk-action list, rewrote replay flow to match the 3-step Create Scenarios dialog. - users.mdx: 5 screenshots; reduced 14-column claim to real 6, removed phantom bulk actions, documented per-user detail page. - evals.mdx: 2 screenshots; replaced multi-step wizard claim with the actual Create Task page (Spans/Traces/Sessions, Live Preview). - charts.mdx: 2 screenshots; fixed chart count (4 system + per-eval), switched description from dropdown to inline-button date range. - dashboard.mdx: 3 screenshots; documented dashboards list -> click to open -> +Add Widget flow. - alerts.mdx: 2 screenshots; renamed 'Create Alert' to '+ New Alert', fixed list columns. All screenshots are 3024x1614 retina captures via Puppeteer over CDP. Text written for engineer / PM / non-tech reader. Also adds the new 'Observability (Updated)' nav group in navigation.ts pointing at observe-two routes.
Voice Observability page rewritten against the live platform using a real voice project (Fast Food Order Agent_replay_agent_09_04_26 — Vapi inbound calls). 5 fresh Puppeteer screenshots captured: - voice-agent-definitions.png — Agent Definitions list with Voice Inbound / Voice Outbound / Chat agents and Vapi provider details. - voice-create-form.png — Create flow first step (3-step wizard: Basic Info -> Configuration -> Behaviour). - voice-projects-list.png — Tracing project list showing voice projects alongside text projects. - voice-tracing-overview.png — Voice project's call log table with voice-specific columns: Call Details, Status, Duration, Avg Latency, Turn Count, Tokens. - voice-call-detail.png — Call detail drawer with transcript, recording waveform, speaker filters, and the Call Analytics tab showing Talk Ratio, Latency Pipeline, and Cost Breakdown. Text fixes vs prior version: - Replaced single-form claim with the actual 3-step wizard. - Documented the full call-detail drawer (header chips, 4 tabs, analytics breakdown) — previous text only mentioned "transcript and recording URLs". - Updated provider list note (Vapi confirmed; Retell + others noted). - Added voice-specific column descriptions for the Tracing table.
LiveKit sets trace attributes that show up in the Tracing view but are not yet selectable as Filter or Breakdown options in Dashboard widgets. Verified the platform fix (PR #124, branch fix/th-4660-livekit-dashboard-attrs, 4 commits incl. af6b170 by Azain on 2026-04-28) is not merged into main. Adding the limitation note back to dashboard.mdx so users know to fall back to Tracing for LiveKit-specific filtering until the fix lands. Will be removed once PR #124 merges.
The new observe-two docs (rewrites + verified screenshots from earlier
commits on this branch) become the canonical /docs/observe/* docs.
The old hand-written /docs/observe/* pages are deleted.
Changes:
- Delete src/pages/docs/observe/ (the old pages and old manual-tracing).
- Rename src/pages/docs/observe-two/ -> src/pages/docs/observe/.
- Delete public/images/docs/observe/{1..5}.png, .webp (old assets).
- Rename public/images/docs/observe-two/ -> public/images/docs/observe/
(preserves all 36 verified screenshots taken on this branch).
- Update every internal reference inside the moved pages from
/docs/observe-two/ -> /docs/observe/ and /images/docs/observe-two/
-> /images/docs/observe/ (151 occurrences).
- src/lib/navigation.ts: remove the old "Observability" group; rename
the "Observability (Updated)" group to "Observability" and swap
its hrefs from /docs/observe-two/ to /docs/observe/.
Also fixes 3 external broken links that were already pointing at
nonexistent /docs/observe/ routes:
- src/pages/index.astro: /docs/observe/quickstart ->
/docs/observe/features/quickstart.
- src/pages/docs/simulation/features/voice-replay.mdx (x2):
/docs/observe/voice/set-up -> /docs/observe/features/voice.
- src/pages/docs/sdk/annotation-queues.mdx:
/docs/observe/features/annotation-queue-using-sdk ->
/docs/annotations/sdk/annotation-queue-using-sdk (the actual
location per navigation.ts).
Concept pages under /docs/tracing/concepts/ are referenced from the
new observe docs and are intentionally left untouched.
Verified: zero remaining "observe-two" references in src/ or public/.
…660) Incorporates the platform fix for TH-4660 / PR #124 into the docs. By the time these docs ship, the fix should be merged and live. Removes the "Known limitation (LiveKit users)" note added in 852fa89 and replaces it with positive guidance: - Filter section now explicitly says every span attribute visible in Tracing is filterable in Dashboard widgets, including LiveKit specific fields (room name, participant identity, custom). - Breakdown section reads similarly — group by any span attribute. Net effect: docs read as if LiveKit-set attributes Just Work as Filter and Breakdown options in dashboards.
The Overview page (/docs/observe) was still pointing at the old /images/observe_dashboard.png (a light-mode screenshot from the previous docs era). Swapped to /images/docs/observe/llm-tracing-overview.png — the dark-mode Tracing screenshot captured for the new Tracing page. Matches the rest of the rewritten observe docs visually.
…lign headings - Zoom-cropped 10 popup/dropdown screenshots so the modal is the subject rather than a tiny corner of a full dashboard view (date-range, filter, display, bulk-actions across llm-tracing/sessions/users) - Renamed top-level headings on all 8 observe feature pages to match the rest of the docs: 'What is this page?' -> 'About', and 'When would you use this?' -> 'When to use' Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
[TH-4627] Rewrites the Observability docs against the live platform. Every page was rewritten to match the actual UI, with 36 fresh replacing outdated assets. The rewritten docs, originally drafted under
/docs/observe-two/*, are now promoted to the canonical/docs/observe/*path, with old pages and assets removed.Pages rewritten
llm-tracing.mdx(10 screenshots)session.mdx(6)users.mdx(5)evals.mdx(2)charts.mdx(2)dashboard.mdx(3)+ Add Widgetflowalerts.mdx(2)Create Alert→+ New Alertvoice.mdx(5)Restructure
src/pages/docs/observe-two/→src/pages/docs/observe/public/images/docs/observe-two/→public/images/docs/observe/src/pages/docs/observe/pages and outdated PNG/WebP assets/docs/observe-two/and/images/docs/observe-two/src/lib/navigation.tsObservabilitygroupObservability (Updated)→Observability/docs/observe/links:index.astrovoice-replay.mdxannotation-queues.mdxLinear
Fixed TH-4627 — https://linear.app/futureagi/issue/TH-4627
Test plan
/docs/observe/*pages render correctlyObservabilitysection with the rewritten pages/images/docs/observe/grep -r "observe-two" src/ public/returns no results