chore(claude): require page stories with frontend UI changes (#13231)

#### Description

- Add `.claude/rules/storybook.md`, scoped to `frontend/src/**/*.tsx`: a
UI change lands with its page story created or updated through the
`signoz-page-story` skill, with the opt-outs spelled out.
- Unwrap the prose in `signoz-page-story` and `sbshot-visual-diff` so
each paragraph and bullet is one line, like the rules files. Words and
code blocks are unchanged.

.claude/rules/storybook.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "frontend/src/**/*.tsx"
+---
+
+# Storybook
+
+Page stories are written with the `signoz-page-story` skill ([`.claude/skills/signoz-page-story/SKILL.md`](../skills/signoz-page-story/SKILL.md)); the API surface is [`frontend/src/storybook/README.md`](../../frontend/src/storybook/README.md).
+
+- **A UI change lands with its story.** Any change that alters what a page renders — a new page, a new state, a new branch, a changed layout — updates the story of every page that renders it, or creates one where the page has none. Go through the `signoz-page-story` skill; never hand-write a page story outside it.
+- **New page, new story. New state, new control or variant.** The skill decides which: a control on a response, a variant worth linking to, or a `play` story for a state only a click reaches.
+- **A shared component is covered through its pages.** A change under `components/` or `container/` with no story of its own updates the stories of the pages that render it.
+- **Already covered, say so.** When the existing story and its controls already reach the changed state, no story edit is needed; state that in the PR description.
+- **Opt out only when there is no visual diff.** Skip stories only when the change renders nothing differently: types, api clients, hooks with no UI branch, tests. Deleting a page deletes its stories.
+- **Prove it with a visual diff when asked.** Before/after screenshots and "did this touch other screens" go through `sbshot-visual-diff`, which can only show what a story renders.

.claude/skills/sbshot-visual-diff/SKILL.md

@@ -5,15 +5,9 @@ description: Shoot Storybook stories with sbshot at two git refs and produce a d
 
 # sbshot visual diffs
 
-`npx -y github:SigNoz/sbshot` shoots Storybook stories and pixel-diffs two runs.
-Use it. Do not hand-roll a Playwright screenshot loop or a canvas pixel-compare:
-sbshot already handles story selection, themes, settling, retries, diffing,
-tagging, a viewer and a static export, and its runs are the format the rest of
-the team can open.
+`npx -y github:SigNoz/sbshot` shoots Storybook stories and pixel-diffs two runs. Use it. Do not hand-roll a Playwright screenshot loop or a canvas pixel-compare: sbshot already handles story selection, themes, settling, retries, diffing, tagging, a viewer and a static export, and its runs are the format the rest of the team can open.
 
-sbshot is not installed by any package. It is run through `npx`, so nothing it
-knows travels into this repo on its own. This file is where that knowledge
-lives.
+sbshot is not installed by any package. It is run through `npx`, so nothing it knows travels into this repo on its own. This file is where that knowledge lives.
 
 ## The shape of a run
 
@@ -24,58 +18,31 @@ tag <diff> <tag> <story-id>...           # what the reviewer should look at
 export <diff> --out <dir>                # a static site, hostable
 ```
 
-`<storybook>` is a running dev server (`http://localhost:6006`), a build
-directory holding `index.json`, or a project directory with `.storybook/`. The
-frontend has **no `build-storybook` script**, only `storybook dev -p 6006`, so
-point `capture` at a dev server.
+`<storybook>` is a running dev server (`http://localhost:6006`), a build directory holding `index.json`, or a project directory with `.storybook/`. The frontend has **no `build-storybook` script**, only `storybook dev -p 6006`, so point `capture` at a dev server.
 
 ## Cover the change with stories first
 
-**A diff can only show what a story renders.** A screen, state or variant with no
-story is invisible to sbshot: it produces no pair, so it reads as "nothing
-changed" rather than "never looked at". This is the failure mode that makes a
-clean-looking diff worthless.
+**A diff can only show what a story renders.** A screen, state or variant with no story is invisible to sbshot: it produces no pair, so it reads as "nothing changed" rather than "never looked at". This is the failure mode that makes a clean-looking diff worthless.
 
-Before capturing, list the screens and states the change touches and check each
-has a story. For anything missing, write it first — the `signoz-page-story`
-skill covers how. New states reached only by an interaction need a `play`
-function, or the capture shoots the page at rest and the state never appears.
+Before capturing, list the screens and states the change touches and check each has a story. For anything missing, write it first — the `signoz-page-story` skill covers how. New states reached only by an interaction need a `play` function, or the capture shoots the page at rest and the state never appears.
 
-Then confirm it worked: the two runs' story counts should differ by exactly the
-stories the change adds. A new screen that produced no new story id is a screen
-nobody is reviewing. Say the count in the summary, so a reader can tell coverage
-from silence.
+Then confirm it worked: the two runs' story counts should differ by exactly the stories the change adds. A new screen that produced no new story id is a screen nobody is reviewing. Say the count in the summary, so a reader can tell coverage from silence.
 
 ## Rules that are not optional
 
-**One freshly started Storybook per ref.** Never start one server and switch git
-branches under it. Vite's HMR reloads the page, but some modules do not
-re-initialise, so the shot differs silently from a clean boot and the difference
-looks like a real change. Settle time does not fix this and is not the variable.
-Use one worktree and one port per ref, and stop each server before the next.
+**One freshly started Storybook per ref.** Never start one server and switch git branches under it. Vite's HMR reloads the page, but some modules do not re-initialise, so the shot differs silently from a clean boot and the difference looks like a real change. Settle time does not fix this and is not the variable. Use one worktree and one port per ref, and stop each server before the next.
 
-**Capture both themes: `--theme dark,light`.** Without it sbshot shoots the
-story's own default and everything lands in a single `default/` folder, so every
-regression in the other theme is invisible. Themes double the shot count, so
-scope with `--stories` or `--title`, never by dropping a theme.
+**Capture both themes: `--theme dark,light`.** Without it sbshot shoots the story's own default and everything lands in a single `default/` folder, so every regression in the other theme is invisible. Themes double the shot count, so scope with `--stories` or `--title`, never by dropping a theme.
 
-**Baseline is the merge-base, not `origin/main`.** `git merge-base origin/main
-<branch>`. Against a moved main, every commit main gained since the branch's base
-shows up reversed, as though the branch reverted it.
+**Baseline is the merge-base, not `origin/main`.** `git merge-base origin/main <branch>`. Against a moved main, every commit main gained since the branch's base shows up reversed, as though the branch reverted it.
 
-**The percentage sorts the list, it does not tell you what matters.** A dialog
-that dims the page scores high for a one-line change, and a whole new form
-section can score low. Open the shots and say what changed on each screen. The
-biggest number is usually the least interesting one.
+**The percentage sorts the list, it does not tell you what matters.** A dialog that dims the page scores high for a one-line change, and a whole new form section can score low. Open the shots and say what changed on each screen. The biggest number is usually the least interesting one.
 
-**If you cannot explain a pair, assume the capture is at fault, not the code.**
-Open it, crop both sides and compare them before calling it noise. A pixel count
-and a good guess are not evidence.
+**If you cannot explain a pair, assume the capture is at fault, not the code.** Open it, crop both sides and compare them before calling it noise. A pixel count and a good guess are not evidence.
 
 ## Noise, and the floor that proves it
 
-The same story does not always render identically twice. Pairs often move for
-reasons that have nothing to do with the change:
+The same story does not always render identically twice. Pairs often move for reasons that have nothing to do with the change:
 
 - a focus ring left on whatever a `play` function clicked last
 - a scrollbar appearing, or its thumb resting a few pixels off
@@ -86,9 +53,7 @@ reasons that have nothing to do with the change:
 - hover or active styling from where the pointer happened to rest
 - a late-loading font or image shifting a line of text
 
-Do not argue about these one at a time. **Measure them**: shoot the same commit
-twice and diff those two runs against each other. Anything that moves there moved
-for no reason, so it is noise.
+Do not argue about these one at a time. **Measure them**: shoot the same commit twice and diff those two runs against each other. Anything that moves there moved for no reason, so it is noise.
 
 ```
 capture <storybook> --name-run noise-a
@@ -97,76 +62,35 @@ diff noise-a noise-b --name-diff noise
 diff <baseline> <after> --noise noise      # marks the movers flaky
 ```
 
-**The noise run has to cover the same stories as the real diff.** Do not scope it
-down to the few pairs that moved, however tempting that is. `--noise` marks a
-pair flaky when the noise diff does not show it as unchanged, so every story the
-noise run leaves out is marked flaky too, including the new screens the reviewer
-is there to look at. Shooting two narrow runs and diffing those against each
-other has the same problem. Either shoot the full set twice, or skip `--noise`
-and explain the few movers by hand.
+**The noise run has to cover the same stories as the real diff.** Do not scope it down to the few pairs that moved, however tempting that is. `--noise` marks a pair flaky when the noise diff does not show it as unchanged, so every story the noise run leaves out is marked flaky too, including the new screens the reviewer is there to look at. Shooting two narrow runs and diffing those against each other has the same problem. Either shoot the full set twice, or skip `--noise` and explain the few movers by hand.
 
-**`--noise` ignores how far a pair moved.** A pair is marked flaky when the
-noise diff does not show it as unchanged, so a 70-pixel flicker in the noise run
-hides a real 8% change in the real one. Compare the two numbers before trusting
-the mark. When most of the flaky marks are hiding real changes, run the diff
-without `--noise` and tag the genuinely noisy pairs by hand instead, so nothing
-real is filtered out of the reviewer's view.
+**`--noise` ignores how far a pair moved.** A pair is marked flaky when the noise diff does not show it as unchanged, so a 70-pixel flicker in the noise run hides a real 8% change in the real one. Compare the two numbers before trusting the mark. When most of the flaky marks are hiding real changes, run the diff without `--noise` and tag the genuinely noisy pairs by hand instead, so nothing real is filtered out of the reviewer's view.
 
-That is the trade: a second full capture costs about as long as the first, so on
-a small diff it is often quicker to crop the two or three movers and say what
-each one is. Use `--noise` when the diff is large, or when wiring `--fail-over`
-into CI, where something has to decide without a person looking.
+That is the trade: a second full capture costs about as long as the first, so on a small diff it is often quicker to crop the two or three movers and say what each one is. Use `--noise` when the diff is large, or when wiring `--fail-over` into CI, where something has to decide without a person looking.
 
-If a pair is flaky every run and the state it captures matters, fix the story
-rather than living with it: blur what the `play` clicked, freeze the clock, or
-assert the state instead of shooting it.
+If a pair is flaky every run and the state it captures matters, fix the story rather than living with it: blur what the `play` clicked, freeze the clock, or assert the state instead of shooting it.
 
 ## Making it readable for a reviewer
 
 A reviewer cannot open `localhost`, so `sbshot ui` is for you, not for them.
 
-1. `tag` the pairs that matter, with `--note` saying why. The viewer filters by
-   tag, so the reviewer lands on the real changes instead of scrolling past
-   noise that scored higher.
-2. `export <diff> --out <dir>`. It writes a static site carrying only the pairs
-   that are not identical, converted to WebP, so a large diff stays small.
-3. Host it. A Claude artifact works: publish the export's files and give the
-   reviewer the link. `index.html` is reserved for the artifact's own page, so
-   publish sbshot's entry as `viewer.html` and link to
-   `viewer.html#/job/diff/<diff>`.
+1. `tag` the pairs that matter, with `--note` saying why. The viewer filters by tag, so the reviewer lands on the real changes instead of scrolling past noise that scored higher.
+2. `export <diff> --out <dir>`. It writes a static site carrying only the pairs that are not identical, converted to WebP, so a large diff stays small.
+3. Host it. A Claude artifact works: publish the export's files and give the reviewer the link. `index.html` is reserved for the artifact's own page, so publish sbshot's entry as `viewer.html` and link to `viewer.html#/job/diff/<diff>`.
 4. Put the link in the PR body under **Screenshots / Screen Recordings**.
 
-Say the numbers plainly: how many screens changed, how many are new, how many are
-pixel-identical, how many are flaky. The count of unchanged screens is often the
-most useful claim in the diff, because it is the one a reviewer cannot check by
-eye.
+Say the numbers plainly: how many screens changed, how many are new, how many are pixel-identical, how many are flaky. The count of unchanged screens is often the most useful claim in the diff, because it is the one a reviewer cannot check by eye.
 
 ## Operational traps
 
-- A full capture is hundreds of shots. Scope with `--title "Pages/Alerts"` or
-  `--stories "a,b,c"` (substring match on id or Title/Name, repeatable).
-- **On macOS a capture can pin itself to one story at a time.** sbshot picks how
-  many to shoot at once by sampling free memory, and off Linux it reads
-  `os.freemem()`, which counts only truly free pages. macOS parks almost
-  everything in "inactive" instead, which is reclaimable on demand, so the
-  sampler can read ~100 MB on a 25 GB machine and shrink to one forever.
-  `--jobs` does not help: it is only an upper cap. Check `parallelism` in
-  `<run>/events.ndjson`; if it sits at 1 while `vm_stat` shows gigabytes
-  inactive, that is this. A 124-shot run takes about 90 minutes pinned and about
-  6 minutes at four at a time, so it is worth spotting before a long capture.
-- A fresh worktree cannot build Storybook: `i18n-translations-hash.json` is
-  gitignored and generated. Run `node ./i18-generate-hash.cjs` in
-  `<worktree>/frontend`, and symlink `node_modules` from the main checkout.
-- `pnpm test:storybook` starts its own server on 6006 and hangs silently if
-  something already holds that port. Free it first.
-- ImageMagick on macOS may have no default font, so `--mode green-parallel` fails
-  with ``unable to read font `' ``. Map Helvetica to a real file in
-  `~/.config/ImageMagick/type.xml`.
-- `sbshot link <dir> <name>` adds a run from elsewhere into the workspace, but it
-  symlinks. Keep the source directory alive until you have exported.
+- A full capture is hundreds of shots. Scope with `--title "Pages/Alerts"` or `--stories "a,b,c"` (substring match on id or Title/Name, repeatable).
+- **On macOS a capture can pin itself to one story at a time.** sbshot picks how many to shoot at once by sampling free memory, and off Linux it reads `os.freemem()`, which counts only truly free pages. macOS parks almost everything in "inactive" instead, which is reclaimable on demand, so the sampler can read ~100 MB on a 25 GB machine and shrink to one forever. `--jobs` does not help: it is only an upper cap. Check `parallelism` in `<run>/events.ndjson`; if it sits at 1 while `vm_stat` shows gigabytes inactive, that is this. A 124-shot run takes about 90 minutes pinned and about 6 minutes at four at a time, so it is worth spotting before a long capture.
+- A fresh worktree cannot build Storybook: `i18n-translations-hash.json` is gitignored and generated. Run `node ./i18-generate-hash.cjs` in `<worktree>/frontend`, and symlink `node_modules` from the main checkout.
+- `pnpm test:storybook` starts its own server on 6006 and hangs silently if something already holds that port. Free it first.
+- ImageMagick on macOS may have no default font, so `--mode green-parallel` fails with ``unable to read font `' ``. Map Helvetica to a real file in `~/.config/ImageMagick/type.xml`.
+- `sbshot link <dir> <name>` adds a run from elsewhere into the workspace, but it symlinks. Keep the source directory alive until you have exported.
 - The export directory is build output. Delete it when done, or gitignore it.
-- Running the whole Storybook test suite locally fails broadly with
-  `page.goto: Timeout` from resource starvation. Scope it; CI is the real signal.
+- Running the whole Storybook test suite locally fails broadly with `page.goto: Timeout` from resource starvation. Scope it; CI is the real signal.
 
 ## Done means
 

.claude/skills/signoz-page-story/SKILL.md

@@ -5,63 +5,35 @@ description: Explore a SigNoz page, map the endpoints, states and query params i
 
 # SigNoz page stories
 
-A page story renders the real page inside the real app shell against msw, and its
-controls panel can reach every state the page has. The panel is the deliverable,
-not the story list.
+A page story renders the real page inside the real app shell against msw, and its controls panel can reach every state the page has. The panel is the deliverable, not the story list.
 
-`frontend/src/storybook/README.md` is the API surface (providers, parameters,
-control builders, module mocks, navigation). Read it first; this skill is the
-process on top of it.
+`frontend/src/storybook/README.md` is the API surface (providers, parameters, control builders, module mocks, navigation). Read it first; this skill is the process on top of it.
 
 ## Workflow
 
-1. **Map the page**: [references/discovery.md](references/discovery.md). Produce
-   the inventory (endpoints, states, params, permissions, caps) before writing
-   code. No inventory, no story.
-2. **Skeleton first**: story + empty `defineStoryMocks`, then run it. The console
-   names the endpoints step 1 missed.
+1. **Map the page**: [references/discovery.md](references/discovery.md). Produce the inventory (endpoints, states, params, permissions, caps) before writing code. No inventory, no story.
+2. **Skeleton first**: story + empty `defineStoryMocks`, then run it. The console names the endpoints step 1 missed.
 3. **Inventory to controls**: [references/controls.md](references/controls.md).
-4. **Mock data and handlers**: builders in `__story_mockdata__`, handlers in the page's
-   mocks module.
-5. **Verify in the browser**: [references/verify.md](references/verify.md). Never
-   report the story as done without it.
+4. **Mock data and handlers**: builders in `__story_mockdata__`, handlers in the page's mocks module.
+5. **Verify in the browser**: [references/verify.md](references/verify.md). Never report the story as done without it.
 
 ## Where it lands in the sidebar
 
-The sidebar mirrors the app's own side nav (`container/SideNav/menuItems.tsx`), so
-a page sits where someone would click it in the product. Four things decide that,
-and all four are part of writing the story, not a follow-up.
+The sidebar mirrors the app's own side nav (`container/SideNav/menuItems.tsx`), so a page sits where someone would click it in the product. Four things decide that, and all four are part of writing the story, not a follow-up.
 
-**Title.** `Pages/<Area>/<Page>`, where `<Area>` is the nav section and `<Page>`
-is the label the nav gives it.
+**Title.** `Pages/<Area>/<Page>`, where `<Area>` is the nav section and `<Page>` is the label the nav gives it.
 
-- The leaf is the product's label, never the component's name: `MetricsExplorer`
-  is `Metrics/Explorer`, `MeterExplorer` is `Metering/Cost Meter`,
-  `AIAssistantPage` is `Noz`.
+- The leaf is the product's label, never the component's name: `MetricsExplorer` is `Metrics/Explorer`, `MeterExplorer` is `Metering/Cost Meter`, `AIAssistantPage` is `Noz`.
 - Never repeat the area in the leaf: `Alerts/Rules`, not `Alerts/AlertRules`.
-- A leaf never shares its name with a sibling folder. The folder wins and the
-  page becomes `List`, or `Overview` for a tab strip: `Services/List` beside
-  `Services/Detail`.
+- A leaf never shares its name with a sibling folder. The folder wins and the page becomes `List`, or `Overview` for a tab strip: `Services/List` beside `Services/Detail`.
 - Title Case with spaces. No camelCase, no kebab.
-- Four levels is the floor to stay under: `Pages/Alerts/Channels/New` is as deep
-  as it goes.
-- Pages nobody navigates to on purpose go under `Pages/System` (`Status`,
-  `Unauthorized`, `Workspace Locked`), and the pre-session pages under
-  `Pages/Auth`.
-- A page whose permission stories earn their own folder becomes one:
-  `Pages/Settings/Billing/Overview` beside `Pages/Settings/Billing/Authz`. See
-  **Permission stories** below.
+- Four levels is the floor to stay under: `Pages/Alerts/Channels/New` is as deep as it goes.
+- Pages nobody navigates to on purpose go under `Pages/System` (`Status`, `Unauthorized`, `Workspace Locked`), and the pre-session pages under `Pages/Auth`.
+- A page whose permission stories earn their own folder becomes one: `Pages/Settings/Billing/Overview` beside `Pages/Settings/Billing/Authz`. See **Permission stories** below.
 
-**Order.** The `storySort.order` literal in `.storybook/preview.tsx` carries the
-order for every level. A new page in an existing area is appended to that area's
-array, in the order the product lists it; a new area goes where the side nav
-puts it. Storybook parses the order out of the file statically, so it has to
-stay an inline literal. Missing entries fall to the end of their level rather
-than disappearing, so a forgotten edit is a page at the bottom of its area, not
-a broken sidebar.
+**Order.** The `storySort.order` literal in `.storybook/preview.tsx` carries the order for every level. A new page in an existing area is appended to that area's array, in the order the product lists it; a new area goes where the side nav puts it. Storybook parses the order out of the file statically, so it has to stay an inline literal. Missing entries fall to the end of their level rather than disappearing, so a forgotten edit is a page at the bottom of its area, not a broken sidebar.
 
-**Tags.** Declared on the meta, right under `title`, and what the sidebar's tag
-filter answers questions with. Only these:
+**Tags.** Declared on the meta, right under `title`, and what the sidebar's tag filter answers questions with. Only these:
 
 | Tag | When |
 | --- | --- |
@@ -73,8 +45,7 @@ filter answers questions with. Only these:
 
 `autodocs` comes from `preview.tsx` and is never written on a meta.
 
-**Doc comment on the meta.** What the page is, in the page's own terms, then a
-blank line, then the route:
+**Doc comment on the meta.** What the page is, in the page's own terms, then a blank line, then the route:
 
 ```tsx
 const pageStory = storyMocks(logsExplorerMocks, {
@@ -97,79 +68,33 @@ const meta = {
 } satisfies Meta<LogsExplorerArgs>;
 ```
 
-The `pageStory` const and the trailing `parameters` line are what make the doc
-comment safe. The comment compiles to a `parameters` property that the csf plugin
-appends after the spread, so a meta that spreads `storyMocks(...)` and stops
-there loses `parameters.signoz` and renders the page against the global handlers
-alone: every one of the page's endpoints misses. Restating `parameters` as a
-literal gives the plugin something to merge into. `resolveStory` logs the
-combination that says it happened, so the console names it rather than leaving it
-to be found by reading the page.
+The `pageStory` const and the trailing `parameters` line are what make the doc comment safe. The comment compiles to a `parameters` property that the csf plugin appends after the spread, so a meta that spreads `storyMocks(...)` and stops there loses `parameters.signoz` and renders the page against the global handlers alone: every one of the page's endpoints misses. Restating `parameters` as a literal gives the plugin something to merge into. `resolveStory` logs the combination that says it happened, so the console names it rather than leaving it to be found by reading the page.
 
-It is the description on the page's Docs page, which is the only place a reader
-who is not in the code finds out what the page is for. Two or three sentences:
-what it shows, what drives it, and the gating worth knowing about (`Gated on
-authz permissions`, `follows the legacy editor role`). A control-driven route
-says so instead of a path: ``Route: `/metrics-explorer/*`, the tab control picks
-which``.
+It is the description on the page's Docs page, which is the only place a reader who is not in the code finds out what the page is for. Two or three sentences: what it shows, what drives it, and the gating worth knowing about (`Gated on authz permissions`, `follows the legacy editor role`). A control-driven route says so instead of a path: ``Route: `/metrics-explorer/*`, the tab control picks which``.
 
 ## Permission stories
 
-A page that gates UI on `lib/authz` keeps its permission states in a folder of
-their own, so the page's own file stays about the page and the sidebar answers
-"what does this permission do" in one place.
+A page that gates UI on `lib/authz` keeps its permission states in a folder of their own, so the page's own file stays about the page and the sidebar answers "what does this permission do" in one place.
 
-**Layout.** A second story file at `stories/authz/<Page>.authz.stories.tsx`,
-titled `Pages/<Area>/<Page>/Authz`, which turns the page into a folder: its own
-file is retitled `Pages/<Area>/<Page>/Overview`, and `.storybook/preview.tsx`
-gains the sub-order (`'Billing', ['Overview', 'Authz']`). Both files carry the
-`authz` tag and share the page's one mocks module, which the authz file imports
-as `../<Page>.stories.mocks`. It declares no controls and no mock data of its
-own: a permission story that needs a new response is a control the page's mocks
-were missing.
+**Layout.** A second story file at `stories/authz/<Page>.authz.stories.tsx`, titled `Pages/<Area>/<Page>/Authz`, which turns the page into a folder: its own file is retitled `Pages/<Area>/<Page>/Overview`, and `.storybook/preview.tsx` gains the sub-order (`'Billing', ['Overview', 'Authz']`). Both files carry the `authz` tag and share the page's one mocks module, which the authz file imports as `../<Page>.stories.mocks`. It declares no controls and no mock data of its own: a permission story that needs a new response is a control the page's mocks were missing.
 
-**One story per permission the page reads**, named for what is gone: `NoRead`,
-`NoList`, `NoUpdate`, `NoCreate`, `NoDelete`. Then the combinations the page
-itself distinguishes, and only those: `NoManage` where two permissions gate one
-button, `ReadOnly` where everything but reading is denied, `NoSubscriptionAccess`
-where none of the resource's permissions are held, and `CheckFailed` for
-`authzState: 'error'`, which is the page's fail-open path rather than a denial.
+**One story per permission the page reads**, named for what is gone: `NoRead`, `NoList`, `NoUpdate`, `NoCreate`, `NoDelete`. Then the combinations the page itself distinguishes, and only those: `NoManage` where two permissions gate one button, `ReadOnly` where everything but reading is denied, `NoSubscriptionAccess` where none of the resource's permissions are held, and `CheckFailed` for `authzState: 'error'`, which is the page's fail-open path rather than a denial.
 
-**Revoke, never allow-list.** Each story is a full grant minus what its name
-says: `args: { revoked: ['read:subscription'] }`. The `Revoked` control subtracts
-from the preset, so the story stays "an admin missing one permission" as the
-catalogue grows, and the diff against the page's `Default` is the one permission.
-Rebuilding the allow-list by hand drifts the moment a resource is added.
+**Revoke, never allow-list.** Each story is a full grant minus what its name says: `args: { revoked: ['read:subscription'] }`. The `Revoked` control subtracts from the preset, so the story stays "an admin missing one permission" as the catalogue grows, and the diff against the page's `Default` is the one permission. Rebuilding the allow-list by hand drifts the moment a resource is added.
 
-**Never a role preset in this folder.** `access: 'viewer'` moves the legacy role,
-the side nav and every other resource's permissions at the same time, so the
-story no longer shows what its name claims. A persona is a story on the page's
-own file, and only when the product has that persona.
+**Never a role preset in this folder.** `access: 'viewer'` moves the legacy role, the side nav and every other resource's permissions at the same time, so the story no longer shows what its name claims. A persona is a story on the page's own file, and only when the product has that persona.
 
-**Pair the revocation with the state that renders the gated control.** A button
-that only exists on a trial needs the plan too:
-`args: { plan: 'on-trial', revoked: ['create:subscription'] }`. A permission
-whose denial changes nothing on screen gets no story: say so in the PR.
+**Pair the revocation with the state that renders the gated control.** A button that only exists on a trial needs the plan too: `args: { plan: 'on-trial', revoked: ['create:subscription'] }`. A permission whose denial changes nothing on screen gets no story: say so in the PR.
 
-Check these by what is turned off, not by what the page says. The page reads the
-same either way, so a story that is wrong still looks right. Check that the
-control the permission guards is off, and that the denial message is there or
-gone.
+Check these by what is turned off, not by what the page says. The page reads the same either way, so a story that is wrong still looks right. Check that the control the permission guards is off, and that the denial message is there or gone.
 
-**Do not use `toBeEnabled` or `toBeDisabled`.** They only look at the `disabled`
-attribute. `@signozhq/ui` turns a button off with `aria-disabled` instead, so
-these matchers pass on a button nobody can click, and the test goes green while
-clicking straight through a denial. Check the attribute the component really
-sets:
+**Do not use `toBeEnabled` or `toBeDisabled`.** They only look at the `disabled` attribute. `@signozhq/ui` turns a button off with `aria-disabled` instead, so these matchers pass on a button nobody can click, and the test goes green while clicking straight through a denial. Check the attribute the component really sets:
 
 ```ts
 expect(save).toHaveAttribute('aria-disabled', 'true');
 ```
 
-**Some controls are off with no attribute at all.** The browser turns off
-everything inside a disabled `<fieldset>` without marking it, and a switch is a
-`<button>` underneath. For those, an attribute check proves nothing, and so does
-looking for a parent `fieldset[disabled]`. Click it and check nothing happened:
+**Some controls are off with no attribute at all.** The browser turns off everything inside a disabled `<fieldset>` without marking it, and a switch is a `<button>` underneath. For those, an attribute check proves nothing, and so does looking for a parent `fieldset[disabled]`. Click it and check nothing happened:
 
 ```ts
 const before = toggle.getAttribute('aria-checked');
@@ -177,66 +102,22 @@ await userEvent.click(toggle);
 await expect(toggle.getAttribute('aria-checked')).toBe(before);
 ```
 
-**Check that a new assertion can fail.** Flip it once and run it. If that story
-goes red and nothing else does, the assertion is real; put it back. A test that
-cannot fail is worse than no test, because it looks like coverage.
+**Check that a new assertion can fail.** Flip it once and run it. If that story goes red and nothing else does, the assertion is real; put it back. A test that cannot fail is worse than no test, because it looks like coverage.
 
-**Delete a story once its difference disappears.** Say a story checks that a
-button reads "View" rather than "Edit" when a permission is missing. If the label
-later becomes the same either way, that story passes no matter which permissions
-are held, including all of them, and it is testing nothing. When a behaviour
-stops depending on a permission, delete the story or rewrite it to lock in the
-new behaviour, and say which one you did in the PR.
+**Delete a story once its difference disappears.** Say a story checks that a button reads "View" rather than "Edit" when a permission is missing. If the label later becomes the same either way, that story passes no matter which permissions are held, including all of them, and it is testing nothing. When a behaviour stops depending on a permission, delete the story or rewrite it to lock in the new behaviour, and say which one you did in the PR.
 
 ## Rules
 
-- **Default is the loaded page.** `export const Default: Story = {}` with no args,
-  every widget carrying data. Empty, loading and failed are variants or control
-  values, never the default.
-- **A control is a knob on a response**, resolved through `handlers`, `config` or
-  `effect`. Never a component prop, never a module mock added for one story.
-- **Every branch in the inventory is reachable from the panel.** A state that
-  needs a code edit to see is a missing control.
-- **Never re-declare what every story already has**: banner, side nav, data state
-  (loaded/loading/error), access preset, permissions, check state.
-- **A variant earns a story only when it is worth linking to**: an empty
-  workspace, a viewer, a page mid-load. Everything else stays a control.
-- **Endpoints the page owns go through `response.json`**, so the Data control
-  covers loaded, loading and failed in one declaration. Endpoints the page cannot
-  render without (ingestion detection, preferences, feature payloads) take a
-  plain resolver so the shell survives the loading and error states.
-- **Query-param state starts from `route`** (`/logs?tab=explorer`). In-page param
-  navigation works inside a story; a different pathname is blocked and reported
-  by the overlay. A control for a param is worth it only when the param is a page
-  mode someone would want to flip.
-- **File layout**: every story file for a page lives under
-  `src/pages/<Page>/stories/`: `<Page>.stories.tsx`, `<Page>.stories.mocks.tsx`,
-  payload builders in `stories/__story_mockdata__/<page>.ts`. Nothing
-  page-specific in `src/storybook/controls/`. A page that is a tab strip over
-  several routes gets one story file per tab, in its own folder under the module
-  page (`LogsModulePage/Pipelines/stories/Pipelines.stories.tsx`), each with its
-  own mocks and `__story_mockdata__/`; the builders more than one tab needs stay
-  in the module page's own `stories/__story_mockdata__/`
-  (`AlertList/stories/__story_mockdata__/alerts.ts`), which a tab reaches as
-  `../../stories/__story_mockdata__/alerts`. Every one of them renders the module page, so the tab
-  strip is there, and the `route` its mocks return decides which tab is open.
-  A page's permission stories go one level further down, in
-  `stories/authz/<Page>.authz.stories.tsx`, on the page's own mocks: see
-  **Permission stories**.
-- **A state only a click reaches is a story with a `play` function**, not a
-  control: a drawer, a modal, an edit mode the page holds in component state.
-  Drive it with `userEvent` and the queries from `storybook/test`, take the first
-  of a repeated row action, and wait on the state's own text. The page fetches
-  before it renders a row, so the finder needs a timeout past the 1s default. A
-  state the app drops again on its own, such as one keyed on an array identity
-  that a refetch replaces, does not get a story: it would not survive being
-  looked at. A *sequence* of such states, a wizard's steps or a
-  questionnaire's pages, is still a control: declare the steps in the mocks
-  module and walk them from a `play` on the meta that destructures `mount`, which
-  is what makes Storybook replay it on an arg change. See
-  [references/controls.md](references/controls.md).
-- **The mocks are AI-owned and say so.** `<Page>.stories.mocks.tsx` and every file
-  under a `__story_mockdata__/` open with this banner, above the imports:
+- **Default is the loaded page.** `export const Default: Story = {}` with no args, every widget carrying data. Empty, loading and failed are variants or control values, never the default.
+- **A control is a knob on a response**, resolved through `handlers`, `config` or `effect`. Never a component prop, never a module mock added for one story.
+- **Every branch in the inventory is reachable from the panel.** A state that needs a code edit to see is a missing control.
+- **Never re-declare what every story already has**: banner, side nav, data state (loaded/loading/error), access preset, permissions, check state.
+- **A variant earns a story only when it is worth linking to**: an empty workspace, a viewer, a page mid-load. Everything else stays a control.
+- **Endpoints the page owns go through `response.json`**, so the Data control covers loaded, loading and failed in one declaration. Endpoints the page cannot render without (ingestion detection, preferences, feature payloads) take a plain resolver so the shell survives the loading and error states.
+- **Query-param state starts from `route`** (`/logs?tab=explorer`). In-page param navigation works inside a story; a different pathname is blocked and reported by the overlay. A control for a param is worth it only when the param is a page mode someone would want to flip.
+- **File layout**: every story file for a page lives under `src/pages/<Page>/stories/`: `<Page>.stories.tsx`, `<Page>.stories.mocks.tsx`, payload builders in `stories/__story_mockdata__/<page>.ts`. Nothing page-specific in `src/storybook/controls/`. A page that is a tab strip over several routes gets one story file per tab, in its own folder under the module page (`LogsModulePage/Pipelines/stories/Pipelines.stories.tsx`), each with its own mocks and `__story_mockdata__/`; the builders more than one tab needs stay in the module page's own `stories/__story_mockdata__/` (`AlertList/stories/__story_mockdata__/alerts.ts`), which a tab reaches as `../../stories/__story_mockdata__/alerts`. Every one of them renders the module page, so the tab strip is there, and the `route` its mocks return decides which tab is open. A page's permission stories go one level further down, in `stories/authz/<Page>.authz.stories.tsx`, on the page's own mocks: see **Permission stories**.
+- **A state only a click reaches is a story with a `play` function**, not a control: a drawer, a modal, an edit mode the page holds in component state. Drive it with `userEvent` and the queries from `storybook/test`, take the first of a repeated row action, and wait on the state's own text. The page fetches before it renders a row, so the finder needs a timeout past the 1s default. A state the app drops again on its own, such as one keyed on an array identity that a refetch replaces, does not get a story: it would not survive being looked at. A _sequence_ of such states, a wizard's steps or a questionnaire's pages, is still a control: declare the steps in the mocks module and walk them from a `play` on the meta that destructures `mount`, which is what makes Storybook replay it on an arg change. See [references/controls.md](references/controls.md).
+- **The mocks are AI-owned and say so.** `<Page>.stories.mocks.tsx` and every file under a `__story_mockdata__/` open with this banner, above the imports:
 
   ```ts
   /**
@@ -245,52 +126,23 @@ new behaviour, and say which one you did in the PR.
    */
   ```
 
-  The root `.gitattributes` marks both paths `linguist-generated=true`, so the
-  reviewer gets them collapsed and spends the attention on the rendered page. The
-  story file is the human surface and never carries the banner. A file with the
-  banner has to stay regenerable from the page alone: no page knowledge in
-  `src/storybook/`, and builders typed from `src/api/generated` where the endpoint
-  has types, so a contract change is a compile error instead of a mock that lies.
-- **Reuse fixtures** from `src/mocks-server/` and `src/tests/fixtures/` where they
-  exist. An endpoint jest needs too belongs in `src/mocks-server/handlers.ts`.
-- **Shared response builders live in `src/storybook/msw/__story_mockdata__/`**: typed
-  helpers like `queryRangeV5ScalarResponse` that multiple pages need. Before
-  writing a response shape inline, check if a builder exists; if not and the
-  shape will repeat, add it there. Page-specific builders stay in the page's
-  `__story_mockdata__/`.
-- **The story's own doc comment is per state.** Every `export const` gets one:
-  what that state shows, not how it is built. It renders in the States list on
-  the page's Docs page, so `Undocumented.` there is a story nobody described.
-- **Story names come from a fixed vocabulary** where one fits: `Default`,
-  `Viewer`, `Empty`, `Loading`, `Error`. Page-specific states get page-specific
-  names (`NoIngestion`, `Unlicensed`), never a second spelling of one of those
-  (`ViewerAccess`, `NonAdmin`).
-- **No comment is the default.** Write one only for what the code cannot show:
-  a shape the backend dictates, an app bug the mock reproduces, an ordering or
-  cap the page depends on, a workaround and the reason for it. Never restate a
-  name, a type, or what a builder plainly builds; if the sentence reads as the
-  signature in prose, delete it. Nothing addressed to a reviewer. The one
-  comment a story always gets is its own doc comment: what it shows, in the
-  page's own terms.
+  The root `.gitattributes` marks both paths `linguist-generated=true`, so the reviewer gets them collapsed and spends the attention on the rendered page. The story file is the human surface and never carries the banner. A file with the banner has to stay regenerable from the page alone: no page knowledge in `src/storybook/`, and builders typed from `src/api/generated` where the endpoint has types, so a contract change is a compile error instead of a mock that lies.
+
+- **Reuse fixtures** from `src/mocks-server/` and `src/tests/fixtures/` where they exist. An endpoint jest needs too belongs in `src/mocks-server/handlers.ts`.
+- **Shared response builders live in `src/storybook/msw/__story_mockdata__/`**: typed helpers like `queryRangeV5ScalarResponse` that multiple pages need. Before writing a response shape inline, check if a builder exists; if not and the shape will repeat, add it there. Page-specific builders stay in the page's `__story_mockdata__/`.
+- **The story's own doc comment is per state.** Every `export const` gets one: what that state shows, not how it is built. It renders in the States list on the page's Docs page, so `Undocumented.` there is a story nobody described.
+- **Story names come from a fixed vocabulary** where one fits: `Default`, `Viewer`, `Empty`, `Loading`, `Error`. Page-specific states get page-specific names (`NoIngestion`, `Unlicensed`), never a second spelling of one of those (`ViewerAccess`, `NonAdmin`).
+- **No comment is the default.** Write one only for what the code cannot show: a shape the backend dictates, an app bug the mock reproduces, an ordering or cap the page depends on, a workaround and the reason for it. Never restate a name, a type, or what a builder plainly builds; if the sentence reads as the signature in prose, delete it. Nothing addressed to a reviewer. The one comment a story always gets is its own doc comment: what it shows, in the page's own terms.
 
 ## Done means
 
 - [ ] `Default` shows the page with data, checked in dark and light
-- [ ] title follows the sidebar rules, tags declared, and the page's entry added
-      to the `storySort.order` literal in `.storybook/preview.tsx`
-- [ ] the meta carries its doc comment with the `Route:` line, the meta restates
-      `parameters: { ...pageStory.parameters }` after the spread, and every story
-      export carries its own doc comment
-- [ ] the page's Docs page renders: description, controls table, and one row per
-      state with no `Undocumented.`
-- [ ] a page tagged `authz` has its `Authz` folder: one story per permission it
-      reads, each reached by `revoked`, none of them a role preset, and each one
-      checked by the `disabled` state of what the permission gates
+- [ ] title follows the sidebar rules, tags declared, and the page's entry added to the `storySort.order` literal in `.storybook/preview.tsx`
+- [ ] the meta carries its doc comment with the `Route:` line, the meta restates `parameters: { ...pageStory.parameters }` after the spread, and every story export carries its own doc comment
+- [ ] the page's Docs page renders: description, controls table, and one row per state with no `Undocumented.`
+- [ ] a page tagged `authz` has its `Authz` folder: one story per permission it reads, each reached by `revoked`, none of them a role preset, and each one checked by the `disabled` state of what the permission gates
 - [ ] the mocks module and every `__story_mockdata__` file carry the AI-owned banner
 - [ ] every control flipped once, its effect seen on screen
-- [ ] console clean: no `[storybook] no msw handler`, no 501, no msw unhandled
-      request, no React warning
+- [ ] console clean: no `[storybook] no msw handler`, no 501, no msw unhandled request, no React warning
 - [ ] no navigation overlay on mount
-- [ ] `pnpm tsgo --noEmit`, `pnpm exec oxlint <files>`,
-      `pnpm exec oxfmt --check <files>` all clean. The repo has no
-      prettier: `pnpm exec prettier` prints a pass while exiting 254
+- [ ] `pnpm tsgo --noEmit`, `pnpm exec oxlint <files>`, `pnpm exec oxfmt --check <files>` all clean. The repo has no prettier: `pnpm exec prettier` prints a pass while exiting 254

.claude/skills/signoz-page-story/references/controls.md

@@ -1,13 +1,10 @@
 # Turning the inventory into controls
 
-Every row of the inventory becomes a control, a global control that already
-exists, or a documented reason it cannot be one.
+Every row of the inventory becomes a control, a global control that already exists, or a documented reason it cannot be one.
 
 ## Imports
 
-Paths written as `src/storybook/...` in prose are repo paths, not import
-specifiers. Stories import through the `@/` alias (`@/*` → `./src/*`); modules
-inside `src/storybook/` import each other relatively.
+Paths written as `src/storybook/...` in prose are repo paths, not import specifiers. Stories import through the `@/` alias (`@/*` → `./src/*`); modules inside `src/storybook/` import each other relatively.
 
 | Import | From |
 | --- | --- |
@@ -31,38 +28,21 @@ inside `src/storybook/` import each other relatively.
 
 Rules that come with them:
 
-- `countControl` `max` goes past what the page renders, so a story can show the
-  cap being hit. `0` is the empty state, which is why an empty list rarely needs
-  its own story. When the cap is in the *request* (`?limit=5`) rather than the
-  renderer, stop `max` at the limit: a longer response is a body the backend
-  cannot send.
-- `choiceControl` options come from a `const` array typed with
-  `(typeof X)[number]`, not from string literals scattered in the handlers.
-- Defaults describe the fully-populated page. The panel starts where `Default`
-  starts.
-- `group` is `'<Page> · <facet>'`, such as `'Services · lists'` or
-  `'Alerts · rules'`. Keep a page's knobs in two or three groups, not one per
-  control.
-- `description` only when the name does not carry the effect (what dismissing
-  does, what the cap is, which widget it feeds).
+- `countControl` `max` goes past what the page renders, so a story can show the cap being hit. `0` is the empty state, which is why an empty list rarely needs its own story. When the cap is in the _request_ (`?limit=5`) rather than the renderer, stop `max` at the limit: a longer response is a body the backend cannot send.
+- `choiceControl` options come from a `const` array typed with `(typeof X)[number]`, not from string literals scattered in the handlers.
+- Defaults describe the fully-populated page. The panel starts where `Default` starts.
+- `group` is `'<Page> · <facet>'`, such as `'Services · lists'` or `'Alerts · rules'`. Keep a page's knobs in two or three groups, not one per control.
+- `description` only when the name does not carry the effect (what dismissing does, what the cap is, which widget it feeds).
 
 ## Which hook
 
 `defineStoryMocks` takes three, all optional:
 
-- `handlers(values, response)`: the page's endpoints. Everything the page owns
-  goes through `response.json`, so the global Data control turns the whole page
-  into loading or failed without a second declaration. An endpoint the page
-  cannot render at all without (ingestion detection, preferences, license
-  payloads) takes a plain `rest.get(...)` resolver instead, so the shell stays
-  visible while the rest hangs or fails.
-- `config(values)`: `SignozStoryConfig` for knobs no endpoint covers: `route`,
-  `appContext`, `reduxState`, `queryBuilder`, `theme`.
+- `handlers(values, response)`: the page's endpoints. Everything the page owns goes through `response.json`, so the global Data control turns the whole page into loading or failed without a second declaration. An endpoint the page cannot render at all without (ingestion detection, preferences, license payloads) takes a plain `rest.get(...)` resolver instead, so the shell stays visible while the rest hangs or fails.
+- `config(values)`: `SignozStoryConfig` for knobs no endpoint covers: `route`, `appContext`, `reduxState`, `queryBuilder`, `theme`.
 - `effect(values)`: module-level state no provider exposes.
 
-One endpoint feeding several widgets stays one handler that reads the request.
-`response.json` hands the request to the builder and awaits it, so reading a
-query param, or a POST body, does not cost the Data control:
+One endpoint feeding several widgets stays one handler that reads the request. `response.json` hands the request to the builder and awaits it, so reading a query param, or a POST body, does not cost the Data control:
 
 ```ts
 rest.get(
@@ -85,18 +65,11 @@ rest.post(
 ),
 ```
 
-Reach for a plain `rest.post(url, async (req, res, ctx) => …)` only when the
-endpoint has to keep answering while the Data control is on `loading` or
-`error`: detection calls the page cannot render without.
+Reach for a plain `rest.post(url, async (req, res, ctx) => …)` only when the endpoint has to keep answering while the Data control is on `loading` or `error`: detection calls the page cannot render without.
 
 ## Mutations
 
-A control drives the response, so a write the page makes against state a control
-owns does not stick: the refetch answers with the control's value and the button
-appears to do nothing. Two honest options: leave it declarative and say so in
-the PR, or move the state into `effect` so the handler can read what the page
-wrote. Never fake the write by mutating a builder's module state without saying
-where the state lives.
+A control drives the response, so a write the page makes against state a control owns does not stick: the refetch answers with the control's value and the button appears to do nothing. Two honest options: leave it declarative and say so in the PR, or move the state into `effect` so the handler can read what the page wrote. Never fake the write by mutating a builder's module state without saying where the state lives.
 
 ## Wiring it up
 
@@ -146,15 +119,11 @@ const meta = {
 } satisfies Meta<ServicesArgs>;
 ```
 
-`PageStoryArgs` folds in the global controls, so a story's `args` can set
-`access`, `dataState` or `banner` next to the page's own knobs and stay typed.
+`PageStoryArgs` folds in the global controls, so a story's `args` can set `access`, `dataState` or `banner` next to the page's own knobs and stay typed.
 
 ## A step the page keeps in component state
 
-A wizard's step, a questionnaire's page, a picker's next question: the page holds
-it in `useState` and nothing in the URL says which one is open. It is still a
-control. Declare the steps in the mocks module and drive them from a `play` on
-the **meta**, so every story of the page inherits the walk and only sets `args`:
+A wizard's step, a questionnaire's page, a picker's next question: the page holds it in `useState` and nothing in the URL says which one is open. It is still a control. Declare the steps in the mocks module and drive them from a `play` on the **meta**, so every story of the page inherits the walk and only sets `args`:
 
 ```tsx
 // <Page>.stories.mocks.tsx
@@ -179,39 +148,23 @@ const meta = {
 export const Configure: Story = { args: { step: 'configure' } };
 ```
 
-**Destructuring `mount` is what makes it a control.** Storybook re-runs a play
-function on an arg change only for a story whose play asks to be remounted
-(`usesMount`); otherwise it re-renders the tree the previous walk left behind and
-the panel looks broken. With `mount` destructured, the story renders when `play`
-calls it, and every arg change replays the walk from a fresh mount.
+**Destructuring `mount` is what makes it a control.** Storybook re-runs a play function on an arg change only for a story whose play asks to be remounted (`usesMount`); otherwise it re-renders the tree the previous walk left behind and the panel looks broken. With `mount` destructured, the story renders when `play` calls it, and every arg change replays the walk from a fresh mount.
 
 The walk itself:
 
-- one `answer` function per step, in an array indexed the same as the step list,
-  so reaching step *n* is `answers.slice(0, STEPS.indexOf(step))`;
-- answer each step with the least its Next button accepts, and prefer a "do this
-  later" over filling a slider;
-- run them sequentially (`reduce` over a promise), since each answer is what
-  renders the step the next one reads;
-- bail out when the page did not start where the walk expects, such as a source
-  deep-linked past the questions. Check for the first step's own text rather than
-  reading another control's value.
+- one `answer` function per step, in an array indexed the same as the step list, so reaching step _n_ is `answers.slice(0, STEPS.indexOf(step))`;
+- answer each step with the least its Next button accepts, and prefer a "do this later" over filling a slider;
+- run them sequentially (`reduce` over a promise), since each answer is what renders the step the next one reads;
+- bail out when the page did not start where the walk expects, such as a source deep-linked past the questions. Check for the first step's own text rather than reading another control's value.
 
-An endpoint that only settles the transition between two steps (the profile a
-questionnaire saves before its last page) takes a plain resolver, or the Data
-control on `loading` strands the walk halfway.
+An endpoint that only settles the transition between two steps (the profile a questionnaire saves before its last page) takes a plain resolver, or the Data control on `loading` strands the walk halfway.
 
 ## Not a control
 
-- Anything the global controls already cover: banner, side nav, data state,
-  access preset, granted permissions, revoked permissions, check state.
-- A knob whose effect nobody can see on the page. Delete it or find the widget it
-  was supposed to drive.
-- A raw payload as an object control. Controls carry intent (`5 dashboards`,
-  `viewer`), and the builder turns intent into the payload.
-- Anything that needs a module mock or a component prop to work. If the state
-  cannot be produced from a response, config or module state, say so in the PR
-  instead of faking it.
+- Anything the global controls already cover: banner, side nav, data state, access preset, granted permissions, revoked permissions, check state.
+- A knob whose effect nobody can see on the page. Delete it or find the widget it was supposed to drive.
+- A raw payload as an object control. Controls carry intent (`5 dashboards`, `viewer`), and the builder turns intent into the payload.
+- Anything that needs a module mock or a component prop to work. If the state cannot be produced from a response, config or module state, say so in the PR instead of faking it.
 
 ## Control or story
 
@@ -220,12 +173,8 @@ Default to a control. Write a story when the state is worth a link:
 - the fresh workspace, because that is what a new user sees
 - a page-defining mode (a tab, a category) that has its own layout
 
-A permission that visibly changes the page is a story too, but it goes in the
-page's `Authz` folder, one per permission, turned with the `Revoked` control.
-See **Permission stories** in SKILL.md.
+A permission that visibly changes the page is a story too, but it goes in the page's `Authz` folder, one per permission, turned with the `Revoked` control. See **Permission stories** in SKILL.md.
 
 Combinations of controls do not need stories, which is what the panel is for.
 
-Each story gets one prose doc comment: what it shows, in the page's own terms.
-Everywhere else the comment rule in SKILL.md applies: write one only for what
-the code cannot show.
+Each story gets one prose doc comment: what it shows, in the page's own terms. Everywhere else the comment rule in SKILL.md applies: write one only for what the code cannot show.

.claude/skills/signoz-page-story/references/discovery.md

@@ -1,14 +1,10 @@
 # Mapping a page
 
-Two passes: read the code, then let the running story correct you. Write the
-inventory down: it is what the controls are derived from, and the only
-protection against a story that renders one state and calls it a page.
+Two passes: read the code, then let the running story correct you. Write the inventory down: it is what the controls are derived from, and the only protection against a story that renders one state and calls it a page.
 
 ## Pass 1: read the page
 
-Start at `src/pages/<Page>/` and follow it outward: the containers it mounts
-(`src/container/<Feature>/`), the hooks those use, the components with their own
-fetches. Stop at leaf components that take props only.
+Start at `src/pages/<Page>/` and follow it outward: the containers it mounts (`src/container/<Feature>/`), the hooks those use, the components with their own fetches. Stop at leaf components that take props only.
 
 Grep recipes, run against the page's directories:
 
@@ -24,41 +20,32 @@ Grep recipes, run against the page's directories:
 | empty and error branches | `isLoading\|isError\|isFetching\|length === 0\|!data` |
 | render caps | `slice(0,\|PAGE_SIZE\|pageSize\|limit` |
 
-`src/constants/routes.ts` has the route, `src/constants/query.ts` the param names,
-`src/lib/authz/README.md` how a permission check resolves.
+`src/constants/routes.ts` has the route, `src/constants/query.ts` the param names, `src/lib/authz/README.md` how a permission check resolves.
 
 ## The inventory
 
 One table, in the story's PR or scratch notes:
 
-| Endpoint | Feeds | States it can be in |
-| --- | --- | --- |
+| Endpoint        | Feeds            | States it can be in    |
+| --------------- | ---------------- | ---------------------- |
 | `GET /api/v1/x` | the header count | populated, zero, error |
 
 Plus four short lists:
 
 - **Query params** the page reads, and what each one switches.
 - **Permission checks** the page makes, and what disappears when each is denied.
-- **Preferences and flags** that change layout (dismissed banners, onboarding
-  checklists, opt-in views).
+- **Preferences and flags** that change layout (dismissed banners, onboarding checklists, opt-in views).
 - **Caps**: how many rows each list renders before it truncates or paginates.
 
-A state that appears in this inventory and not in the controls panel is a bug in
-the story.
+A state that appears in this inventory and not in the controls panel is a bug in the story.
 
 ## Pass 2: let it run
 
-Write the story and an empty `defineStoryMocks({ controls: {} })`, point it at the
-route with `layout: 'app'`, then open it (see verify.md). The console is the
-oracle:
+Write the story and an empty `defineStoryMocks({ controls: {} })`, point it at the route with `layout: 'app'`, then open it (see verify.md). The console is the oracle:
 
-- `[storybook] no msw handler` or a 501 from the catch-all: an endpoint pass 1
-  missed. Add it to the inventory.
-- an msw unhandled-request warning: a request going to an origin the handlers do
-  not answer on. handlers are declared against `http://localhost`.
-- a spinner that never resolves with the Data control on `loaded`: a handler
-  whose URL does not match what the page calls.
-- the navigation overlay on mount: the page redirects, usually because `route`
-  is wrong or a guard is failing on a permission the controls have not granted.
+- `[storybook] no msw handler` or a 501 from the catch-all: an endpoint pass 1 missed. Add it to the inventory.
+- an msw unhandled-request warning: a request going to an origin the handlers do not answer on. handlers are declared against `http://localhost`.
+- a spinner that never resolves with the Data control on `loaded`: a handler whose URL does not match what the page calls.
+- the navigation overlay on mount: the page redirects, usually because `route` is wrong or a guard is failing on a permission the controls have not granted.
 
 Repeat until the console is silent. Only then start declaring controls.

.claude/skills/signoz-page-story/references/verify.md

@@ -1,7 +1,6 @@
 # Verifying a page story
 
-A story is not done because it compiles. It is done when each control has been
-seen changing the page and the console is silent.
+A story is not done because it compiles. It is done when each control has been seen changing the page and the console is silent.
 
 ## Run it
 
@@ -9,12 +8,9 @@ seen changing the page and the console is silent.
 cd frontend && pnpm storybook --ci --quiet   # :6006, background it
 ```
 
-A newly added `.stories.tsx` takes a few seconds to appear in `index.json` on an
-already-running server; an empty first poll is not a broken `stories` glob.
+A newly added `.stories.tsx` takes a few seconds to appear in `index.json` on an already-running server; an empty first poll is not a broken `stories` glob.
 
-Story ids come from the meta title: `Pages/Services/List` →
-`pages-services-list`, plus the story export in kebab-case. Render one story on
-its own:
+Story ids come from the meta title: `Pages/Services/List` → `pages-services-list`, plus the story export in kebab-case. Render one story on its own:
 
 ```
 http://localhost:6006/iframe.html?id=pages-services-list--default&viewMode=story
@@ -22,9 +18,7 @@ http://localhost:6006/iframe.html?id=pages-services-list--default&viewMode=story
 
 ## Flip controls from the URL
 
-Args are settable in the iframe URL, so a whole sweep runs headless without
-touching the panel. Booleans go as `!true` / `!false`, numbers bare, arrays
-indexed, several separated by `;`, and the theme through `globals`:
+Args are settable in the iframe URL, so a whole sweep runs headless without touching the panel. Booleans go as `!true` / `!false`, numbers bare, arrays indexed, several separated by `;`, and the theme through `globals`:
 
 ```
 &args=services:0;apdex:poor;access:viewer;dataState:loading
@@ -32,13 +26,11 @@ indexed, several separated by `;`, and the theme through `globals`:
 &globals=theme:light
 ```
 
-That is the cheap way to check a control does something: load with and without
-it, diff the page text.
+That is the cheap way to check a control does something: load with and without it, diff the page text.
 
 ## Drive it
 
-Playwright lives in the repo's e2e workspace, so a scratch script can use it
-directly:
+Playwright lives in the repo's e2e workspace, so a scratch script can use it directly:
 
 ```js
 import pw from '<repo>/tests/e2e/node_modules/playwright/index.js';
@@ -58,40 +50,18 @@ console.log((await page.locator('body').innerText()).slice(0, 1500), problems);
 await browser.close();
 ```
 
-Screenshots are worth taking for `Default` in both themes: text extraction does
-not catch an unstyled page. Take them with
-[sbshot](https://github.com/SigNoz/sbshot), e.g.
-`sbshot capture http://localhost:6006 --title <story title> --theme dark,light`.
+Screenshots are worth taking for `Default` in both themes: text extraction does not catch an unstyled page. Take them with [sbshot](https://github.com/SigNoz/sbshot), e.g. `sbshot capture http://localhost:6006 --title <story title> --theme dark,light`.
 
-That is one run, for checking the story you just wrote. Comparing two branches is
-a different job: see the `sbshot-visual-diff` skill, which covers the baseline to
-pick, measuring the noise and exporting something a reviewer can open.
+That is one run, for checking the story you just wrote. Comparing two branches is a different job: see the `sbshot-visual-diff` skill, which covers the baseline to pick, measuring the noise and exporting something a reviewer can open.
 
 ## Gates
 
-- **Console silent.** `[storybook] no msw handler`, a 501 from the catch-all, an
-  msw unhandled-request warning, a React key or state warning: assume the story
-  is wrong first. A warning that survives is sometimes the app's. Prove it by
-  turning off the control that renders the widget and watching the warning go
-  with it, and by finding the same component elsewhere doing it right. Then
-  report the app bug in the PR. Never invent a field the API does not return to
-  silence a warning.
-- **No navigation overlay on mount.** "Navigation blocked in Storybook" on load
-  means the page is trying to leave: wrong `route`, or a guard denying on a
-  permission the controls did not grant.
-- **Every control moves something.** Sweep them one at a time from the URL and
-  diff the page text. A control with no diff is either wired to nothing or aimed
-  at a widget that is not rendering. Some only show their effect after an
-  interaction, such as a tab that has to be clicked or a select that has to be
-  opened. Drive that interaction rather than calling the control unobservable.
-- **Both themes render styled.** An unstyled page means the story is not inside
-  the provider decorator, or `<body data-theme>` was lost.
-- **Roles agree.** `<body data-signoz-story-role>` and
-  `<body data-signoz-context-role>` disagreeing means the page reads a different
-  `AppContext` than the story config fills.
-- **The page's own navigation works.** Tabs, filters and pagination that write
-  query params should re-render the page in place; only leaving the page belongs
-  in the overlay.
+- **Console silent.** `[storybook] no msw handler`, a 501 from the catch-all, an msw unhandled-request warning, a React key or state warning: assume the story is wrong first. A warning that survives is sometimes the app's. Prove it by turning off the control that renders the widget and watching the warning go with it, and by finding the same component elsewhere doing it right. Then report the app bug in the PR. Never invent a field the API does not return to silence a warning.
+- **No navigation overlay on mount.** "Navigation blocked in Storybook" on load means the page is trying to leave: wrong `route`, or a guard denying on a permission the controls did not grant.
+- **Every control moves something.** Sweep them one at a time from the URL and diff the page text. A control with no diff is either wired to nothing or aimed at a widget that is not rendering. Some only show their effect after an interaction, such as a tab that has to be clicked or a select that has to be opened. Drive that interaction rather than calling the control unobservable.
+- **Both themes render styled.** An unstyled page means the story is not inside the provider decorator, or `<body data-theme>` was lost.
+- **Roles agree.** `<body data-signoz-story-role>` and `<body data-signoz-context-role>` disagreeing means the page reads a different `AppContext` than the story config fills.
+- **The page's own navigation works.** Tabs, filters and pagination that write query params should re-render the page in place; only leaving the page belongs in the overlay.
 
 ## Then the usual
 
@@ -101,9 +71,7 @@ pnpm exec oxlint <changed files>
 pnpm exec oxfmt --check <changed files>
 ```
 
-There is no prettier in this repo. `pnpm exec prettier --check` fetches something
-else, prints `Prettier: All files formatted correctly` and exits 254: a pass that is
-not one.
+There is no prettier in this repo. `pnpm exec prettier --check` fetches something else, prints `Prettier: All files formatted correctly` and exits 254: a pass that is not one.
 
 ## Common failures
 

frontend/src/constants/reactQueryKeys.ts

@@ -24,7 +24,7 @@ export const REACT_QUERY_KEY = {
 	GET_ALL_ALERTS: 'GET_ALL_ALERTS',
 	ALERT_RULES_CHART_PREVIEW: 'ALERT_RULES_CHART_PREVIEW',
 	REMOVE_ALERT_RULE: 'REMOVE_ALERT_RULE',
-	DUPLICATE_ALERT_RULE: 'DUPLICATE_ALERT_RULE',
+	CLONE_ALERT_RULE: 'CLONE_ALERT_RULE',
 	GET_HOST_LIST: 'GET_HOST_LIST',
 	UPDATE_ALERT_RULE: 'UPDATE_ALERT_RULE',
 	GET_TRACE_V2_WATERFALL: 'GET_TRACE_V2_WATERFALL',

frontend/src/container/LLMObservability/Explorer/ListView/utils.tsx

@@ -1,6 +1,7 @@
 import type { TracesTableRow } from '../TracesTable/getFieldColumn';
 import { generatePath } from 'react-router-dom';
 import ROUTES from 'constants/routes';
+import { TraceDetailsTab } from 'pages/TraceDetailsV3/constants';
 import { formUrlParams } from 'utils/traceUtils';
 import { QueryDataV3 } from 'types/api/widgets/getQuery';
 
@@ -20,6 +21,7 @@ export const getTraceLink = (record: Record<string, unknown>): string => {
 	}
 
 	return `${generatePath(ROUTES.TRACE_DETAIL, { id: traceId })}${formUrlParams({
+		tab: TraceDetailsTab.Thread,
 		spanId,
 		levelUp: 0,
 		levelDown: 0,

frontend/src/container/LLMObservability/Explorer/TracesTable/FieldCell.tsx

@@ -3,6 +3,7 @@ import { Badge } from '@signozhq/ui/badge';
 import TanStackTable from 'components/TanStackTableView';
 import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
 import ROUTES from 'constants/routes';
+import { TraceDetailsTab } from 'pages/TraceDetailsV3/constants';
 import { getMs } from 'utils/timeUtils';
 import { useTimezone } from 'providers/Timezone';
 
@@ -44,7 +45,10 @@ function FieldCell({ name, value }: FieldCellProps): JSX.Element {
 	if (TRACE_ID_FIELD_NAMES.has(name)) {
 		return (
 			<Link
-				to={generatePath(ROUTES.TRACE_DETAIL, { id: text })}
+				to={{
+					pathname: generatePath(ROUTES.TRACE_DETAIL, { id: text }),
+					search: `?tab=${TraceDetailsTab.Thread}`,
+				}}
 				data-testid="trace-id"
 				onClick={(e): void => e.stopPropagation()}
 			>

frontend/src/container/ListAlertRules/__tests__/ListAlertRules.actions.test.tsx

@@ -2,6 +2,7 @@ import userEvent from '@testing-library/user-event';
 import { logEventMock } from '__tests__/logEventMock';
 import { safeNavigateMock } from '__tests__/safeNavigateMock';
 import { server } from 'mocks-server/server';
+import { alertRulesFixture } from 'mocks-server/__mockdata__/alert_rules';
 import { rest } from 'msw';
 import { screen, waitFor } from 'tests/test-utils';
 
@@ -121,22 +122,26 @@ describe('ListAlertRules — actions menu', () => {
 		expect(options).toStrictEqual(expect.objectContaining({ newTab: true }));
 	});
 
-	it('clone action: sends POST with " - Copy" suffix and opens the cloned rule returned by the API', async () => {
-		let capturedPostBody: unknown = null;
+	it('clone action: sends POST to clone endpoint and opens the cloned rule returned by the API', async () => {
+		let capturedRuleId: string | null = null;
 		server.use(
-			rest.post('http://localhost/api/v2/rules', async (req, res, ctx) => {
-				capturedPostBody = await req.json();
-				return res(
-					ctx.status(201),
-					ctx.json({
-						data: {
-							...(capturedPostBody as Record<string, unknown>),
-							id: 'cloned-from-server',
-						},
-						status: 'success',
-					}),
-				);
-			}),
+			rest.post(
+				'http://localhost/api/v2/rules/:id/clone',
+				async (req, res, ctx) => {
+					capturedRuleId = req.params.id as string;
+					return res(
+						ctx.status(201),
+						ctx.json({
+							data: {
+								...alertRulesFixture[0],
+								id: 'cloned-from-server',
+								alert: 'High CPU Alert - Copy',
+							},
+							status: 'success',
+						}),
+					);
+				},
+			),
 		);
 
 		renderListAlertRules();
@@ -145,9 +150,7 @@ describe('ListAlertRules — actions menu', () => {
 		await clickMenuItem('Clone');
 
 		await waitFor(() => {
-			expect(capturedPostBody).toStrictEqual(
-				expect.objectContaining({ alert: 'High CPU Alert - Copy' }),
-			);
+			expect(capturedRuleId).toBe('rule-1');
 		});
 
 		// The id from the server response round-trips into the navigate URL — this

frontend/src/container/ListAlertRules/components/ActionsMenu.tsx

@@ -6,10 +6,10 @@ import { Dropdown, type DropdownItemType } from '@signozhq/ui/dropdown';
 import { toast } from '@signozhq/ui/sonner';
 import { convertToApiError } from 'api/ErrorResponseHandlerForGeneratedAPIs';
 import {
-	createRule,
 	deleteRuleByID,
 	invalidateListRules,
 	patchRuleByID,
+	cloneRuleByID,
 } from 'api/generated/services/rules';
 import type {
 	RenderErrorResponseDTO,
@@ -62,10 +62,9 @@ function ActionsMenu({ rule, onEdit }: ActionsMenuProps): JSX.Element {
 	const handleClone = useCallback((): void => {
 		alertActionLogEvent(ALERT_ACTIONS.CLONE, rule);
 		toast.promise(
-			createRule({
-				...rule,
-				alert: `${rule.alert} - Copy`,
-			} as RuletypesPostableRuleDTO).then(async (response) => {
+			cloneRuleByID({
+				id: rule.id,
+			}).then(async (response) => {
 				await invalidateListRules(queryClient);
 				const newRule = response.data;
 				if (newRule) {

frontend/src/hooks/trace/__tests__/useCopySpanLink.test.tsx

@@ -0,0 +1,58 @@
+import { MouseEvent, ReactNode } from 'react';
+import { MemoryRouter } from 'react-router-dom';
+import { renderHook } from '@testing-library/react';
+import {
+	__resetSearchParamsGetter,
+	__setSearchParamsGetterForTest,
+} from 'utils/getUnstableCurrentSearchParams';
+
+import { useCopySpanLink } from '../useCopySpanLink';
+
+const mockCopy = jest.fn();
+
+jest.mock('react-use', () => ({
+	__esModule: true,
+	useCopyToClipboard: (): [unknown, jest.Mock] => [null, mockCopy],
+}));
+
+jest.mock('@signozhq/ui/sonner', () => ({
+	toast: { success: jest.fn() },
+}));
+
+// The router only knows the stale URL; nuqs has since written ?tab=thread.
+const wrapper = ({ children }: { children: ReactNode }): JSX.Element => (
+	<MemoryRouter initialEntries={['/trace/abc?tab=overview&spanId=old']}>
+		{children}
+	</MemoryRouter>
+);
+
+const clickEvent = {
+	preventDefault: jest.fn(),
+	stopPropagation: jest.fn(),
+} as unknown as MouseEvent<HTMLElement>;
+
+describe('useCopySpanLink', () => {
+	beforeEach(() => {
+		mockCopy.mockClear();
+		__setSearchParamsGetterForTest(
+			() => new URLSearchParams('tab=thread&spanId=old'),
+		);
+	});
+
+	afterEach(() => {
+		__resetSearchParamsGetter();
+	});
+
+	it('builds the link from the live URL, keeping its tab', () => {
+		const { result } = renderHook(() => useCopySpanLink({ span_id: 'new' }), {
+			wrapper,
+		});
+
+		result.current.onSpanCopy(clickEvent);
+
+		const link = new URL(mockCopy.mock.calls[0][0]);
+		expect(link.pathname).toBe('/trace/abc');
+		expect(link.searchParams.get('tab')).toBe('thread');
+		expect(link.searchParams.get('spanId')).toBe('new');
+	});
+});

frontend/src/hooks/trace/useCopySpanLink.ts

@@ -2,8 +2,8 @@ import { MouseEventHandler, useCallback } from 'react';
 import { useLocation } from 'react-router-dom';
 import { useCopyToClipboard } from 'react-use';
 import { toast } from '@signozhq/ui/sonner';
-import useUrlQuery from 'hooks/useUrlQuery';
 import { getAbsoluteUrl } from 'utils/basePath';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
 
 // Accepts both V2 (spanId) and V3 (span_id) span shapes
 // TODO: Remove V2 (spanId) support when phasing out V2
@@ -15,7 +15,6 @@ interface SpanLike {
 export const useCopySpanLink = (
 	span?: SpanLike,
 ): { onSpanCopy: MouseEventHandler<HTMLElement> } => {
-	const urlQuery = useUrlQuery();
 	const { pathname } = useLocation();
 	const [, setCopy] = useCopyToClipboard();
 
@@ -28,21 +27,22 @@ export const useCopySpanLink = (
 			event.preventDefault();
 			event.stopPropagation();
 
-			urlQuery.delete('spanId');
+			const params = getUnstableCurrentSearchParams();
+			params.delete('spanId');
 
 			const id = span.span_id || span.spanId;
 			if (id) {
-				urlQuery.set('spanId', id);
+				params.set('spanId', id);
 			}
 
-			const link = getAbsoluteUrl(`${pathname}?${urlQuery.toString()}`);
+			const link = getAbsoluteUrl(`${pathname}?${params.toString()}`);
 
 			setCopy(link);
 			toast.success('Copied to clipboard', {
 				position: 'top-right',
 			});
 		},
-		[span, urlQuery, pathname, setCopy],
+		[span, pathname, setCopy],
 	);
 
 	return {

frontend/src/pages/AlertDetails/AlertHeader/ActionButtons/ActionButtons.tsx

@@ -7,8 +7,8 @@ import { Switch } from '@signozhq/ui/switch';
 import { useIsDarkMode } from 'hooks/useDarkMode';
 import { Copy, Ellipsis, PenLine, Trash2 } from '@signozhq/icons';
 import {
+	useAlertRuleClone,
 	useAlertRuleDelete,
-	useAlertRuleDuplicate,
 	useAlertRuleStatusToggle,
 	useAlertRuleUpdate,
 } from 'pages/AlertDetails/hooks';
@@ -38,9 +38,7 @@ function AlertActionButtons({
 	const isDarkMode = useIsDarkMode();
 
 	const { handleAlertStateToggle } = useAlertRuleStatusToggle({ ruleId });
-	const { handleAlertDuplicate } = useAlertRuleDuplicate({
-		alertDetails: alertDetails as unknown as AlertDef,
-	});
+	const { handleAlertClone } = useAlertRuleClone({ ruleId });
 	const { handleAlertDelete } = useAlertRuleDelete({ ruleId });
 	const { handleAlertUpdate, isLoading } = useAlertRuleUpdate({
 		alertDetails: alertDetails as unknown as AlertDef,
@@ -72,10 +70,10 @@ function AlertActionButtons({
 	menuItems.push(
 		{
 			type: 'item',
-			value: 'duplicate-rule',
-			label: 'Duplicate',
+			value: 'clone-rule',
+			label: 'Clone',
 			prefix: <Copy size={16} color={Color.BG_VANILLA_400} />,
-			onClick: handleAlertDuplicate,
+			onClick: handleAlertClone,
 		},
 		{
 			type: 'item',

frontend/src/pages/AlertDetails/hooks.tsx

@@ -6,7 +6,7 @@ import type { FilterValue, SorterResult } from 'antd/es/table/interface';
 import { patchRulePartial } from 'api/alerts/patchRulePartial';
 import { convertToApiError } from 'api/ErrorResponseHandlerForGeneratedAPIs';
 import {
-	createRule,
+	cloneRuleByID,
 	deleteRuleByID,
 	getGetRuleByIDQueryKey,
 	getGetRuleHistoryTimelineQueryOptions,
@@ -17,7 +17,6 @@ import {
 	useGetRuleHistoryOverallStatus,
 	useGetRuleHistoryStats,
 	useGetRuleHistoryTopContributors,
-	useListRules,
 } from 'api/generated/services/rules';
 import {
 	Querybuildertypesv5OrderDirectionDTO,
@@ -478,39 +477,32 @@ export const useAlertRuleStatusToggle = ({
 	return { handleAlertStateToggle };
 };
 
-export const useAlertRuleDuplicate = ({
-	alertDetails,
+export const useAlertRuleClone = ({
+	ruleId,
 }: {
-	alertDetails: AlertDef;
+	ruleId: string;
 }): {
-	handleAlertDuplicate: () => void;
+	handleAlertClone: () => void;
 } => {
 	const { notifications } = useNotifications();
+	const queryClient = useQueryClient();
 
 	const params = useUrlQuery();
 
-	const { refetch } = useListRules({
-		query: { cacheTime: 0 },
-	});
 	const { showErrorModal } = useErrorModal();
-	const { mutate: duplicateAlert } = useMutation(
-		[REACT_QUERY_KEY.DUPLICATE_ALERT_RULE],
-		(args: { data: AlertDef }) =>
-			createRule(toPostableRuleDTOFromAlertDef(args.data)),
+	const { mutate: cloneAlert } = useMutation(
+		[REACT_QUERY_KEY.CLONE_ALERT_RULE],
+		() => cloneRuleByID({ id: ruleId }),
 		{
-			onSuccess: async () => {
+			onSuccess: async (response) => {
 				notifications.success({
 					message: `Success`,
 				});
 
-				const { data: allAlertsData } = await refetch();
+				await invalidateListRules(queryClient);
 
-				const rules = allAlertsData?.data;
-				if (rules && rules.length > 0) {
-					const clonedAlert = rules[rules.length - 1];
-					params.set(QueryParams.ruleId, String(clonedAlert.id));
-					history.push(`${ROUTES.ALERT_OVERVIEW}?${params.toString()}`);
-				}
+				params.set(QueryParams.ruleId, response.data.id);
+				history.push(`${ROUTES.ALERT_OVERVIEW}?${params.toString()}`);
 			},
 			onError: (error) =>
 				showErrorModal(
@@ -519,15 +511,13 @@ export const useAlertRuleDuplicate = ({
 		},
 	);
 
-	const handleAlertDuplicate = (): void => {
-		const args = {
-			data: { ...alertDetails, alert: alertDetails.alert?.concat(' - Copy') },
-		};
-		duplicateAlert(args);
+	const handleAlertClone = (): void => {
+		cloneAlert();
 	};
 
-	return { handleAlertDuplicate };
+	return { handleAlertClone };
 };
+
 export const useAlertRuleUpdate = ({
 	alertDetails,
 	setAlertRuleName,

frontend/src/pages/AlertList/AlertRules/stories/AlertRules.stories.mocks.tsx

@@ -107,7 +107,7 @@ export const alertRulesMocks = defineStoryMocks({
 			})),
 		),
 
-		rest.post('http://localhost/api/v2/rules', (_req, res, ctx) =>
+		rest.post('http://localhost/api/v2/rules/:id/clone', (_req, res, ctx) =>
 			actionResponse(values.cloneState, res, ctx, () => ({
 				status: 'success',
 				data: alertRulesResponse(1, {

frontend/src/pages/TraceDetailsV3/AIThreadMessage/AIMarkdown.tsx

@@ -0,0 +1,44 @@
+import ReactMarkdown, { uriTransformer } from 'react-markdown';
+import type { Components } from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+// Model output is untrusted: never add `rehype-raw`, so raw HTML renders as text.
+const MD_PLUGINS = [remarkGfm];
+const MD_COMPONENTS: Components = {
+	a: ({ node: _node, children, ...props }): JSX.Element => (
+		<a {...props} target="_blank" rel="noopener noreferrer">
+			{children}
+		</a>
+	),
+	// Images become links so viewing a message never fetches a third-party URL.
+	img: ({ src, alt }): JSX.Element => (
+		<a href={src} target="_blank" rel="noopener noreferrer">
+			{alt || src}
+		</a>
+	),
+};
+
+interface AIMarkdownProps {
+	content: string;
+	className?: string;
+}
+
+function AIMarkdown({ content, className }: AIMarkdownProps): JSX.Element {
+	return (
+		<ReactMarkdown
+			className={className}
+			remarkPlugins={MD_PLUGINS}
+			// Images render as links, so their URIs need the same sanitising links get.
+			transformImageUri={uriTransformer}
+			components={MD_COMPONENTS}
+		>
+			{content}
+		</ReactMarkdown>
+	);
+}
+
+AIMarkdown.defaultProps = {
+	className: undefined,
+};
+
+export default AIMarkdown;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/AIThreadMessage.module.scss

@@ -0,0 +1,376 @@
+// Design token Paragraph/Base/400.
+@mixin paragraph-base {
+	font-size: var(--periscope-font-size-base);
+	font-weight: var(--font-weight-normal);
+	line-height: var(--line-height-20);
+}
+
+.message {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-4);
+	min-width: 0;
+}
+
+.roleHeader {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-4);
+	color: var(--l1-foreground);
+}
+
+// Typography sets size, weight and line height; the mixin adds the rest.
+.roleLabel {
+	@include paragraph-base;
+}
+
+.parts {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-4);
+	min-width: 0;
+}
+
+.empty {
+	font-size: var(--periscope-font-size-base);
+	font-style: italic;
+	color: var(--l2-foreground);
+}
+
+.textBox {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-3);
+	padding: var(--spacing-3) var(--spacing-5);
+	border: 1px solid var(--l2-border);
+	border-radius: var(--radius-2);
+	background: var(--l2-background);
+	min-width: 0;
+}
+
+.text {
+	@include paragraph-base;
+
+	color: var(--l2-foreground);
+	word-break: break-word;
+
+	:global(p) {
+		margin: 0 0 var(--spacing-4);
+	}
+
+	:global(p:last-child) {
+		margin-bottom: 0;
+	}
+
+	:global(:is(ol, ul)) {
+		margin: 0 0 var(--spacing-4);
+		padding-left: var(--spacing-10);
+	}
+
+	:global(li::marker) {
+		color: var(--l2-foreground);
+	}
+
+	:global(:is(h1, h2, h3, h4, h5, h6)) {
+		margin: var(--spacing-6) 0 var(--spacing-4);
+		font-size: var(--periscope-font-size-base);
+		font-weight: var(--font-weight-semibold);
+		line-height: var(--line-height-20);
+		color: var(--l1-foreground);
+	}
+
+	:global(:is(h1, h2)) {
+		font-size: var(--periscope-font-size-medium);
+	}
+
+	:global(:is(h1, h2, h3, h4, h5, h6):first-child) {
+		margin-top: 0;
+	}
+
+	:global(strong) {
+		font-weight: var(--font-weight-semibold);
+		color: var(--l1-foreground);
+	}
+
+	:global(a) {
+		color: var(--accent-primary);
+		text-decoration: none;
+
+		&:hover {
+			text-decoration: underline;
+		}
+	}
+
+	:global(code:not(pre code)) {
+		padding: 0 var(--spacing-2);
+		border: 1px solid var(--l2-border);
+		border-radius: var(--radius-2);
+		background: var(--l3-background);
+		font-family: var(--font-mono);
+		font-size: 0.92em;
+		color: var(--l1-foreground);
+	}
+
+	:global(pre) {
+		position: relative;
+		margin: 0 0 var(--spacing-4);
+	}
+
+	// The highlighter sets its box with inline styles; syntax colours stay its own.
+	:global(pre > div:not(.code-copy-btn)) {
+		margin: 0 !important;
+		padding: var(--spacing-4) var(--spacing-5) !important;
+		border: 1px solid var(--l2-border);
+		border-radius: var(--radius-2) !important;
+		background: var(--l1-background) !important;
+		overflow-x: auto;
+	}
+
+	:global(pre code) {
+		font-family: var(--font-mono) !important;
+	}
+
+	:global(blockquote) {
+		margin: 0 0 var(--spacing-4);
+		padding-left: var(--spacing-5);
+		border-left: 2px solid var(--l3-border);
+		color: var(--l2-foreground);
+	}
+
+	:global(hr) {
+		margin: var(--spacing-6) 0;
+		border: none;
+		border-top: 1px solid var(--l2-border);
+	}
+}
+
+.showMore {
+	align-self: flex-start;
+	padding: 0;
+	border: none;
+	background: none;
+	font-size: var(--font-size-xs);
+	color: var(--primary);
+	cursor: pointer;
+}
+
+.chip {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--spacing-3);
+	align-self: flex-start;
+	max-width: 100%;
+	padding: var(--spacing-2) var(--spacing-4);
+	border-radius: var(--radius-2);
+	background: var(--l2-background);
+	color: var(--l2-foreground);
+	min-width: 0;
+
+	@include paragraph-base;
+
+	&.isPlain {
+		padding: 0;
+		background: none;
+	}
+}
+
+.dot {
+	flex-shrink: 0;
+	width: var(--spacing-3);
+	height: var(--spacing-3);
+	border-radius: var(--radius-round);
+
+	&[data-tone='success'] {
+		background: var(--accent-forest);
+	}
+
+	&[data-tone='warning'] {
+		background: var(--accent-amber);
+	}
+
+	&[data-tone='error'] {
+		background: var(--accent-cherry);
+	}
+
+	&[data-tone='info'] {
+		background: var(--accent-primary);
+	}
+}
+
+.chipLabel {
+	flex-shrink: 0;
+}
+
+.chipSeparator {
+	flex-shrink: 0;
+	color: var(--l2-foreground);
+}
+
+.chipValue {
+	display: inline-flex;
+	gap: var(--spacing-2);
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	min-width: 0;
+	color: var(--accent-primary);
+}
+
+.chipKey {
+	flex-shrink: 0;
+}
+
+.toolName {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	color: var(--accent-amber);
+}
+
+.toolCall,
+.toolResult {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-3);
+	min-width: 0;
+}
+
+.toolCall {
+	border-radius: var(--radius-2);
+	transition: outline-color 0.3s ease;
+	outline: 1px solid transparent;
+	outline-offset: var(--spacing-1);
+
+	&.isHighlighted {
+		outline-color: var(--primary);
+	}
+}
+
+.toolLink {
+	display: inline-flex;
+	align-self: flex-start;
+	max-width: 100%;
+	min-width: 0;
+	padding: 0;
+	border: none;
+	border-radius: var(--radius-2);
+	background: none;
+	font: inherit;
+	color: inherit;
+	text-align: left;
+	cursor: pointer;
+
+	&:hover {
+		.chip {
+			background: var(--l3-background);
+		}
+
+		.toolLinkIcon {
+			color: var(--primary);
+		}
+	}
+}
+
+.toolLinkIcon {
+	flex-shrink: 0;
+	color: var(--l2-foreground);
+}
+
+.collapsible {
+	min-width: 0;
+
+	:global(.ant-collapse-item) {
+		border: none;
+	}
+
+	:global(.ant-collapse-header) {
+		align-items: center !important;
+		gap: var(--spacing-2);
+		padding: 0 !important;
+		font-size: var(--font-size-xs);
+		color: var(--l2-foreground);
+	}
+
+	// Unboxed: the chevron sits right after the label.
+	:global(.ant-collapse-header-text) {
+		flex: none !important;
+		margin-inline-end: 0 !important;
+		color: var(--l2-foreground);
+
+		@include paragraph-base;
+	}
+
+	:global(.ant-collapse-expand-icon) {
+		height: auto !important;
+		padding-inline-start: 0 !important;
+	}
+
+	:global(.ant-collapse-content-box) {
+		display: flex;
+		flex-direction: column;
+		min-width: 0;
+		padding: var(--spacing-4) 0 0 !important;
+	}
+
+	&.boxed {
+		border: 1px solid var(--l2-border);
+		border-radius: var(--radius-2);
+		background: var(--l2-background);
+
+		:global(.ant-collapse-header) {
+			padding: var(--spacing-3) var(--spacing-5) !important;
+		}
+
+		:global(.ant-collapse-header-text) {
+			flex: auto !important;
+		}
+
+		:global(.ant-collapse-content-box) {
+			padding: 0 var(--spacing-5) var(--spacing-4) !important;
+		}
+
+		// The block is the box; nested text drops its own.
+		.textBox {
+			padding: 0;
+			border: none;
+			background: none;
+		}
+	}
+}
+
+.collapsibleChevron {
+	display: flex;
+	color: var(--l2-foreground);
+}
+
+.jsonBlock {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-3);
+	min-width: 0;
+}
+
+.json {
+	position: relative;
+	min-width: 0;
+	padding: var(--spacing-3) var(--spacing-4);
+	border: 1px solid var(--l2-border);
+	border-radius: var(--radius-2);
+	cursor: auto;
+
+	:global(.pretty-view) {
+		padding: 0;
+	}
+}
+
+.jsonCollapsed {
+	overflow: hidden;
+}
+
+.jsonCopy {
+	position: absolute;
+	top: var(--spacing-2);
+	right: var(--spacing-2);
+	z-index: 1;
+}

frontend/src/pages/TraceDetailsV3/AIThreadMessage/AIThreadMessage.tsx

@@ -0,0 +1,98 @@
+import { Badge } from '@signozhq/ui/badge';
+
+import { MessageType, ThreadMessage } from './types';
+import CollapsibleBlock from './CollapsibleBlock';
+import MessagePart from './MessagePart';
+import PartChip from './PartChip';
+import RoleLabel from './RoleLabel';
+import { getFinishReasonTone, getRoleLabel } from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+export interface AIThreadMessageProps {
+	message: ThreadMessage;
+	messageType?: MessageType;
+	canLinkToToolCall?: (toolCallKey: string) => boolean;
+	onToolLinkClick?: (toolCallKey: string) => void;
+}
+
+function AIThreadMessage({
+	message,
+	messageType,
+	canLinkToToolCall,
+	onToolLinkClick,
+}: AIThreadMessageProps): JSX.Element {
+	const { role, parts: messageParts, finish_reason: finishReason } = message;
+	const roleLabel = getRoleLabel(role);
+	const tone = getFinishReasonTone(finishReason);
+	const isOutput = messageType === MessageType.Output;
+
+	const parts = (
+		<div className={styles.parts}>
+			{messageParts.length === 0 ? (
+				<span className={styles.empty}>No content</span>
+			) : (
+				messageParts.map((part, index) => (
+					<MessagePart
+						// eslint-disable-next-line react/no-array-index-key
+						key={index}
+						part={part}
+						canLinkToToolCall={canLinkToToolCall}
+						onToolLinkClick={onToolLinkClick}
+					/>
+				))
+			)}
+		</div>
+	);
+
+	return (
+		<div
+			className={styles.message}
+			data-testid={`ai-thread-message-${role || 'unknown'}`}
+		>
+			{role === 'system' || role === 'developer' ? (
+				<CollapsibleBlock
+					label={roleLabel && <RoleLabel label={roleLabel} />}
+					testId="ai-message-system-toggle"
+				>
+					{parts}
+				</CollapsibleBlock>
+			) : (
+				<>
+					{(roleLabel || isOutput) && (
+						<div className={styles.roleHeader}>
+							{roleLabel && <RoleLabel label={roleLabel} />}
+							{isOutput && (
+								<Badge
+									variant="outlined"
+									color="secondary"
+									textTransform="none"
+									testId="ai-message-output-badge"
+								>
+									Output
+								</Badge>
+							)}
+						</div>
+					)}
+					{parts}
+				</>
+			)}
+			{finishReason && (
+				<PartChip
+					label="Finish Reason"
+					value={finishReason}
+					tone={tone}
+					testId="ai-message-finish-reason"
+				/>
+			)}
+		</div>
+	);
+}
+
+AIThreadMessage.defaultProps = {
+	messageType: MessageType.Input,
+	canLinkToToolCall: undefined,
+	onToolLinkClick: undefined,
+};
+
+export default AIThreadMessage;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/CollapsibleBlock.tsx

@@ -0,0 +1,54 @@
+import { MouseEvent, ReactNode } from 'react';
+import { ChevronDown, ChevronUp } from '@signozhq/icons';
+import { Collapse } from 'antd';
+import cx from 'classnames';
+
+import styles from './AIThreadMessage.module.scss';
+
+const PANEL_KEY = 'content';
+
+interface CollapsibleBlockProps {
+	label: ReactNode;
+	// Boxed: full-width bordered row with the chevron on the right.
+	isBoxed?: boolean;
+	testId?: string;
+	children: ReactNode;
+}
+
+function CollapsibleBlock({
+	label,
+	isBoxed = false,
+	testId,
+	children,
+}: CollapsibleBlockProps): JSX.Element {
+	// Toggling must not count as a click on the message card; the body still does.
+	const stopToggleFromSelectingCard = (event: MouseEvent): void => {
+		if ((event.target as HTMLElement).closest('.ant-collapse-header')) {
+			event.stopPropagation();
+		}
+	};
+
+	return (
+		// eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+		<div onClick={stopToggleFromSelectingCard}>
+			<Collapse
+				ghost
+				className={cx(styles.collapsible, isBoxed && styles.boxed)}
+				expandIconPosition="end"
+				expandIcon={({ isActive }): JSX.Element => (
+					<span className={styles.collapsibleChevron} data-testid={testId}>
+						{isActive ? <ChevronUp size={12} /> : <ChevronDown size={12} />}
+					</span>
+				)}
+				items={[{ key: PANEL_KEY, label, children }]}
+			/>
+		</div>
+	);
+}
+
+CollapsibleBlock.defaultProps = {
+	isBoxed: false,
+	testId: undefined,
+};
+
+export default CollapsibleBlock;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/ExpandableText.tsx

@@ -0,0 +1,39 @@
+import { MouseEvent, useState } from 'react';
+
+import AIMarkdown from './AIMarkdown';
+import { MAX_TEXT_LENGTH } from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+interface ExpandableTextProps {
+	text: string;
+}
+
+function ExpandableText({ text }: ExpandableTextProps): JSX.Element {
+	const [isExpanded, setIsExpanded] = useState(false);
+	const isTruncated = !isExpanded && text.length > MAX_TEXT_LENGTH;
+	const visibleText = isTruncated ? `${text.slice(0, MAX_TEXT_LENGTH)}…` : text;
+
+	const handleToggle = (event: MouseEvent): void => {
+		event.stopPropagation();
+		setIsExpanded((prev) => !prev);
+	};
+
+	return (
+		<>
+			<AIMarkdown className={styles.text} content={visibleText} />
+			{text.length > MAX_TEXT_LENGTH && (
+				<button
+					type="button"
+					className={styles.showMore}
+					onClick={handleToggle}
+					data-testid="ai-message-show-more"
+				>
+					{isExpanded ? 'Show less' : 'Show more'}
+				</button>
+			)}
+		</>
+	);
+}
+
+export default ExpandableText;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/JsonBlock.tsx

@@ -0,0 +1,79 @@
+import { MouseEvent, useMemo, useRef, useState } from 'react';
+import cx from 'classnames';
+import CopyButton from 'periscope/components/CopyButton/CopyButton';
+import { PrettyView } from 'periscope/components/PrettyView';
+import { useResizeObserver } from 'hooks/useDimensions';
+
+import styles from './AIThreadMessage.module.scss';
+
+// Branch toggles (arrow, key, summary); PrettyView already stops its actions menu.
+const TREE_TOGGLES = '.pretty-view__nested-row > :not(ul)';
+const NO_ACTIONS = { leaf: [], nested: [] };
+// 10 tree rows: 18px line-height plus 2px padding top and bottom.
+const COLLAPSED_MAX_HEIGHT = 10 * 22;
+
+interface JsonBlockProps {
+	data: object;
+}
+
+// Expanding tree nodes must not count as a click on the message.
+function JsonBlock({ data }: JsonBlockProps): JSX.Element {
+	const [isExpanded, setIsExpanded] = useState(false);
+	const text = useMemo(() => JSON.stringify(data, null, 2), [data]);
+	const treeRef = useRef<HTMLDivElement>(null);
+	const { height: treeHeight } = useResizeObserver(treeRef);
+	const isLong = treeHeight > COLLAPSED_MAX_HEIGHT;
+	const isClamped = isLong && !isExpanded;
+
+	const stopTreeToggleFromSelectingCard = (event: MouseEvent): void => {
+		if ((event.target as HTMLElement).closest(TREE_TOGGLES)) {
+			event.stopPropagation();
+		}
+	};
+
+	const handleToggle = (event: MouseEvent): void => {
+		event.stopPropagation();
+		setIsExpanded((prev) => !prev);
+	};
+
+	return (
+		<div className={styles.jsonBlock}>
+			{/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions */}
+			<div
+				className={cx(styles.json, isClamped && styles.jsonCollapsed)}
+				style={isClamped ? { maxHeight: COLLAPSED_MAX_HEIGHT } : undefined}
+				onClick={stopTreeToggleFromSelectingCard}
+				data-testid="ai-json-block"
+			>
+				<span className={styles.jsonCopy}>
+					<CopyButton
+						value={text}
+						size={12}
+						ariaLabel="Copy JSON"
+						testId="ai-json-copy"
+					/>
+				</span>
+				<div ref={treeRef}>
+					<PrettyView
+						data={data as Record<string, unknown>}
+						searchable={false}
+						drawerKey="ai-thread-message"
+						visibleActions={NO_ACTIONS}
+					/>
+				</div>
+			</div>
+			{isLong && (
+				<button
+					type="button"
+					className={styles.showMore}
+					onClick={handleToggle}
+					data-testid="ai-json-show-more"
+				>
+					{isExpanded ? 'Show less' : 'Show more'}
+				</button>
+			)}
+		</div>
+	);
+}
+
+export default JsonBlock;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/MessagePart.tsx

@@ -0,0 +1,105 @@
+import { MessagePart as MessagePartType } from './types';
+import JsonBlock from './JsonBlock';
+import ThinkingPart from './parts/ThinkingPart';
+import ToolCallPart from './parts/ToolCallPart';
+import ToolResultPart from './parts/ToolResultPart';
+import TextContent from './TextContent';
+import {
+	isEmptyPart,
+	toDisplayText,
+	toToolCallKey,
+	truncateBlobContent,
+} from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+const EMPTY_PART = (
+	<span className={styles.empty} data-testid="ai-message-empty-part">
+		No content
+	</span>
+);
+
+interface MessagePartProps {
+	part: MessagePartType;
+	canLinkToToolCall?: (toolCallKey: string) => boolean;
+	onToolLinkClick?: (toolCallKey: string) => void;
+}
+
+function MessagePart({
+	part,
+	canLinkToToolCall,
+	onToolLinkClick,
+}: MessagePartProps): JSX.Element {
+	if (isEmptyPart(part)) {
+		return EMPTY_PART;
+	}
+	switch (part.type) {
+		case 'text':
+			return <TextContent text={part.content} />;
+		case 'reasoning':
+			return <ThinkingPart content={part.content} />;
+		case 'compaction':
+			return (
+				<ThinkingPart
+					label="Compaction"
+					content={part.content ?? undefined}
+					testId="ai-message-compaction-toggle"
+				/>
+			);
+		case 'tool_call':
+			return (
+				<ToolCallPart
+					id={part.id ?? ''}
+					name={part.name ?? ''}
+					args={part.arguments}
+					type={part.type}
+				/>
+			);
+		case 'server_tool_call':
+			return (
+				<ToolCallPart
+					id={part.id ?? ''}
+					name={part.name ?? ''}
+					args={part.server_tool_call}
+					type={part.type}
+				/>
+			);
+		case 'tool_call_response':
+		case 'server_tool_call_response': {
+			const toolCallId = part.id ?? '';
+			const toolCallKey = toToolCallKey(
+				toolCallId,
+				part.type === 'server_tool_call_response',
+			);
+			return (
+				<ToolResultPart
+					toolCallId={toolCallId}
+					toolCallKey={toolCallKey}
+					type={part.type}
+					content={toDisplayText(
+						part.type === 'tool_call_response'
+							? part.response
+							: part.server_tool_call_response,
+					)}
+					isLinkEnabled={!!toolCallId && !!canLinkToToolCall?.(toolCallKey)}
+					onLinkClick={onToolLinkClick}
+				/>
+			);
+		}
+		case 'blob':
+		case 'file':
+		case 'uri':
+			return <JsonBlock data={truncateBlobContent(part)} />;
+		case 'generic':
+			return <TextContent text={toDisplayText(part.content)} />;
+		default:
+			return <TextContent text={toDisplayText(part)} />;
+	}
+}
+
+MessagePart.defaultProps = {
+	canLinkToToolCall: undefined,
+	onToolLinkClick: undefined,
+};
+
+export default MessagePart;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/PartChip.tsx

@@ -0,0 +1,52 @@
+import { ReactNode } from 'react';
+import cx from 'classnames';
+
+import { MessageTone } from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+interface PartChipProps {
+	label: string;
+	value?: ReactNode;
+	tone?: MessageTone;
+	// Plain: no chip background, for headers like a tool call's.
+	isPlain?: boolean;
+	testId?: string;
+	children?: ReactNode;
+}
+
+function PartChip({
+	label,
+	value,
+	tone = 'success',
+	isPlain = false,
+	testId,
+	children,
+}: PartChipProps): JSX.Element {
+	return (
+		<span
+			className={cx(styles.chip, isPlain && styles.isPlain)}
+			data-testid={testId}
+		>
+			<span className={styles.dot} data-tone={tone} />
+			<span className={styles.chipLabel}>{label}</span>
+			{value !== undefined && (
+				<>
+					<span className={styles.chipSeparator}>—</span>
+					<span className={styles.chipValue}>{value}</span>
+				</>
+			)}
+			{children}
+		</span>
+	);
+}
+
+PartChip.defaultProps = {
+	value: undefined,
+	tone: 'success',
+	isPlain: false,
+	testId: undefined,
+	children: undefined,
+};
+
+export default PartChip;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/RoleLabel.tsx

@@ -0,0 +1,17 @@
+import { Typography } from '@signozhq/ui/typography';
+
+import styles from './AIThreadMessage.module.scss';
+
+interface RoleLabelProps {
+	label: string;
+}
+
+function RoleLabel({ label }: RoleLabelProps): JSX.Element {
+	return (
+		<Typography.Text size="base" weight="normal" className={styles.roleLabel}>
+			{label}
+		</Typography.Text>
+	);
+}
+
+export default RoleLabel;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/TextContent.tsx

@@ -0,0 +1,27 @@
+import { useMemo } from 'react';
+
+import ExpandableText from './ExpandableText';
+import JsonBlock from './JsonBlock';
+import { parseJsonObject } from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+interface TextContentProps {
+	text: string;
+}
+
+/** Renders JSON text as a tree, anything else as markdown. */
+function TextContent({ text }: TextContentProps): JSX.Element {
+	const json = useMemo(() => parseJsonObject(text), [text]);
+
+	if (json) {
+		return <JsonBlock data={json} />;
+	}
+	return (
+		<div className={styles.textBox}>
+			<ExpandableText text={text} />
+		</div>
+	);
+}
+
+export default TextContent;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/__tests__/AIThreadMessage.test.tsx

@@ -0,0 +1,97 @@
+import { render, screen, userEvent } from 'tests/test-utils';
+
+import AIThreadMessage from '../AIThreadMessage';
+import JsonBlock from '../JsonBlock';
+import { MessageType } from '../types';
+
+// jsdom has no layout, so the tree height JsonBlock measures is set per test.
+let mockTreeHeight = 0;
+jest.mock('hooks/useDimensions', () => ({
+	useResizeObserver: (): { width: number; height: number } => ({
+		width: 0,
+		height: mockTreeHeight,
+	}),
+}));
+
+beforeEach(() => {
+	mockTreeHeight = 0;
+});
+
+describe('AIThreadMessage', () => {
+	it('shows the Output badge when the message has no role', () => {
+		render(
+			<AIThreadMessage
+				message={{ parts: [{ type: 'text', content: 'hi' }] }}
+				messageType={MessageType.Output}
+			/>,
+		);
+
+		expect(screen.getByTestId('ai-message-output-badge')).toBeInTheDocument();
+	});
+
+	it.each([
+		['blank text', { type: 'text' as const, content: '  ' }],
+		['empty generic', { type: 'generic' as const, content: '' }],
+	])('renders No content for a %s part', (_label, part) => {
+		render(<AIThreadMessage message={{ role: 'user', parts: [part] }} />);
+
+		expect(screen.getByTestId('ai-message-empty-part')).toHaveTextContent(
+			'No content',
+		);
+	});
+
+	it('hides system message parts until the toggle is clicked', async () => {
+		const user = userEvent.setup();
+		render(
+			<AIThreadMessage
+				message={{ role: 'system', parts: [{ type: 'text', content: 'be brief' }] }}
+			/>,
+		);
+
+		expect(screen.queryByText('be brief')).not.toBeInTheDocument();
+		await user.click(screen.getByTestId('ai-message-system-toggle'));
+		expect(screen.getByText('be brief')).toBeInTheDocument();
+	});
+
+	it('shows the finish reason', () => {
+		render(
+			<AIThreadMessage
+				message={{
+					role: 'assistant',
+					parts: [{ type: 'text', content: 'hi' }],
+					finish_reason: 'stop',
+				}}
+			/>,
+		);
+
+		expect(screen.getByTestId('ai-message-finish-reason')).toHaveTextContent(
+			'stop',
+		);
+	});
+});
+
+describe('JsonBlock', () => {
+	it('collapses JSON taller than 10 rows behind Show more', async () => {
+		mockTreeHeight = 300;
+		const user = userEvent.setup();
+		render(<JsonBlock data={{ a: 1 }} />);
+
+		const toggle = screen.getByTestId('ai-json-show-more');
+		expect(toggle).toHaveTextContent('Show more');
+		await user.click(toggle);
+		expect(toggle).toHaveTextContent('Show less');
+	});
+
+	it('does not collapse JSON of 10 rows or fewer', () => {
+		mockTreeHeight = 220;
+		render(<JsonBlock data={{ a: 1 }} />);
+
+		expect(screen.queryByTestId('ai-json-show-more')).not.toBeInTheDocument();
+	});
+
+	it('renders a copy button', () => {
+		render(<JsonBlock data={{ a: 1 }} />);
+
+		expect(screen.getByTestId('ai-json-copy')).toBeInTheDocument();
+	});
+});

frontend/src/pages/TraceDetailsV3/AIThreadMessage/parts/ThinkingPart.tsx

@@ -0,0 +1,34 @@
+import CollapsibleBlock from '../CollapsibleBlock';
+import TextContent from '../TextContent';
+
+import styles from '../AIThreadMessage.module.scss';
+
+interface ThinkingPartProps {
+	content?: string;
+	label?: string;
+	testId?: string;
+}
+
+function ThinkingPart({
+	content,
+	label = 'Thinking',
+	testId = 'ai-message-thinking-toggle',
+}: ThinkingPartProps): JSX.Element {
+	return (
+		<CollapsibleBlock label={label} isBoxed testId={testId}>
+			{content ? (
+				<TextContent text={content} />
+			) : (
+				<span className={styles.empty}> - </span>
+			)}
+		</CollapsibleBlock>
+	);
+}
+
+ThinkingPart.defaultProps = {
+	content: undefined,
+	label: 'Thinking',
+	testId: 'ai-message-thinking-toggle',
+};
+
+export default ThinkingPart;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/parts/ToolCallPart.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import JsonBlock from '../JsonBlock';
+import PartChip from '../PartChip';
+import { parseJsonObject, TOOL_CALL_ID_ATTR, toToolCallKey } from '../utils';
+
+import styles from '../AIThreadMessage.module.scss';
+
+interface ToolCallPartProps {
+	id: string;
+	name: string;
+	args: unknown;
+	type: 'tool_call' | 'server_tool_call';
+}
+
+function ToolCallPart({
+	id,
+	name,
+	args,
+	type,
+}: ToolCallPartProps): JSX.Element {
+	// Streamed calls can carry truncated, unparseable argument strings.
+	const json = useMemo(() => {
+		if (typeof args === 'string') {
+			return parseJsonObject(args);
+		}
+		return typeof args === 'object' && args !== null ? args : undefined;
+	}, [args]);
+
+	const toolCallAttr = {
+		[TOOL_CALL_ID_ATTR]: toToolCallKey(id, type === 'server_tool_call'),
+	};
+
+	return (
+		<div className={styles.toolCall} {...toolCallAttr} data-testid="ai-tool-call">
+			<PartChip
+				label={type}
+				tone="info"
+				isPlain
+				value={
+					<>
+						<span className={styles.chipKey}>name :</span>
+						<span className={styles.toolName}>{name}</span>
+					</>
+				}
+			/>
+			{json ? (
+				<JsonBlock data={json} />
+			) : (
+				<span className={styles.empty}> - </span>
+			)}
+		</div>
+	);
+}
+
+export default ToolCallPart;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/parts/ToolResultPart.tsx

@@ -0,0 +1,80 @@
+import { MouseEvent, useMemo } from 'react';
+import { CornerUpRight } from '@signozhq/icons';
+
+import PartChip from '../PartChip';
+import TextContent from '../TextContent';
+import { MAX_INLINE_RESULT_LENGTH, parseJsonObject } from '../utils';
+
+import styles from '../AIThreadMessage.module.scss';
+
+interface ToolResultPartProps {
+	toolCallId: string;
+	toolCallKey: string;
+	type: 'tool_call_response' | 'server_tool_call_response';
+	name?: string;
+	content: string;
+	isError?: boolean;
+	isLinkEnabled: boolean;
+	onLinkClick?: (toolCallKey: string) => void;
+}
+
+function ToolResultPart({
+	toolCallId,
+	toolCallKey,
+	type,
+	name,
+	content,
+	isError,
+	isLinkEnabled,
+	onLinkClick,
+}: ToolResultPartProps): JSX.Element {
+	// Short plain results fit in the chip; JSON or long ones render below it.
+	const isInline = useMemo(
+		() => content.length <= MAX_INLINE_RESULT_LENGTH && !parseJsonObject(content),
+		[content],
+	);
+
+	const handleLinkClick = (event: MouseEvent): void => {
+		event.stopPropagation();
+		onLinkClick?.(toolCallKey);
+	};
+
+	const chip = (
+		<PartChip
+			label={type}
+			value={isInline ? content || '…' : name || toolCallId}
+			tone={isError ? 'error' : 'success'}
+		>
+			{isLinkEnabled && (
+				<CornerUpRight size={12} className={styles.toolLinkIcon} />
+			)}
+		</PartChip>
+	);
+
+	return (
+		<div className={styles.toolResult} data-testid="ai-tool-result">
+			{isLinkEnabled ? (
+				<button
+					type="button"
+					className={styles.toolLink}
+					onClick={handleLinkClick}
+					title="Go to tool call"
+					data-testid="ai-tool-result-link"
+				>
+					{chip}
+				</button>
+			) : (
+				chip
+			)}
+			{!isInline && <TextContent text={content} />}
+		</div>
+	);
+}
+
+ToolResultPart.defaultProps = {
+	name: undefined,
+	isError: false,
+	onLinkClick: undefined,
+};
+
+export default ToolResultPart;

frontend/src/pages/TraceDetailsV3/AIThreadMessage/types.ts

@@ -0,0 +1,58 @@
+import type {
+	AiobservabilitytypesBlobPartDTO,
+	AiobservabilitytypesCompactionPartDTO,
+	AiobservabilitytypesFilePartDTO,
+	AiobservabilitytypesOutputMessageDTO,
+	AiobservabilitytypesReasoningPartDTO,
+	AiobservabilitytypesServerToolCallPartDTO,
+	AiobservabilitytypesServerToolCallResponsePartDTO,
+	AiobservabilitytypesTextPartDTO,
+	AiobservabilitytypesToolCallRequestPartDTO,
+	AiobservabilitytypesToolCallResponsePartDTO,
+	AiobservabilitytypesUriPartDTO,
+} from 'api/generated/services/sigNoz.schemas';
+
+// Generated enum `type`s as string literals, so `part.type === 'text'` narrows.
+type Part<T extends { type: string }> = Omit<T, 'type'> & {
+	type: `${T['type']}`;
+};
+
+// Keys the schema marks required may still be missing.
+type LoosePart<T extends { type: string }> = Partial<Omit<T, 'type'>> & {
+	type: `${T['type']}`;
+};
+
+/** OTel GenAI message part; `text` content is always normalised to a string. */
+export type MessagePart =
+	| Part<AiobservabilitytypesTextPartDTO>
+	| LoosePart<AiobservabilitytypesReasoningPartDTO>
+	| LoosePart<AiobservabilitytypesCompactionPartDTO>
+	| LoosePart<AiobservabilitytypesToolCallRequestPartDTO>
+	| LoosePart<AiobservabilitytypesToolCallResponsePartDTO>
+	| LoosePart<AiobservabilitytypesServerToolCallPartDTO>
+	| LoosePart<AiobservabilitytypesServerToolCallResponsePartDTO>
+	| LoosePart<AiobservabilitytypesBlobPartDTO>
+	| LoosePart<AiobservabilitytypesFilePartDTO>
+	| LoosePart<AiobservabilitytypesUriPartDTO>
+	// The API's generic part is an untyped index signature, which defeats narrowing on `type`.
+	| { type: 'generic'; content?: unknown };
+
+export type MessagePartType = MessagePart['type'];
+
+export type MediaMessagePart = Extract<
+	MessagePart,
+	{ type: 'blob' | 'file' | 'uri' }
+>;
+
+// role: system | developer | user | assistant | tool; any other value renders headerless.
+// finish_reason: stop | tool_call | length | content_filter | compaction | error, or provider-specific.
+export type ThreadMessage = Partial<
+	Omit<AiobservabilitytypesOutputMessageDTO, 'parts'>
+> & {
+	parts: MessagePart[];
+};
+
+export enum MessageType {
+	Input = 'input',
+	Output = 'output',
+}

frontend/src/pages/TraceDetailsV3/AIThreadMessage/useToolCallLinks.ts

@@ -0,0 +1,43 @@
+import { RefObject, useCallback } from 'react';
+
+import { TOOL_CALL_ID_ATTR } from './utils';
+
+import styles from './AIThreadMessage.module.scss';
+
+const HIGHLIGHT_MS = 1500;
+
+interface ToolCallLinks {
+	canLinkToToolCall: (toolCallKey: string) => boolean;
+	onToolLinkClick: (toolCallKey: string) => void;
+}
+
+/** Links tool results to their calls in `rootRef`; enabled only for keys in `toolCallKeys`. */
+export function useToolCallLinks(
+	rootRef: RefObject<HTMLElement>,
+	toolCallKeys: Set<string>,
+): ToolCallLinks {
+	const canLinkToToolCall = useCallback(
+		(toolCallKey: string): boolean => toolCallKeys.has(toolCallKey),
+		[toolCallKeys],
+	);
+
+	const onToolLinkClick = useCallback(
+		(toolCallKey: string): void => {
+			const target = rootRef.current?.querySelector<HTMLElement>(
+				`[${TOOL_CALL_ID_ATTR}="${CSS.escape(toolCallKey)}"]`,
+			);
+			if (!target) {
+				return;
+			}
+			target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+			target.classList.add(styles.isHighlighted);
+			window.setTimeout(
+				() => target.classList.remove(styles.isHighlighted),
+				HIGHLIGHT_MS,
+			);
+		},
+		[rootRef],
+	);
+
+	return { canLinkToToolCall, onToolLinkClick };
+}

frontend/src/pages/TraceDetailsV3/AIThreadMessage/utils.ts

@@ -0,0 +1,96 @@
+import { attempt, isError, isObjectLike } from 'lodash-es';
+
+import { MediaMessagePart, MessagePart, ThreadMessage } from './types';
+
+export const MAX_TEXT_LENGTH = 1000;
+
+const MAX_BLOB_PREVIEW_LENGTH = 100;
+
+export const MAX_INLINE_RESULT_LENGTH = 80;
+
+export const TOOL_CALL_ID_ATTR = 'data-tool-call-id';
+
+const ROLE_LABELS: Record<string, string> = {
+	system: 'System',
+	developer: 'Developer',
+	user: 'User',
+	assistant: 'Assistant',
+	tool: 'Tool',
+};
+
+export type MessageTone = 'success' | 'warning' | 'error' | 'info';
+
+// Provider values the backend could not map fall back to info.
+const FINISH_REASON_TONES: Record<string, MessageTone> = {
+	stop: 'success',
+	tool_call: 'success',
+	length: 'warning',
+	content_filter: 'warning',
+	compaction: 'info',
+	error: 'error',
+};
+
+/** Undefined for missing or unknown roles, which render headerless. */
+export function getRoleLabel(role?: string): string | undefined {
+	return role ? ROLE_LABELS[role] : undefined;
+}
+
+export function getFinishReasonTone(reason?: string | null): MessageTone {
+	return (reason && FINISH_REASON_TONES[reason.toLowerCase()]) || 'info';
+}
+
+/** Parses objects and arrays only; scalars and invalid JSON return undefined. */
+export function parseJsonObject(text: string): object | undefined {
+	const parsed: unknown = attempt(JSON.parse, text);
+	return isObjectLike(parsed) && !isError(parsed)
+		? (parsed as object)
+		: undefined;
+}
+
+export function toDisplayText(value: unknown): string {
+	if (value === undefined || value === null) {
+		return '';
+	}
+	return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+}
+
+/** Text and generic parts with only whitespace have nothing to render. */
+export function isEmptyPart(part: MessagePart): boolean {
+	if (part.type === 'text') {
+		return part.content.trim() === '';
+	}
+	if (part.type === 'generic') {
+		return toDisplayText(part.content).trim() === '';
+	}
+	return false;
+}
+
+/** Blob content is inline base64; only a prefix is shown. */
+export function truncateBlobContent(part: MediaMessagePart): MediaMessagePart {
+	if (
+		part.type !== 'blob' ||
+		!part.content ||
+		part.content.length <= MAX_BLOB_PREVIEW_LENGTH
+	) {
+		return part;
+	}
+	return {
+		...part,
+		content: `${part.content.slice(0, MAX_BLOB_PREVIEW_LENGTH)}…`,
+	};
+}
+
+// Server and client calls can share an id, so links match on kind too.
+export function toToolCallKey(id: string, isServer: boolean): string {
+	return `${isServer ? 'server' : 'client'}:${id}`;
+}
+
+export function collectToolCallKeys(messages: ThreadMessage[]): string[] {
+	return messages.flatMap((message) =>
+		message.parts.flatMap((part) =>
+			(part.type === 'tool_call' || part.type === 'server_tool_call') && part.id
+				? [toToolCallKey(part.id, part.type === 'server_tool_call')]
+				: [],
+		),
+	);
+}

frontend/src/pages/TraceDetailsV3/EntityMetadata/EntityMetadataItem.tsx

@@ -16,7 +16,8 @@ function EntityMetadataItem({
 	children,
 }: EntityMetadataItemProps): JSX.Element {
 	return (
-		<Tooltip title={tooltip}>
+		// Below the row: above it the tooltip covers the Overview / Thread tabs.
+		<Tooltip title={tooltip} side="bottom">
 			<span className={styles.item}>
 				{icon}
 				<Typography.Text as="span">{children}</Typography.Text>

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanAIMessages/MessagesAccordion.module.scss

@@ -0,0 +1,46 @@
+@use '../../../../styles/scrollbar' as *;
+
+.accordion {
+	border: 1px solid var(--l2-border);
+	border-radius: var(--radius-2);
+	background: var(--l2-background);
+
+	// Direct children only, so nested collapses keep their own styles.
+	> :global(.ant-collapse-item) {
+		border: none;
+	}
+
+	> :global(.ant-collapse-item > .ant-collapse-header) {
+		align-items: center !important;
+		height: 40px;
+		padding: 0 var(--spacing-4) !important;
+	}
+
+	> :global(.ant-collapse-item > .ant-collapse-content) {
+		background: transparent;
+		border-top: 1px solid var(--l2-border);
+	}
+
+	> :global(
+		.ant-collapse-item > .ant-collapse-content > .ant-collapse-content-box
+	) {
+		@include custom-scrollbar;
+
+		max-height: 150px;
+		overflow-y: auto;
+		padding: var(--spacing-4) !important;
+	}
+}
+
+.title {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-2);
+	font-size: var(--periscope-font-size-base);
+	color: var(--l1-foreground);
+}
+
+.chevron {
+	display: flex;
+	color: var(--l2-foreground);
+}

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanAIMessages/MessagesAccordion.tsx

@@ -0,0 +1,102 @@
+import { MouseEvent, ReactNode, useState } from 'react';
+import { ChevronDown, ChevronUp } from '@signozhq/icons';
+import { Collapse } from 'antd';
+
+import { AIThreadMessageProps } from '../../AIThreadMessage/AIThreadMessage';
+import { ThreadMessage } from '../../AIThreadMessage/types';
+import MessagesSection from '../../SpanMessages/MessagesSection';
+import { RawMessagesValue } from '../../utils/spanMessages';
+import { ThreadView } from '../../TraceDetailsThread/types';
+import ThreadViewToggle from '../../TraceDetailsThread/ThreadViewToggle';
+
+import styles from './MessagesAccordion.module.scss';
+
+const PANEL_KEY = 'messages';
+
+interface MessagesAccordionProps extends Pick<
+	AIThreadMessageProps,
+	'messageType' | 'canLinkToToolCall' | 'onToolLinkClick'
+> {
+	icon: ReactNode;
+	title: string;
+	messages: ThreadMessage[];
+	raw?: RawMessagesValue;
+	testId: string;
+}
+
+function MessagesAccordion({
+	icon,
+	title,
+	messages,
+	raw,
+	testId,
+	messageType,
+	canLinkToToolCall,
+	onToolLinkClick,
+}: MessagesAccordionProps): JSX.Element | null {
+	const [isOpen, setIsOpen] = useState(false);
+	const [view, setView] = useState(ThreadView.Formatted);
+	const canFormat = messages.length > 0;
+	const effectiveView = canFormat ? view : ThreadView.Json;
+
+	if (!canFormat && !raw) {
+		return null;
+	}
+
+	const stopToggle = (event: MouseEvent): void => event.stopPropagation();
+
+	return (
+		<section data-testid={testId}>
+			<Collapse
+				className={styles.accordion}
+				activeKey={isOpen ? [PANEL_KEY] : []}
+				onChange={(): void => setIsOpen((prev) => !prev)}
+				expandIconPosition="end"
+				expandIcon={({ isActive }): JSX.Element => (
+					<span className={styles.chevron} data-testid={`${testId}-toggle`}>
+						{isActive ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
+					</span>
+				)}
+				items={[
+					{
+						key: PANEL_KEY,
+						label: (
+							<span className={styles.title}>
+								{icon}
+								{title}
+							</span>
+						),
+						extra: isOpen && canFormat && (
+							// The view toggle lives in the header; its clicks must not fold the panel.
+							// eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+							<span onClick={stopToggle}>
+								<ThreadViewToggle
+									value={effectiveView}
+									onChange={setView}
+									testId={`${testId}-view-toggle`}
+								/>
+							</span>
+						),
+						children: (
+							<MessagesSection
+								view={effectiveView}
+								messages={messages}
+								raw={raw}
+								testId={`${testId}-body`}
+								messageType={messageType}
+								canLinkToToolCall={canLinkToToolCall}
+								onToolLinkClick={onToolLinkClick}
+							/>
+						),
+					},
+				]}
+			/>
+		</section>
+	);
+}
+
+MessagesAccordion.defaultProps = {
+	raw: undefined,
+};
+
+export default MessagesAccordion;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanAIMessages/SpanAIMessages.module.scss

@@ -0,0 +1,7 @@
+.root {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-4);
+	flex-shrink: 0;
+	min-width: 0;
+}

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanAIMessages/SpanAIMessages.tsx

@@ -0,0 +1,58 @@
+import { useMemo, useRef } from 'react';
+import { ArrowDownRight, ArrowUpRight } from '@signozhq/icons';
+
+import { MessageType } from '../../AIThreadMessage/types';
+import { useToolCallLinks } from '../../AIThreadMessage/useToolCallLinks';
+import { getSpanMessages, hasAnyMessages } from '../../utils/spanMessages';
+import { ThreadSpan } from '../../TraceDetailsThread/types';
+import { buildToolCallIndex } from '../../TraceDetailsThread/utils';
+import MessagesAccordion from './MessagesAccordion';
+
+import styles from './SpanAIMessages.module.scss';
+
+interface SpanAIMessagesProps {
+	span: ThreadSpan;
+}
+
+/** Waterfall spans only carry raw attributes, so they get the JSON view alone. */
+function SpanAIMessages({ span }: SpanAIMessagesProps): JSX.Element | null {
+	const data = useMemo(() => getSpanMessages(span), [span]);
+
+	const rootRef = useRef<HTMLDivElement>(null);
+	const toolCallKeys = useMemo(() => buildToolCallIndex(span), [span]);
+	const { canLinkToToolCall, onToolLinkClick } = useToolCallLinks(
+		rootRef,
+		toolCallKeys,
+	);
+
+	if (!hasAnyMessages(data)) {
+		return null;
+	}
+
+	return (
+		<div className={styles.root} ref={rootRef} data-testid="span-ai-messages">
+			<MessagesAccordion
+				icon={<ArrowUpRight size={14} />}
+				title="Input"
+				messages={data.formattedInput}
+				raw={data.rawInput}
+				messageType={MessageType.Input}
+				testId="span-ai-messages-input"
+				canLinkToToolCall={canLinkToToolCall}
+				onToolLinkClick={onToolLinkClick}
+			/>
+			<MessagesAccordion
+				icon={<ArrowDownRight size={14} />}
+				title="Output"
+				messages={data.formattedOutput}
+				raw={data.rawOutput}
+				messageType={MessageType.Output}
+				testId="span-ai-messages-output"
+				canLinkToToolCall={canLinkToToolCall}
+				onToolLinkClick={onToolLinkClick}
+			/>
+		</div>
+	);
+}
+
+export default SpanAIMessages;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanDetailsPanel.module.scss

@@ -34,6 +34,15 @@
 	min-width: 0;
 }
 
+// Inside the Overview tab there's no flex gap, so match .panelBody's 16px.
+.tabAiMessages {
+	margin-bottom: 16px;
+
+	&:empty {
+		display: none;
+	}
+}
+
 // Logs-tab footer. Sibling of the scrolling .panelBody inside .panel, so it's
 // a true fixed footer flush with the panel's bottom edge — always visible
 // regardless of how the body is scrolled.

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanDetailsPanel.tsx

@@ -48,6 +48,7 @@ import Events from './Events/Events';
 import OpenInLogsExplorer from './SpanLogs/OpenInLogsExplorer';
 import SpanLogs from './SpanLogs/SpanLogs';
 import { useSpanContextLogs } from './SpanLogs/useSpanContextLogs';
+import SpanAIMessages from './SpanAIMessages/SpanAIMessages';
 import SpanSummary from './SpanSummary';
 
 import styles from './SpanDetailsPanel.module.scss';
@@ -281,6 +282,7 @@ function SpanDetailsContent({
 			traceEndTime={traceEndTime}
 		/>
 	);
+	const aiMessages = <SpanAIMessages span={selectedSpan} />;
 	const eventsCount = selectedSpan.events?.length || 0;
 
 	const spanDetailTabs: TabsItemProps[] = [
@@ -291,6 +293,7 @@ function SpanDetailsContent({
 			children: (
 				<>
 					{isWide && summary}
+					{isWide && <div className={styles.tabAiMessages}>{aiMessages}</div>}
 					<DataViewer
 						data={spanDisplayData}
 						drawerKey="trace-details"
@@ -369,6 +372,7 @@ function SpanDetailsContent({
 		<>
 			<div className={styles.panelBody} ref={bodyRef}>
 				{!isWide && <div className={styles.detailsSection}>{summary}</div>}
+				{!isWide && aiMessages}
 
 				<div className={styles.tabsSection}>
 					<Tabs

frontend/src/pages/TraceDetailsV3/SpanMessages/MessagesSection.tsx

@@ -0,0 +1,68 @@
+import AIThreadMessage, {
+	AIThreadMessageProps,
+} from '../AIThreadMessage/AIThreadMessage';
+import { ThreadMessage } from '../AIThreadMessage/types';
+import { ThreadView } from '../TraceDetailsThread/types';
+import RawMessages from './RawMessages';
+import { RawMessagesValue } from '../utils/spanMessages';
+
+import styles from './SpanMessages.module.scss';
+
+type MessageProps = Pick<
+	AIThreadMessageProps,
+	'messageType' | 'canLinkToToolCall' | 'onToolLinkClick'
+>;
+
+interface MessagesSectionProps extends MessageProps {
+	title?: string;
+	view: ThreadView;
+	messages: ThreadMessage[];
+	raw?: RawMessagesValue;
+	testId: string;
+}
+
+function MessagesSection({
+	title,
+	view,
+	messages,
+	raw,
+	testId,
+	messageType,
+	canLinkToToolCall,
+	onToolLinkClick,
+}: MessagesSectionProps): JSX.Element | null {
+	const isFormatted = view === ThreadView.Formatted;
+	if (isFormatted ? messages.length === 0 : !raw) {
+		return null;
+	}
+
+	return (
+		<section className={styles.section} data-testid={testId}>
+			{title && <div className={styles.sectionTitle}>{title}</div>}
+			{isFormatted ? (
+				<div className={styles.messages}>
+					{messages.map((message, index) => (
+						<AIThreadMessage
+							// Messages have no stable id and never reorder.
+							// eslint-disable-next-line react/no-array-index-key
+							key={index}
+							message={message}
+							messageType={messageType}
+							canLinkToToolCall={canLinkToToolCall}
+							onToolLinkClick={onToolLinkClick}
+						/>
+					))}
+				</div>
+			) : (
+				<RawMessages value={raw as RawMessagesValue} />
+			)}
+		</section>
+	);
+}
+
+MessagesSection.defaultProps = {
+	title: undefined,
+	raw: undefined,
+};
+
+export default MessagesSection;

frontend/src/pages/TraceDetailsV3/SpanMessages/RawMessages.tsx

@@ -0,0 +1,21 @@
+import JsonBlock from '../AIThreadMessage/JsonBlock';
+import { RawMessagesValue } from '../utils/spanMessages';
+
+import styles from './SpanMessages.module.scss';
+
+interface RawMessagesProps {
+	value: RawMessagesValue;
+}
+
+function RawMessages({ value }: RawMessagesProps): JSX.Element {
+	if (typeof value === 'object') {
+		return <JsonBlock data={value} />;
+	}
+	return (
+		<span className={styles.rawUnavailable} data-testid="span-raw-messages">
+			Unable to render messages
+		</span>
+	);
+}
+
+export default RawMessages;

frontend/src/pages/TraceDetailsV3/SpanMessages/SpanMessages.module.scss

@@ -0,0 +1,43 @@
+.root {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-10);
+	min-width: 0;
+}
+
+.section {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-2);
+	min-width: 0;
+}
+
+.sectionTitle {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-3);
+	font-size: var(--font-size-xs);
+	font-weight: var(--font-weight-medium);
+	color: var(--l2-foreground);
+}
+
+.messages {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-10);
+	min-width: 0;
+}
+
+.rawUnavailable {
+	font-size: var(--periscope-font-size-base);
+	font-style: italic;
+	color: var(--l2-foreground);
+}
+
+.missing {
+	padding: var(--spacing-10) var(--spacing-6);
+	border-radius: var(--radius-2);
+	font-size: var(--periscope-font-size-base);
+	color: var(--l2-foreground);
+	text-align: center;
+}

frontend/src/pages/TraceDetailsV3/SpanMessages/SpanMessages.tsx

@@ -0,0 +1,86 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+
+import { AIThreadMessageProps } from '../AIThreadMessage/AIThreadMessage';
+import { ThreadSpan, ThreadView } from '../TraceDetailsThread/types';
+import JsonBlock from '../AIThreadMessage/JsonBlock';
+import { MessageType } from '../AIThreadMessage/types';
+import MessagesSection from './MessagesSection';
+import {
+	getSpanMessages,
+	hasFormattedMessages,
+	hasRawMessages,
+} from '../utils/spanMessages';
+
+import styles from './SpanMessages.module.scss';
+
+interface SpanMessagesProps extends Pick<
+	AIThreadMessageProps,
+	'canLinkToToolCall' | 'onToolLinkClick'
+> {
+	span: ThreadSpan;
+	view: ThreadView;
+	className?: string;
+}
+
+/** Input and output messages of one AI span, shared by Thread and Span Details. */
+function SpanMessages({
+	span,
+	view,
+	className,
+	canLinkToToolCall,
+	onToolLinkClick,
+}: SpanMessagesProps): JSX.Element {
+	const data = useMemo(() => getSpanMessages(span), [span]);
+	const isFormatted = view === ThreadView.Formatted;
+
+	if (isFormatted ? !hasFormattedMessages(data) : !hasRawMessages(data)) {
+		return (
+			<div
+				className={cx(styles.missing, className)}
+				data-testid="span-messages-empty"
+			>
+				This span has no input or output.
+			</div>
+		);
+	}
+
+	if (!isFormatted) {
+		return (
+			<div className={cx(styles.root, className)} data-testid="span-messages-json">
+				<JsonBlock
+					data={{ input: data.rawInput ?? [], output: data.rawOutput ?? [] }}
+				/>
+			</div>
+		);
+	}
+
+	return (
+		<div className={cx(styles.root, className)}>
+			<MessagesSection
+				view={view}
+				messages={data.formattedInput}
+				raw={data.rawInput}
+				messageType={MessageType.Input}
+				testId="span-messages-input"
+				canLinkToToolCall={canLinkToToolCall}
+				onToolLinkClick={onToolLinkClick}
+			/>
+			<MessagesSection
+				view={view}
+				messages={data.formattedOutput}
+				raw={data.rawOutput}
+				messageType={MessageType.Output}
+				testId="span-messages-output"
+				canLinkToToolCall={canLinkToToolCall}
+				onToolLinkClick={onToolLinkClick}
+			/>
+		</div>
+	);
+}
+
+SpanMessages.defaultProps = {
+	className: undefined,
+};
+
+export default SpanMessages;

frontend/src/pages/TraceDetailsV3/SpanMessages/__tests__/SpanMessages.test.tsx

@@ -0,0 +1,94 @@
+import { render, screen, within } from 'tests/test-utils';
+
+import { ThreadSpan, ThreadView } from '../../TraceDetailsThread/types';
+import { GEN_AI_KEYS } from '../../utils/aiTraceUtils';
+import SpanMessages from '../SpanMessages';
+
+// jsdom has no layout; report a JSON tree taller than the 10-row clamp.
+jest.mock('hooks/useDimensions', () => ({
+	useResizeObserver: (): { width: number; height: number } => ({
+		width: 0,
+		height: 300,
+	}),
+}));
+
+const makeSpan = (overrides: Partial<ThreadSpan>): ThreadSpan =>
+	({ span_id: 's1', attributes: {}, ...overrides }) as unknown as ThreadSpan;
+
+describe('SpanMessages', () => {
+	it('shows the empty state when there are no formatted messages', () => {
+		const span = makeSpan({
+			attributes: { [GEN_AI_KEYS.inputMessages]: '[{"role":"user"}]' },
+		});
+
+		render(<SpanMessages span={span} view={ThreadView.Formatted} />);
+
+		expect(screen.getByTestId('span-messages-empty')).toHaveTextContent(
+			'This span has no input or output.',
+		);
+	});
+
+	it('renders formatted input and output messages', () => {
+		const span = makeSpan({
+			formattedInput: [
+				{ role: 'user', parts: [{ type: 'text', content: 'question' }] },
+			],
+			formattedOutput: [
+				{ role: 'assistant', parts: [{ type: 'text', content: 'answer' }] },
+			],
+		});
+
+		render(<SpanMessages span={span} view={ThreadView.Formatted} />);
+
+		expect(
+			within(screen.getByTestId('span-messages-input')).getByText('question'),
+		).toBeInTheDocument();
+		expect(
+			within(screen.getByTestId('span-messages-output')).getByText('answer'),
+		).toBeInTheDocument();
+	});
+
+	it('shows the empty state in JSON view when there are no raw messages', () => {
+		render(<SpanMessages span={makeSpan({})} view={ThreadView.Json} />);
+
+		expect(screen.getByTestId('span-messages-empty')).toBeInTheDocument();
+	});
+
+	it('renders raw messages in JSON view', () => {
+		const span = makeSpan({
+			attributes: { [GEN_AI_KEYS.outputMessages]: '[{"role":"assistant"}]' },
+		});
+
+		render(<SpanMessages span={span} view={ThreadView.Json} />);
+
+		expect(screen.getByTestId('span-messages-json')).toBeInTheDocument();
+	});
+
+	it('opens every key in JSON view', () => {
+		const span = makeSpan({
+			attributes: {
+				[GEN_AI_KEYS.inputMessages]: '[{"role":"user","content":"visible-text"}]',
+			},
+		});
+
+		render(<SpanMessages span={span} view={ThreadView.Json} />);
+
+		expect(screen.getByText(/visible-text/)).toBeInTheDocument();
+	});
+
+	it('collapses tall JSON behind Show more in JSON view', () => {
+		const span = makeSpan({
+			attributes: {
+				[GEN_AI_KEYS.inputMessages]: JSON.stringify([
+					{ role: 'user', content: 'hi' },
+				]),
+			},
+		});
+
+		render(<SpanMessages span={span} view={ThreadView.Json} />);
+
+		expect(screen.getByTestId('ai-json-show-more')).toHaveTextContent(
+			'Show more',
+		);
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceDetailsHeader.module.scss

@@ -29,6 +29,10 @@
 	}
 }
 
+.tabs {
+	flex-shrink: 0;
+}
+
 .filterSection {
 	display: flex;
 	align-items: center;

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceDetailsHeader.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useParams } from 'react-router-dom';
 import { Button } from '@signozhq/ui/button';
 import { Tooltip } from '@signozhq/ui/tooltip';
@@ -13,16 +13,20 @@ import KeyValueLabel from 'periscope/components/KeyValueLabel';
 import { TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
 import { DataSource } from 'types/common/queryBuilder';
 
+import { TraceDetailsTab } from '../constants';
 import { TraceDetailEventKeys, TraceDetailEvents } from '../events';
 import { useTraceDetailLogEvent } from '../hooks/useTraceDetailLogEvent';
+import { useTraceDetailsTab } from '../hooks/useTraceDetailsTab';
 import { useTraceStore } from '../stores/traceStore';
 import TraceDownloadPanel from './TraceDownloadPanel';
 import EntityMetadataRow from '../EntityMetadata/EntityMetadataRow';
 import AnalyticsPanel from '../SpanDetailsPanel/AnalyticsPanel/AnalyticsPanel';
 import Filters from '../TraceWaterfall/TraceWaterfallStates/Success/Filters/Filters';
+import { useTraceDetailsStripInfo } from '../useTraceDetailsStripInfo';
 import MissingSpansBanner from './MissingSpansBanner';
-import TraceOptionsMenu from './TraceOptionsMenu';
 import { useTraceSummary } from './useTraceSummary';
+import TraceDetailsTabs from './TraceDetailsTabs';
+import TraceOptionsMenu from './TraceOptionsMenu';
 
 import styles from './TraceDetailsHeader.module.scss';
 import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
@@ -60,6 +64,17 @@ function TraceDetailsHeader({
 	const [isPreviewFieldsOpen, setIsPreviewFieldsOpen] = useState(false);
 	const [isAnalyticsOpen, setIsAnalyticsOpen] = useState(false);
 	const { data: traceSummary } = useTraceSummary(traceID);
+	const [tab] = useTraceDetailsTab();
+	const isOverview = tab === TraceDetailsTab.Overview;
+
+	// Overview-only panels must not linger over another tab.
+	// The filter query lives in Filters' local state, which unmounts with the
+	// Overview tab; drop its result too so both start empty on return.
+	useEffect(() => {
+		setIsPreviewFieldsOpen(false);
+		setIsAnalyticsOpen(false);
+		onFilteredSpansChange([], false);
+	}, [tab, onFilteredSpansChange]);
 	const previewFields = useTraceStore((s) => s.previewFields);
 	const setPreviewFields = useTraceStore((s) => s.setPreviewFields);
 
@@ -93,13 +108,14 @@ function TraceDetailsHeader({
 		setShowTraceDetails((prev) => !prev);
 	}, []);
 
+	useTraceDetailsStripInfo({
+		totalSpansCount: traceSummary?.totalSpansCount ?? 0,
+		totalErrorSpansCount: traceSummary?.totalErrorSpansCount ?? 0,
+	});
+
 	const startTime = (traceSummary?.startTimestampMillis ?? 0) / 1e3;
 	const endTime = (traceSummary?.endTimestampMillis ?? 0) / 1e3;
 
-	const durationMs = traceSummary
-		? traceSummary.endTimestampMillis - traceSummary.startTimestampMillis
-		: 0;
-
 	return (
 		<div className={styles.wrapper}>
 			<div className={styles.header}>
@@ -120,9 +136,10 @@ function TraceDetailsHeader({
 							badgeValue={traceID}
 							maxCharacters={100}
 						/>
+						<TraceDetailsTabs />
 					</div>
 				)}
-				{showTraceDetailsHeaderOptions && traceSummary && (
+				{isOverview && showTraceDetailsHeaderOptions && traceSummary && (
 					<div
 						className={cx(
 							styles.filterSection,
@@ -138,6 +155,7 @@ function TraceDetailsHeader({
 										icon
 										color="secondary"
 										aria-label="Analytics"
+										testId="trace-analytics-button"
 										onClick={handleToggleAnalytics}
 									>
 										<ChartPie size={14} />
@@ -172,16 +190,20 @@ function TraceDetailsHeader({
 				)}
 			</div>
 
-			{showTraceDetails && (
+			{(showTraceDetails || !isOverview) && (
 				<div className={styles.subHeader}>
-					{traceSummary ? (
+					{!traceSummary ? (
+						<DetailsLoader />
+					) : (
 						<EntityMetadataRow
 							entity="trace"
 							service={{
 								name: traceSummary.rootServiceName,
 								entryPoint: traceSummary.rootServiceEntryPoint,
 							}}
-							durationMs={durationMs}
+							durationMs={
+								traceSummary.endTimestampMillis - traceSummary.startTimestampMillis
+							}
 							timestamp={dayjs(traceSummary.startTimestampMillis).format(
 								DATE_TIME_FORMATS.DD_MMM_YYYY_HH_MM_SS,
 							)}
@@ -189,13 +211,11 @@ function TraceDetailsHeader({
 							tokens={traceSummary.ai?.tokens}
 							cost={traceSummary.ai?.totalCost}
 						/>
-					) : (
-						<DetailsLoader />
 					)}
 				</div>
 			)}
 
-			{traceSummary?.hasMissingSpans && <MissingSpansBanner />}
+			{isOverview && traceSummary?.hasMissingSpans && <MissingSpansBanner />}
 
 			<FieldsSelector
 				isOpen={isPreviewFieldsOpen}

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceDetailsTabs.tsx

@@ -0,0 +1,43 @@
+import { ToggleGroup } from '@signozhq/ui/toggle-group';
+
+import { TraceDetailsTab } from '../constants';
+import { useTraceDetailsTab } from '../hooks/useTraceDetailsTab';
+
+import styles from './TraceDetailsHeader.module.scss';
+
+const TAB_ITEMS = [
+	{
+		value: TraceDetailsTab.Overview,
+		label: 'Overview',
+		testId: 'trace-details-tab-overview',
+	},
+	{
+		value: TraceDetailsTab.Thread,
+		label: 'Thread',
+		testId: 'trace-details-tab-thread',
+	},
+];
+
+function TraceDetailsTabs(): JSX.Element {
+	const [tab, setTab] = useTraceDetailsTab();
+
+	const handleChange = (value: string): void => {
+		void setTab(value as TraceDetailsTab);
+	};
+
+	return (
+		<div className={styles.tabs}>
+			<ToggleGroup
+				variant="outlined"
+				color="secondary"
+				type="single"
+				value={tab}
+				onChange={handleChange}
+				size="sm"
+				items={TAB_ITEMS}
+			/>
+		</div>
+	);
+}
+
+export default TraceDetailsTabs;

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceOptionsMenu.tsx

@@ -50,6 +50,7 @@ function TraceOptionsMenu({
 			type: 'item',
 			value: 'toggle-trace-details',
 			label: showTraceDetails ? 'Hide trace details' : 'Show trace details',
+			testId: 'toggle-trace-details',
 			onClick: onToggleTraceDetails,
 		},
 		{
@@ -127,6 +128,7 @@ function TraceOptionsMenu({
 				icon
 				color="secondary"
 				aria-label="Trace options"
+				testId="trace-options-button"
 			>
 				<Settings2 size={14} />
 			</Button>

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/__tests__/TraceDetailsHeader.test.tsx

@@ -2,6 +2,7 @@ import { fireEvent, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { getYAxisFormattedValue } from 'components/Graph/yAxisConfig';
 import type { SpantypesGettableTraceSummaryDTO } from 'api/generated/services/sigNoz.schemas';
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing';
 import ROUTES from 'constants/routes';
 import { render } from 'tests/test-utils';
 
@@ -315,3 +316,98 @@ describe('TraceDetailsHeader – trace metadata row', () => {
 		expect(container.querySelectorAll('.ant-skeleton-input')).toHaveLength(3);
 	});
 });
+
+const metadataText = /Missing Span/;
+
+describe('TraceDetailsHeader – tabs', () => {
+	beforeEach(() => {
+		jest.mocked(useTraceSummary).mockReturnValue({
+			data: {
+				...SUMMARY,
+				rootServiceEntryPoint: 'Missing Span',
+				hasMissingSpans: true,
+			},
+			isLoading: false,
+		});
+	});
+
+	afterEach(() => {
+		jest
+			.mocked(useTraceSummary)
+			.mockReturnValue({ data: undefined, isLoading: false });
+	});
+
+	// In-memory URL state, so a tab switch can't leak into the next test.
+	const renderHeader = (): void => {
+		render(
+			<NuqsTestingAdapter hasMemory>
+				<TraceDetailsHeader {...baseProps} showTraceDetailsHeaderOptions />
+			</NuqsTestingAdapter>,
+		);
+	};
+
+	it('shows the Overview-only sections on the Overview tab', () => {
+		renderHeader();
+
+		expect(screen.getByTestId('filters-stub')).toBeInTheDocument();
+		expect(screen.getByTestId('trace-analytics-button')).toBeInTheDocument();
+		expect(screen.getByTestId('trace-options-button')).toBeInTheDocument();
+		expect(screen.getByTestId('missing-spans-banner')).toBeInTheDocument();
+	});
+
+	it('keeps only the metadata row on the Thread tab', async () => {
+		const user = userEvent.setup({ delay: null });
+		renderHeader();
+
+		await user.click(screen.getByTestId('trace-details-tab-thread'));
+
+		expect(screen.queryByTestId('filters-stub')).not.toBeInTheDocument();
+		expect(
+			screen.queryByTestId('trace-analytics-button'),
+		).not.toBeInTheDocument();
+		expect(screen.queryByTestId('trace-options-button')).not.toBeInTheDocument();
+		expect(screen.queryByTestId('missing-spans-banner')).not.toBeInTheDocument();
+		expect(screen.getByText(metadataText)).toBeInTheDocument();
+	});
+
+	it('shows the metadata row on the Thread tab even when hidden on Overview', async () => {
+		const user = userEvent.setup({ delay: null });
+		renderHeader();
+
+		await user.click(screen.getByTestId('trace-options-button'));
+		await user.click(await screen.findByTestId('toggle-trace-details'));
+		expect(screen.queryByText(metadataText)).not.toBeInTheDocument();
+
+		await user.click(screen.getByTestId('trace-details-tab-thread'));
+
+		expect(screen.getByText(metadataText)).toBeInTheDocument();
+	});
+
+	it('clears the filter result when switching to the Thread tab', async () => {
+		const user = userEvent.setup({ delay: null });
+		renderHeader();
+		baseProps.onFilteredSpansChange.mockClear();
+
+		await user.click(screen.getByTestId('trace-details-tab-thread'));
+
+		expect(baseProps.onFilteredSpansChange).toHaveBeenCalledWith([], false);
+	});
+
+	it('closes the Analytics panel when switching to the Thread tab', async () => {
+		const user = userEvent.setup({ delay: null });
+		renderHeader();
+
+		await user.click(screen.getByTestId('trace-analytics-button'));
+		expect(screen.getByTestId('analytics-panel')).toHaveAttribute(
+			'data-open',
+			'true',
+		);
+
+		await user.click(screen.getByTestId('trace-details-tab-thread'));
+
+		expect(screen.getByTestId('analytics-panel')).toHaveAttribute(
+			'data-open',
+			'false',
+		);
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsOverview/TraceDetailsOverview.module.scss

@@ -1,10 +1,3 @@
-.root {
-	flex: 1;
-	min-height: 0;
-	display: flex;
-	flex-direction: column;
-}
-
 .layoutRow {
 	display: flex;
 	flex: 1;

frontend/src/pages/TraceDetailsV3/TraceDetailsOverview/TraceDetailsOverview.tsx

@@ -0,0 +1,505 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+import {
+	MutableRefObject,
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react';
+import { useParams } from 'react-router-dom';
+import {
+	ChartNoAxesGantt,
+	ChevronDown,
+	ChevronRight,
+	Info,
+	TriangleAlert,
+} from '@signozhq/icons';
+import getLocalStorageKey from 'api/browser/localstorage/get';
+import { Collapse } from 'antd';
+import { useDetailsPanel } from 'components/DetailsPanel';
+import WarningPopover from 'components/WarningPopover/WarningPopover';
+import { LOCALSTORAGE } from 'constants/localStorage';
+import useGetTraceV4 from 'hooks/trace/useGetTraceV4';
+import { useSafeNavigate } from 'hooks/useSafeNavigate';
+import useUrlQuery from 'hooks/useUrlQuery';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
+import { ResizableBox } from 'periscope/components/ResizableBox';
+import { SpanV3, TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
+
+import { TraceDetailEventKeys, TraceDetailEvents } from '../events';
+import { useSpanDetailVariant } from '../hooks/useSpanDetailVariant';
+import { useTraceDetailLogEvent } from '../hooks/useTraceDetailLogEvent';
+import NoData from '../NoData/NoData';
+import {
+	setTraceStoreAvailableColorByFields,
+	useTraceStore,
+} from '../stores/traceStore';
+import {
+	SPAN_DETAILS_PANEL_MIN_WIDTH,
+	SpanDetailVariant,
+} from '../SpanDetailsPanel/constants';
+import SpanDetailsPanel from '../SpanDetailsPanel/SpanDetailsPanel';
+import { FLAMEGRAPH_SPAN_LIMIT } from '../TraceFlamegraph/constants';
+import TraceFlamegraph from '../TraceFlamegraph/TraceFlamegraph';
+import TraceWaterfall from '../TraceWaterfall/TraceWaterfall';
+import { IInterestedSpan } from '../TraceWaterfall/types';
+import { getAncestorSpanIds } from '../TraceWaterfall/utils';
+import { getAvailableColorByFieldNames } from '../utils';
+
+import cx from 'classnames';
+
+import styles from './TraceDetailsOverview.module.scss';
+
+// Lucide chevrons for the flame/waterfall accordion headers, matching the
+// span-tree chevrons in the waterfall.
+function renderPanelExpandIcon({
+	isActive,
+}: {
+	isActive?: boolean;
+}): JSX.Element {
+	return isActive ? <ChevronDown size={14} /> : <ChevronRight size={14} />;
+}
+
+interface TraceDetailsOverviewProps {
+	filteredSpanIds: string[];
+	isFilterActive: boolean;
+	onHasTraceDataChange: (hasTraceData: boolean) => void;
+	dataLoadedFiredForRef: MutableRefObject<string>;
+}
+
+function TraceDetailsOverview({
+	filteredSpanIds,
+	isFilterActive,
+	onHasTraceDataChange,
+	dataLoadedFiredForRef,
+}: TraceDetailsOverviewProps): JSX.Element {
+	const { id: traceId } = useParams<TraceDetailV3URLProps>();
+	const urlQuery = useUrlQuery();
+	const [interestedSpanId, setInterestedSpanId] = useState<IInterestedSpan>(
+		() => ({
+			spanId: urlQuery.get('spanId') || '',
+			isUncollapsed: urlQuery.get('spanId') !== '',
+		}),
+	);
+	const [uncollapsedNodes, setUncollapsedNodes] = useState<string[]>([]);
+	const [localUncollapsedNodes, setLocalUncollapsedNodes] = useState<
+		Set<string>
+	>(new Set());
+	const [selectedSpan, setSelectedSpan] = useState<SpanV3>();
+
+	const selectedSpanId = urlQuery.get('spanId') || undefined;
+	const { safeNavigate } = useSafeNavigate();
+
+	const logTraceEvent = useTraceDetailLogEvent('v3', traceId || '');
+	const colorByField = useTraceStore((s) => s.colorByField);
+	const previewFieldsCount = useTraceStore((s) => s.previewFields.length);
+	const userPrefsReady = useTraceStore((s) => s.userPreferences !== null);
+
+	const handleSpanDetailsClose = useCallback((): void => {
+		const params = getUnstableCurrentSearchParams();
+		params.delete('spanId');
+		safeNavigate({ search: params.toString() }, { replace: true });
+	}, [safeNavigate]);
+
+	const panelState = useDetailsPanel({
+		entityId: selectedSpanId,
+		onClose: handleSpanDetailsClose,
+	});
+
+	const allSpansRef = useRef<SpanV3[]>([]);
+	const deepLinkResolvedRef = useRef(false);
+
+	// Refetch only when the URL target isn't already loaded. Keeps row clicks
+	// and other in-window URL navigation from triggering a backend window slide.
+	useEffect(() => {
+		const spanId = urlQuery.get('spanId') || '';
+		if (!spanId) {
+			return;
+		}
+		const idx = allSpansRef.current.findIndex((s) => s.span_id === spanId);
+		if (idx !== -1) {
+			setSelectedSpan(allSpansRef.current[idx]);
+			return;
+		}
+		setInterestedSpanId({ spanId, isUncollapsed: true });
+	}, [urlQuery]);
+
+	// Once all spans are loaded (frontend mode), freeze query params so
+	// subsequent interestedSpanId changes don't trigger unnecessary refetches.
+	const fullDataLoadedRef = useRef(false);
+	const frozenParamsRef = useRef({
+		selectedSpanId: interestedSpanId.spanId,
+		isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
+		uncollapsedSpans: uncollapsedNodes,
+	});
+
+	const queryParams = fullDataLoadedRef.current
+		? frozenParamsRef.current
+		: {
+				selectedSpanId: interestedSpanId.spanId,
+				isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
+				uncollapsedSpans: uncollapsedNodes,
+			};
+
+	const {
+		data: traceData,
+		isFetching: isFetchingTraceData,
+		error: errorFetchingTraceData,
+	} = useGetTraceV4({
+		traceId,
+		uncollapsedSpans: queryParams.uncollapsedSpans,
+		selectedSpanId: queryParams.selectedSpanId,
+		isSelectedSpanIDUnCollapsed: queryParams.isSelectedSpanIDUnCollapsed,
+	});
+
+	const allSpans = traceData?.payload?.spans || [];
+	const totalSpansCount = traceData?.payload?.totalSpansCount || 0;
+
+	const isFullDataLoaded =
+		totalSpansCount > 0 && totalSpansCount <= allSpans.length;
+
+	// Color-by options, gated on fields in loaded spans. Resource attrs are
+	// trace-wide, so any window has the full set — no need to accumulate.
+	const availableColorByFields = useMemo(() => {
+		const spans = traceData?.payload?.spans;
+		return spans?.length ? getAvailableColorByFieldNames(spans) : undefined;
+	}, [traceData?.payload?.spans]);
+
+	useEffect(() => {
+		setTraceStoreAvailableColorByFields(availableColorByFields);
+	}, [availableColorByFields]);
+
+	// Lock the ref once we confirm all data is loaded
+	if (isFullDataLoaded && !fullDataLoadedRef.current) {
+		fullDataLoadedRef.current = true;
+		frozenParamsRef.current = {
+			selectedSpanId: interestedSpanId.spanId,
+			isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
+			uncollapsedSpans: uncollapsedNodes,
+		};
+	}
+
+	useEffect(() => {
+		allSpansRef.current = allSpans;
+	}, [allSpans]);
+
+	useEffect(() => {
+		if (
+			!traceId ||
+			dataLoadedFiredForRef.current === traceId ||
+			!userPrefsReady
+		) {
+			return;
+		}
+		const payload = traceData?.payload;
+		if (!payload?.spans?.length) {
+			return;
+		}
+		dataLoadedFiredForRef.current = traceId;
+		const numServices = new Set(payload.spans.map((s) => s['service.name'])).size;
+		logTraceEvent(TraceDetailEvents.DataLoaded, {
+			[TraceDetailEventKeys.TotalSpansCount]: totalSpansCount,
+			[TraceDetailEventKeys.NumServices]: numServices,
+			[TraceDetailEventKeys.TraceDurationMs]:
+				payload.endTimestampMillis - payload.startTimestampMillis,
+			[TraceDetailEventKeys.HadErrors]: (payload.totalErrorSpansCount || 0) > 0,
+			[TraceDetailEventKeys.FlamegraphSampled]:
+				totalSpansCount > FLAMEGRAPH_SPAN_LIMIT,
+			[TraceDetailEventKeys.SpanPanelVariant]:
+				getLocalStorageKey(LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION) ||
+				SpanDetailVariant.DOCKED_RIGHT,
+			[TraceDetailEventKeys.ColorByField]: colorByField.name,
+			[TraceDetailEventKeys.PreviewFieldsCount]: previewFieldsCount,
+		});
+	}, [
+		traceId,
+		userPrefsReady,
+		traceData,
+		totalSpansCount,
+		colorByField,
+		previewFieldsCount,
+		logTraceEvent,
+		dataLoadedFiredForRef,
+	]);
+
+	// Frontend mode: expand all parents by default when full data arrives
+	useEffect(() => {
+		if (isFullDataLoaded && allSpans.length > 0) {
+			const parentIds = new Set(
+				allSpans.filter((s) => s.has_children).map((s) => s.span_id),
+			);
+			setLocalUncollapsedNodes(parentIds);
+		}
+	}, [isFullDataLoaded, allSpans]);
+
+	// Backend mode: sync uncollapsed state from API response
+	useEffect(() => {
+		if (
+			!isFullDataLoaded &&
+			traceData &&
+			traceData.payload &&
+			traceData.payload.uncollapsedSpans
+		) {
+			setUncollapsedNodes(traceData.payload.uncollapsedSpans);
+		}
+	}, [traceData, isFullDataLoaded]);
+
+	// Tracks whether we've already done the initial URL→selectedSpan handoff
+	//Lets `interestedSpanId` stay purely as the refetch trigger in frontend mode.
+	useEffect(() => {
+		if (deepLinkResolvedRef.current) {
+			return;
+		}
+		if (allSpans.length === 0) {
+			return;
+		}
+		if (selectedSpanId) {
+			const span = allSpans.find((s) => s.span_id === selectedSpanId);
+			if (!span) {
+				// Span not in the current window — wait for more data (backend
+				// pagination) before marking resolved.
+				return;
+			}
+			setSelectedSpan(span);
+		} else {
+			setSelectedSpan((prev) => prev ?? allSpans[0]);
+		}
+		deepLinkResolvedRef.current = true;
+	}, [selectedSpanId, allSpans]);
+
+	// Frontend mode: auto-expand ancestors of the URL-targeted span so it's
+	// visible. Keyed on URL `spanId`(selectedSpanId).
+	useEffect(() => {
+		if (!isFullDataLoaded || !selectedSpanId || allSpans.length === 0) {
+			return;
+		}
+		const ancestors = getAncestorSpanIds(allSpans, selectedSpanId);
+		if (ancestors.size === 0) {
+			return;
+		}
+		setLocalUncollapsedNodes((prev) => {
+			// Check if all ancestors are already expanded — avoid unnecessary state update
+			let allPresent = true;
+			for (const id of ancestors) {
+				if (!prev.has(id)) {
+					allPresent = false;
+					break;
+				}
+			}
+			if (allPresent) {
+				return prev;
+			}
+
+			const next = new Set(prev);
+			for (const id of ancestors) {
+				next.add(id);
+			}
+			return next;
+		});
+	}, [isFullDataLoaded, selectedSpanId, allSpans]);
+
+	const [activeKeys, setActiveKeys] = useState<string[]>(['flame', 'waterfall']);
+
+	const handleCollapseChange = (key: string): void => {
+		logTraceEvent(
+			key === 'flame'
+				? TraceDetailEvents.FlameGraphToggled
+				: TraceDetailEvents.WaterfallToggled,
+			{ [TraceDetailEventKeys.Expanded]: !activeKeys.includes(key) },
+		);
+		setActiveKeys((prev) =>
+			prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key],
+		);
+	};
+
+	const [spanDetailVariant, handleVariantChange] = useSpanDetailVariant();
+
+	const RIGHT_DOCK_MIN = SPAN_DETAILS_PANEL_MIN_WIDTH;
+	const RIGHT_DOCK_MAX = 720;
+	const [rightDockWidth, setRightDockWidth] = useState(RIGHT_DOCK_MIN);
+
+	const showNoData =
+		!isFetchingTraceData &&
+		(!!errorFetchingTraceData || !traceData?.payload?.spans?.length);
+
+	const hasTraceData = !showNoData && allSpans.length > 0;
+
+	useEffect(() => {
+		onHasTraceDataChange(hasTraceData);
+		return (): void => onHasTraceDataChange(false);
+	}, [hasTraceData, onHasTraceDataChange]);
+
+	const isDocked = spanDetailVariant === SpanDetailVariant.DOCKED;
+	const isRightDocked = spanDetailVariant === SpanDetailVariant.DOCKED_RIGHT;
+	const isWaterfallDocked = panelState.isOpen && isDocked;
+	const showRightDock = panelState.isOpen && isRightDocked;
+
+	const waterfallChildren = (
+		<ResizableBox
+			defaultHeight={300}
+			minHeight={150}
+			disabled={!isWaterfallDocked}
+		>
+			<TraceWaterfall
+				traceData={traceData}
+				isFetchingTraceData={isFetchingTraceData}
+				errorFetchingTraceData={errorFetchingTraceData}
+				traceId={traceId || ''}
+				interestedSpanId={interestedSpanId}
+				setInterestedSpanId={setInterestedSpanId}
+				uncollapsedNodes={uncollapsedNodes}
+				isFullDataLoaded={isFullDataLoaded}
+				localUncollapsedNodes={localUncollapsedNodes}
+				setLocalUncollapsedNodes={setLocalUncollapsedNodes}
+				selectedSpan={selectedSpan}
+				setSelectedSpan={setSelectedSpan}
+				filteredSpanIds={filteredSpanIds}
+				isFilterActive={isFilterActive}
+			/>
+		</ResizableBox>
+	);
+
+	return (
+		<>
+			{showNoData ? (
+				<NoData />
+			) : (
+				<>
+					<div className={styles.layoutRow}>
+						<div className={styles.content}>
+							<Collapse
+								// @ts-expect-error motion is passed through to rc-collapse to disable animation
+								motion={false}
+								activeKey={activeKeys.filter((k) => k === 'flame')}
+								onChange={(): void => handleCollapseChange('flame')}
+								size="small"
+								expandIcon={renderPanelExpandIcon}
+								className={styles.flameCollapse}
+								items={[
+									{
+										key: 'flame',
+										label: (
+											<div className={styles.collapseLabel}>
+												<span className={styles.collapseTitle}>
+													Flame Graph
+													{traceData?.payload?.totalSpansCount &&
+														traceData.payload.totalSpansCount > FLAMEGRAPH_SPAN_LIMIT && (
+															<WarningPopover
+																message="The total span count exceeds the visualization limit. Displaying a sampled subset of spans in flamegraph."
+																placement="bottomLeft"
+															>
+																<Info
+																	size={16}
+																	color="var(--l2-foreground)"
+																	style={{ cursor: 'pointer' }}
+																/>
+															</WarningPopover>
+														)}
+												</span>
+												{traceData?.payload?.totalSpansCount ? (
+													<span className={styles.collapseCount}>
+														<span className={styles.collapseCountItem}>
+															<ChartNoAxesGantt size={13} />
+															Spans: {traceData.payload.totalSpansCount}
+														</span>
+														<span
+															className={cx(styles.collapseCountItem, {
+																[styles.hasErrors]: traceData.payload.totalErrorSpansCount > 0,
+															})}
+														>
+															<TriangleAlert size={13} />
+															Errors:{' '}
+															{traceData.payload.totalErrorSpansCount ?? (
+																<span className="translate-safe">{0}</span>
+															)}
+														</span>
+													</span>
+												) : null}
+											</div>
+										),
+										children: (
+											<ResizableBox defaultHeight={300} minHeight={100} maxHeight={400}>
+												<TraceFlamegraph
+													filteredSpanIds={filteredSpanIds}
+													isFilterActive={isFilterActive}
+													selectedSpan={selectedSpan}
+													totalSpansCount={totalSpansCount}
+												/>
+											</ResizableBox>
+										),
+									},
+								]}
+							/>
+
+							<Collapse
+								// @ts-expect-error motion is passed through to rc-collapse to disable animation
+								motion={false}
+								activeKey={activeKeys.filter((k) => k === 'waterfall')}
+								onChange={(): void => handleCollapseChange('waterfall')}
+								size="small"
+								expandIcon={renderPanelExpandIcon}
+								className={cx(styles.waterfallCollapse, {
+									[styles.isDocked]: isWaterfallDocked,
+								})}
+								items={[
+									{
+										key: 'waterfall',
+										label: 'Waterfall',
+										children: activeKeys.includes('waterfall') ? waterfallChildren : null,
+									},
+								]}
+							/>
+
+							{panelState.isOpen && isDocked && (
+								<div className={styles.dockedSpanDetails}>
+									<SpanDetailsPanel
+										panelState={panelState}
+										selectedSpan={selectedSpan}
+										variant={SpanDetailVariant.DOCKED}
+										onVariantChange={handleVariantChange}
+										traceStartTime={traceData?.payload?.startTimestampMillis}
+										traceEndTime={traceData?.payload?.endTimestampMillis}
+									/>
+								</div>
+							)}
+						</div>
+
+						{showRightDock && (
+							<ResizableBox
+								handle="left"
+								defaultWidth={rightDockWidth}
+								minWidth={RIGHT_DOCK_MIN}
+								maxWidth={RIGHT_DOCK_MAX}
+								onResize={setRightDockWidth}
+								className={styles.rightDock}
+							>
+								<SpanDetailsPanel
+									panelState={panelState}
+									selectedSpan={selectedSpan}
+									variant={SpanDetailVariant.DOCKED_RIGHT}
+									onVariantChange={handleVariantChange}
+									traceStartTime={traceData?.payload?.startTimestampMillis}
+									traceEndTime={traceData?.payload?.endTimestampMillis}
+								/>
+							</ResizableBox>
+						)}
+					</div>
+
+					{panelState.isOpen && spanDetailVariant === SpanDetailVariant.DIALOG && (
+						<SpanDetailsPanel
+							panelState={panelState}
+							selectedSpan={selectedSpan}
+							variant={SpanDetailVariant.DIALOG}
+							onVariantChange={handleVariantChange}
+							traceStartTime={traceData?.payload?.startTimestampMillis}
+							traceEndTime={traceData?.payload?.endTimestampMillis}
+						/>
+					)}
+				</>
+			)}
+		</>
+	);
+}
+
+export default TraceDetailsOverview;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadNoAiSpans.module.scss

@@ -0,0 +1,29 @@
+.root {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-start;
+	gap: var(--spacing-12);
+	padding: var(--spacing-20) var(--spacing-24);
+}
+
+.message {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-4);
+	max-width: 428px;
+}
+
+.emoji {
+	font-size: 32px;
+	line-height: 1;
+}
+
+.paragraphs {
+	display: flex;
+	flex-direction: column;
+	gap: var(--paragraph-base-500-line-height);
+}
+
+.highlight {
+	color: var(--l1-foreground);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadNoAiSpans.tsx

@@ -0,0 +1,43 @@
+import { ArrowRight } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { Typography } from '@signozhq/ui/typography';
+import { openInNewTab } from 'utils/navigation';
+
+import { LLM_OBSERVABILITY_DOCS_URL } from '../constants';
+
+import styles from './ThreadNoAiSpans.module.scss';
+
+function ThreadNoAiSpans(): JSX.Element {
+	return (
+		<div className={styles.root} data-testid="thread-empty">
+			<div className={styles.message}>
+				<span className={styles.emoji} aria-hidden>
+					🚏
+				</span>
+				<div className={styles.paragraphs}>
+					<Typography size="base" weight="medium" color="muted">
+						Looks like this trace does not have any spans from AI-related actions.
+					</Typography>
+					<Typography size="base" weight="medium" className={styles.highlight}>
+						Thread view summarising your entire AI-journey history will appear here
+						when the spans have the necessary datapoints.
+					</Typography>
+				</div>
+			</div>
+			<Button
+				variant="solid"
+				color="secondary"
+				size="md"
+				suffix={<ArrowRight size={12} />}
+				onClick={(): void => {
+					openInNewTab(LLM_OBSERVABILITY_DOCS_URL);
+				}}
+				testId="thread-empty-learn-more"
+			>
+				Learn more
+			</Button>
+		</div>
+	);
+}
+
+export default ThreadNoAiSpans;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadPageLoader.tsx

@@ -0,0 +1,23 @@
+import { Skeleton } from '@signozhq/ui/skeleton';
+
+import styles from './ThreadSpanList.module.scss';
+
+interface ThreadPageLoaderProps {
+	testId: string;
+}
+
+// Mirrors a span card: a short message, then an output with a block and a chip.
+function ThreadPageLoader({ testId }: ThreadPageLoaderProps): JSX.Element {
+	return (
+		<div className={styles.pageLoader} data-testid={testId}>
+			<Skeleton active title={{ width: 48 }} paragraph={{ rows: 1 }} />
+			<Skeleton
+				active
+				title={{ width: 112 }}
+				paragraph={{ rows: 3, width: ['100%', '100%', 160] }}
+			/>
+		</div>
+	);
+}
+
+export default ThreadPageLoader;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanCard.module.scss

@@ -0,0 +1,29 @@
+.card {
+	position: relative;
+	padding: var(--spacing-8);
+	border: 1px solid var(--l2-border);
+	border-radius: var(--radius-2);
+	background: var(--l1-background);
+	min-width: 0;
+	cursor: pointer;
+
+	&:hover {
+		border-color: var(--l3-border);
+	}
+
+	&:focus-visible {
+		outline: 1px solid var(--primary);
+		outline-offset: var(--spacing-1);
+	}
+
+	&.isSelected::before {
+		content: '';
+		position: absolute;
+		top: -1px;
+		bottom: -1px;
+		left: -1px;
+		width: 2px;
+		border-radius: var(--radius-2) 0 0 var(--radius-2);
+		background: var(--primary-background);
+	}
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanCard.tsx

@@ -0,0 +1,67 @@
+import { KeyboardEvent, memo, useMemo, useRef } from 'react';
+import cx from 'classnames';
+
+import { useToolCallLinks } from '../AIThreadMessage/useToolCallLinks';
+import SpanMessages from '../SpanMessages/SpanMessages';
+import { ThreadSpan, ThreadView } from './types';
+import { buildToolCallIndex } from './utils';
+
+import styles from './ThreadSpanCard.module.scss';
+
+interface ThreadSpanCardProps {
+	span: ThreadSpan;
+	view: ThreadView;
+	isSelected: boolean;
+	onSelect: (span: ThreadSpan) => void;
+}
+
+function ThreadSpanCard({
+	span,
+	view,
+	isSelected,
+	onSelect,
+}: ThreadSpanCardProps): JSX.Element {
+	const cardRef = useRef<HTMLDivElement>(null);
+	// A result links only to a call in its own span.
+	const toolCallKeys = useMemo(() => buildToolCallIndex(span), [span]);
+	const { canLinkToToolCall, onToolLinkClick } = useToolCallLinks(
+		cardRef,
+		toolCallKeys,
+	);
+
+	const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
+		// Keys pressed on the card's own controls stay with them.
+		if (event.target !== event.currentTarget) {
+			return;
+		}
+		if (event.key === 'Enter' || event.key === ' ') {
+			event.preventDefault();
+			onSelect(span);
+		}
+	};
+
+	return (
+		<div
+			ref={cardRef}
+			// eslint-disable-next-line jsx-a11y/prefer-tag-over-role -- a <button> can't nest the card's own buttons
+			role="button"
+			tabIndex={0}
+			aria-pressed={isSelected}
+			aria-label={`Span ${span.name}`}
+			className={cx(styles.card, isSelected && styles.isSelected)}
+			onClick={(): void => onSelect(span)}
+			onKeyDown={handleKeyDown}
+			data-span-id={span.span_id}
+			data-testid="thread-span-card"
+		>
+			<SpanMessages
+				span={span}
+				view={view}
+				canLinkToToolCall={canLinkToToolCall}
+				onToolLinkClick={onToolLinkClick}
+			/>
+		</div>
+	);
+}
+
+export default memo(ThreadSpanCard);

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanDetails.tsx

@@ -0,0 +1,83 @@
+import { useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { DetailsPanelState } from 'components/DetailsPanel/types';
+import { ResizableBox } from 'periscope/components/ResizableBox';
+import { TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
+
+import SpanDetailsPanel from '../SpanDetailsPanel/SpanDetailsPanel';
+import {
+	SPAN_DETAILS_PANEL_MIN_WIDTH,
+	SpanDetailVariant,
+} from '../SpanDetailsPanel/constants';
+import { useTraceSummary } from '../TraceDetailsHeader/useTraceSummary';
+import { ThreadSpan } from './types';
+
+import styles from './TraceDetailsThread.module.scss';
+
+const RIGHT_DOCK_MIN = SPAN_DETAILS_PANEL_MIN_WIDTH;
+const RIGHT_DOCK_MAX = 720;
+const BOTTOM_DOCK_DEFAULT = 360;
+const BOTTOM_DOCK_MIN = 200;
+
+interface ThreadSpanDetailsProps {
+	panelState: DetailsPanelState;
+	span: ThreadSpan;
+	variant: SpanDetailVariant;
+	onVariantChange: (variant: SpanDetailVariant) => void;
+}
+
+function ThreadSpanDetails({
+	panelState,
+	span,
+	variant,
+	onVariantChange,
+}: ThreadSpanDetailsProps): JSX.Element {
+	const [width, setWidth] = useState(RIGHT_DOCK_MIN);
+	const [height, setHeight] = useState(BOTTOM_DOCK_DEFAULT);
+	const { id: traceId } = useParams<TraceDetailV3URLProps>();
+	const { data: traceSummary } = useTraceSummary(traceId);
+
+	const panel = (
+		<SpanDetailsPanel
+			panelState={panelState}
+			selectedSpan={span}
+			variant={variant}
+			onVariantChange={onVariantChange}
+			traceStartTime={traceSummary?.startTimestampMillis}
+			traceEndTime={traceSummary?.endTimestampMillis}
+		/>
+	);
+
+	if (variant === SpanDetailVariant.DOCKED_RIGHT) {
+		return (
+			<ResizableBox
+				handle="left"
+				defaultWidth={width}
+				minWidth={RIGHT_DOCK_MIN}
+				maxWidth={RIGHT_DOCK_MAX}
+				onResize={setWidth}
+				className={styles.rightDock}
+			>
+				{panel}
+			</ResizableBox>
+		);
+	}
+
+	if (variant === SpanDetailVariant.DOCKED) {
+		return (
+			<ResizableBox
+				handle="top"
+				defaultHeight={height}
+				minHeight={BOTTOM_DOCK_MIN}
+				onResize={setHeight}
+				className={styles.bottomDock}
+			>
+				{panel}
+			</ResizableBox>
+		);
+	}
+
+	return panel;
+}
+
+export default ThreadSpanDetails;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanList.module.scss

@@ -0,0 +1,29 @@
+@use '../../../styles/scrollbar' as *;
+
+.list {
+	@include custom-scrollbar;
+
+	flex: 1;
+	min-height: 0;
+	margin-bottom: var(--spacing-4);
+}
+
+// Padding, not margin: Virtuoso measures item boxes.
+.item {
+	padding: var(--spacing-6) var(--spacing-8) 0;
+}
+
+.footer {
+	padding-bottom: var(--spacing-6);
+}
+
+.pageLoader {
+	flex-shrink: 0;
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-10);
+	padding: var(--spacing-8);
+	border: 1px solid var(--l2-border);
+	border-radius: var(--radius-2);
+	background: var(--l1-background);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanList.tsx

@@ -0,0 +1,94 @@
+import { ReactNode, useCallback, useMemo } from 'react';
+import { Virtuoso } from 'react-virtuoso';
+
+import ThreadPageLoader from './ThreadPageLoader';
+import { ThreadSpan } from './types';
+
+import styles from './ThreadSpanList.module.scss';
+
+// Virtuoso needs a positive index it can decrease as older spans are prepended.
+const FIRST_ITEM_INDEX_BASE = 1_000_000;
+const LOAD_AHEAD_PX = 200;
+
+interface ThreadSpanListProps {
+	spans: ThreadSpan[];
+	spansAboveFirstPage: number;
+	initialSpanIndex?: number;
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	isFetchingNextPage: boolean;
+	isFetchingPreviousPage: boolean;
+	fetchNextPage: () => Promise<unknown>;
+	fetchPreviousPage: () => Promise<unknown>;
+	renderSpan: (span: ThreadSpan) => ReactNode;
+}
+
+function ThreadSpanList({
+	spans,
+	spansAboveFirstPage,
+	initialSpanIndex,
+	hasNextPage,
+	hasPreviousPage,
+	isFetchingNextPage,
+	isFetchingPreviousPage,
+	fetchNextPage,
+	fetchPreviousPage,
+	renderSpan,
+}: ThreadSpanListProps): JSX.Element {
+	const handleEndReached = useCallback((): void => {
+		if (hasNextPage && !isFetchingNextPage) {
+			void fetchNextPage();
+		}
+	}, [hasNextPage, isFetchingNextPage, fetchNextPage]);
+
+	const handleStartReached = useCallback((): void => {
+		if (hasPreviousPage && !isFetchingPreviousPage) {
+			void fetchPreviousPage();
+		}
+	}, [hasPreviousPage, isFetchingPreviousPage, fetchPreviousPage]);
+
+	const components = useMemo(
+		() => ({
+			Header: (): JSX.Element | null =>
+				hasPreviousPage || isFetchingPreviousPage ? (
+					<div className={styles.item}>
+						<ThreadPageLoader testId="thread-loading-previous" />
+					</div>
+				) : null,
+			Footer: (): JSX.Element => (
+				<div className={styles.footer}>
+					{isFetchingNextPage && (
+						<div className={styles.item}>
+							<ThreadPageLoader testId="thread-loading-next" />
+						</div>
+					)}
+				</div>
+			),
+		}),
+		[hasPreviousPage, isFetchingPreviousPage, isFetchingNextPage],
+	);
+
+	return (
+		<Virtuoso
+			className={styles.list}
+			data-testid="thread-span-list"
+			data={spans}
+			// 0 is allowed, negative is not (Virtuoso warns); the base fits 1,000,000 prepended spans.
+			firstItemIndex={FIRST_ITEM_INDEX_BASE - spansAboveFirstPage}
+			// Omitted, not undefined: an explicit undefined blanks the list, and 0 resets an early scroll.
+			{...(initialSpanIndex === undefined
+				? {}
+				: { initialTopMostItemIndex: initialSpanIndex })}
+			increaseViewportBy={LOAD_AHEAD_PX}
+			computeItemKey={(_, span): string => span.span_id}
+			itemContent={(_, span): JSX.Element => (
+				<div className={styles.item}>{renderSpan(span)}</div>
+			)}
+			startReached={handleStartReached}
+			endReached={handleEndReached}
+			components={components}
+		/>
+	);
+}
+
+export default ThreadSpanList;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanNotFound.module.scss

@@ -0,0 +1,32 @@
+.root {
+	flex: 1;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	gap: var(--spacing-4);
+	padding: var(--spacing-16);
+	text-align: center;
+}
+
+.icon {
+	color: var(--l2-foreground);
+}
+
+.title {
+	font-size: var(--periscope-font-size-medium);
+	font-weight: var(--font-weight-medium);
+	color: var(--l1-foreground);
+}
+
+.description {
+	max-width: 420px;
+	font-size: var(--periscope-font-size-base);
+	color: var(--l2-foreground);
+}
+
+.actions {
+	display: flex;
+	gap: var(--spacing-4);
+	margin-top: var(--spacing-4);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanNotFound.tsx

@@ -0,0 +1,50 @@
+import { Button } from '@signozhq/ui/button';
+import { ArrowLeft, MessagesSquare, SearchX } from '@signozhq/icons';
+
+import styles from './ThreadSpanNotFound.module.scss';
+
+interface ThreadSpanNotFoundProps {
+	onGoBack: () => void;
+	onShowThread: () => void;
+}
+
+function ThreadSpanNotFound({
+	onGoBack,
+	onShowThread,
+}: ThreadSpanNotFoundProps): JSX.Element {
+	return (
+		<div className={styles.root} data-testid="thread-span-not-found">
+			<span className={styles.icon}>
+				<SearchX size={32} />
+			</span>
+			<span className={styles.title}>Span not found in this thread</span>
+			<span className={styles.description}>
+				The requested span isn&apos;t part of this trace&apos;s AI thread.
+			</span>
+			<div className={styles.actions}>
+				<Button
+					variant="outlined"
+					color="secondary"
+					size="md"
+					prefix={<ArrowLeft size={14} />}
+					onClick={onGoBack}
+					testId="thread-span-not-found-go-back"
+				>
+					Go back
+				</Button>
+				<Button
+					variant="solid"
+					color="primary"
+					size="md"
+					prefix={<MessagesSquare size={14} />}
+					onClick={onShowThread}
+					testId="thread-span-not-found-show-thread"
+				>
+					Show thread
+				</Button>
+			</div>
+		</div>
+	);
+}
+
+export default ThreadSpanNotFound;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadViewToggle.tsx

@@ -0,0 +1,46 @@
+import { ToggleGroup } from '@signozhq/ui/toggle-group';
+
+import { ThreadView } from './types';
+
+const VIEW_OPTIONS = [
+	{ label: 'Formatted', value: ThreadView.Formatted },
+	{ label: 'JSON', value: ThreadView.Json },
+];
+
+interface ThreadViewToggleProps {
+	value: ThreadView;
+	onChange: (view: ThreadView) => void;
+	testId?: string;
+}
+
+function ThreadViewToggle({
+	value,
+	onChange,
+	testId,
+}: ThreadViewToggleProps): JSX.Element {
+	const handleChange = (next: string): void => {
+		// Clicking the active item deselects it and reports ''.
+		if (next) {
+			onChange(next as ThreadView);
+		}
+	};
+
+	return (
+		<ToggleGroup
+			variant="outlined"
+			color="secondary"
+			type="single"
+			size="sm"
+			value={value}
+			onChange={handleChange}
+			items={VIEW_OPTIONS}
+			testId={testId}
+		/>
+	);
+}
+
+ThreadViewToggle.defaultProps = {
+	testId: 'thread-view-toggle',
+};
+
+export default ThreadViewToggle;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/TraceDetailsThread.module.scss

@@ -0,0 +1,50 @@
+.root {
+	flex: 1;
+	min-height: 0;
+	display: flex;
+	overflow: hidden;
+	border-top: 1px solid var(--l2-border);
+}
+
+.content {
+	flex: 1;
+	min-width: 0;
+	display: flex;
+	flex-direction: column;
+}
+
+.toolbar {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-4);
+	padding: var(--spacing-4) var(--spacing-8);
+	border-bottom: 1px solid var(--l2-border);
+	font-size: var(--font-size-xs);
+	color: var(--l2-foreground);
+}
+
+.notice {
+	margin: var(--spacing-6) var(--spacing-8) var(--spacing-4);
+}
+
+.initialLoader {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-6);
+	padding: var(--spacing-6) var(--spacing-8);
+}
+
+.bottomDock {
+	display: flex;
+	flex-direction: column;
+	min-height: 0;
+	border-top: 1px solid var(--l2-border);
+}
+
+.rightDock {
+	display: flex;
+	flex-direction: column;
+	min-width: 0;
+	border-left: 1px solid var(--l2-border);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/TraceDetailsThread.tsx

@@ -0,0 +1,165 @@
+import { useParams } from 'react-router-dom';
+import { Callout } from '@signozhq/ui/callout';
+import history, { hasInAppHistory } from 'lib/history';
+import { TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
+
+import { TraceDetailsTab } from '../constants';
+import { useSpanDetailVariant } from '../hooks/useSpanDetailVariant';
+import { useTraceDetailsTab } from '../hooks/useTraceDetailsTab';
+import { SpanDetailVariant } from '../SpanDetailsPanel/constants';
+import { useThreadSpanSelection } from './hooks/useThreadSpanSelection';
+import { useThreadView } from './hooks/useThreadView';
+import { useTraceThread } from './hooks/useTraceThread';
+import ThreadNoAiSpans from './ThreadNoAiSpans';
+import ThreadPageLoader from './ThreadPageLoader';
+import ThreadSpanCard from './ThreadSpanCard';
+import ThreadSpanDetails from './ThreadSpanDetails';
+import ThreadSpanList from './ThreadSpanList';
+import ThreadSpanNotFound from './ThreadSpanNotFound';
+import ThreadViewToggle from './ThreadViewToggle';
+import { InterestedSpanStatus } from './types';
+import { getInterestedSpanStatus } from './utils';
+
+import styles from './TraceDetailsThread.module.scss';
+
+const INITIAL_LOADER_COUNT = 4;
+
+function TraceDetailsThread(): JSX.Element {
+	const { id: traceId } = useParams<TraceDetailV3URLProps>();
+	const [, setTab] = useTraceDetailsTab();
+	const [view, setView] = useThreadView();
+	const {
+		interestedSpanId,
+		clearInterestedSpan,
+		selectedSpanId,
+		selectSpan,
+		panelState,
+	} = useThreadSpanSelection();
+	const {
+		spans,
+		spansAboveFirstPage,
+		isLoading,
+		isError,
+		hasNextPage,
+		hasPreviousPage,
+		isFetchingNextPage,
+		isFetchingPreviousPage,
+		fetchNextPage,
+		fetchPreviousPage,
+	} = useTraceThread({ traceId: traceId || '', interestedSpanId });
+
+	const interestedSpanStatus = getInterestedSpanStatus(
+		interestedSpanId,
+		spans,
+		isLoading,
+	);
+	const interestedSpanIndex = spans.findIndex(
+		(span) => span.span_id === interestedSpanId,
+	);
+
+	const selectedSpan = spans.find((span) => span.span_id === selectedSpanId);
+	const [spanDetailVariant, setSpanDetailVariant] = useSpanDetailVariant();
+	const isBottomDocked = spanDetailVariant === SpanDetailVariant.DOCKED;
+
+	const spanDetails = panelState.isOpen && selectedSpan && (
+		<ThreadSpanDetails
+			panelState={panelState}
+			span={selectedSpan}
+			variant={spanDetailVariant}
+			onVariantChange={setSpanDetailVariant}
+		/>
+	);
+	const hasNoThread =
+		!isLoading &&
+		interestedSpanStatus !== InterestedSpanStatus.NotFound &&
+		(isError || spans.length === 0);
+
+	const renderBody = (): JSX.Element => {
+		if (isLoading) {
+			return (
+				<div className={styles.initialLoader} data-testid="thread-loading">
+					{Array.from({ length: INITIAL_LOADER_COUNT }).map((_, i) => (
+						// eslint-disable-next-line react/no-array-index-key
+						<ThreadPageLoader key={i} testId="thread-loading-item" />
+					))}
+				</div>
+			);
+		}
+		if (interestedSpanStatus === InterestedSpanStatus.NotFound) {
+			return (
+				<ThreadSpanNotFound
+					onGoBack={(): void => {
+						// go back to the previous page
+						if (hasInAppHistory()) {
+							history.goBack();
+						} else {
+							void setTab(TraceDetailsTab.Overview);
+						}
+					}}
+					onShowThread={clearInterestedSpan}
+				/>
+			);
+		}
+		if (hasNoThread) {
+			return <ThreadNoAiSpans />;
+		}
+		return (
+			<>
+				{interestedSpanStatus === InterestedSpanStatus.NoIOMessages && (
+					<Callout
+						type="info"
+						size="small"
+						className={styles.notice}
+						title="The requested span has no input or output messages. Showing the rest of the thread."
+						testId="thread-anchor-no-messages"
+					/>
+				)}
+				<ThreadSpanList
+					key={interestedSpanId}
+					spans={spans}
+					spansAboveFirstPage={spansAboveFirstPage}
+					initialSpanIndex={
+						interestedSpanIndex === -1 ? undefined : interestedSpanIndex
+					}
+					hasNextPage={hasNextPage}
+					hasPreviousPage={hasPreviousPage}
+					isFetchingNextPage={isFetchingNextPage}
+					isFetchingPreviousPage={isFetchingPreviousPage}
+					fetchNextPage={fetchNextPage}
+					fetchPreviousPage={fetchPreviousPage}
+					renderSpan={(span): JSX.Element => (
+						<ThreadSpanCard
+							span={span}
+							view={view}
+							isSelected={span.span_id === selectedSpanId}
+							onSelect={selectSpan}
+						/>
+					)}
+				/>
+			</>
+		);
+	};
+
+	return (
+		<div className={styles.root} data-testid="trace-details-thread">
+			<div className={styles.content}>
+				{!hasNoThread && interestedSpanStatus !== InterestedSpanStatus.NotFound && (
+					<div className={styles.toolbar}>
+						<ThreadViewToggle
+							value={view}
+							onChange={(next): void => {
+								void setView(next);
+							}}
+						/>
+						{spans.length > 0 && <span>Showing {spans.length} spans</span>}
+					</div>
+				)}
+				{renderBody()}
+				{isBottomDocked && spanDetails}
+			</div>
+			{!isBottomDocked && spanDetails}
+		</div>
+	);
+}
+
+export default TraceDetailsThread;

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/__tests__/useTraceThread.test.tsx

@@ -0,0 +1,166 @@
+import { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from 'react-query';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { getTraceThread } from 'api/generated/services/tracedetail';
+
+import { useTraceThread } from '../useTraceThread';
+
+jest.mock('api/generated/services/tracedetail', () => ({
+	getGetTraceThreadQueryKey: (...args: unknown[]): unknown[] => [
+		'thread',
+		...args,
+	],
+	getTraceThread: jest.fn(),
+}));
+
+const mockGetTraceThread = jest.mocked(getTraceThread);
+
+type ThreadResponse = Awaited<ReturnType<typeof getTraceThread>>;
+
+const SPANS_PER_PAGE = 3;
+const LAST_PAGE = 2;
+
+// Page n is reached with `before: c{n+1}` or `after: c{n-1}`.
+function page(n: number): ThreadResponse {
+	return {
+		data: {
+			spans: Array.from({ length: SPANS_PER_PAGE }, (_, i) => ({
+				span_id: `span-${n}-${i}`,
+			})),
+			prevCursor: n > 0 ? `c${n}` : undefined,
+			nextCursor: n < LAST_PAGE ? `c${n}` : undefined,
+		},
+	} as unknown as ThreadResponse;
+}
+
+function cursorPage(cursor: string, offset: number): number {
+	return Number(cursor.slice(1)) + offset;
+}
+
+// The first request returns the last page unless the interested span maps to another.
+function mockThread(firstPageBySpanId: Record<string, number> = {}): void {
+	mockGetTraceThread.mockImplementation((_path, params) => {
+		const { before, after, spanId } = params ?? {};
+		if (before) {
+			return Promise.resolve(page(cursorPage(before, -1)));
+		}
+		if (after) {
+			return Promise.resolve(page(cursorPage(after, 1)));
+		}
+		return Promise.resolve(page(firstPageBySpanId[spanId ?? ''] ?? LAST_PAGE));
+	});
+}
+
+function httpError(status: number): Error {
+	return Object.assign(new Error(`HTTP ${status}`), {
+		isAxiosError: true,
+		response: { status },
+	});
+}
+
+function renderThread(interestedSpanId = 'span'): {
+	result: { current: ReturnType<typeof useTraceThread> };
+	rerender: (props: { interestedSpanId: string }) => void;
+	queryClient: QueryClient;
+} {
+	const queryClient = new QueryClient({
+		defaultOptions: { queries: { retry: false, retryDelay: 0 } },
+	});
+	const wrapper = ({ children }: { children: ReactNode }): JSX.Element => (
+		<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+	);
+	const { result, rerender } = renderHook(
+		(props: { interestedSpanId: string }) =>
+			useTraceThread({ traceId: 'trace', ...props }),
+		{ wrapper, initialProps: { interestedSpanId } },
+	);
+	return { result, rerender, queryClient };
+}
+
+describe('useTraceThread', () => {
+	beforeEach(() => {
+		mockGetTraceThread.mockReset();
+		mockThread();
+	});
+
+	it('counts spans prepended above the first page', async () => {
+		const { result } = renderThread();
+		await waitFor(() => expect(result.current.spans).toHaveLength(3));
+		expect(result.current.spansAboveFirstPage).toBe(0);
+
+		await act(() => result.current.fetchPreviousPage());
+		await act(() => result.current.fetchPreviousPage());
+
+		expect(result.current.spans).toHaveLength(9);
+		expect(result.current.spansAboveFirstPage).toBe(6);
+	});
+
+	it('does not count spans appended below the first page', async () => {
+		mockThread({ span: 0 });
+		const { result } = renderThread();
+		await waitFor(() => expect(result.current.spans).toHaveLength(3));
+
+		await act(() => result.current.fetchNextPage());
+		await act(() => result.current.fetchNextPage());
+
+		expect(result.current.spans).toHaveLength(9);
+		expect(result.current.spansAboveFirstPage).toBe(0);
+	});
+
+	it('keeps spansAboveFirstPage stable across a refetch', async () => {
+		const { result, queryClient } = renderThread();
+		await waitFor(() => expect(result.current.spans).toHaveLength(3));
+		await act(() => result.current.fetchPreviousPage());
+		await act(() => result.current.fetchPreviousPage());
+
+		await act(() => queryClient.refetchQueries());
+
+		expect(result.current.spans).toHaveLength(9);
+		expect(result.current.spansAboveFirstPage).toBe(6);
+	});
+
+	it('sends the interested span only with the first request', async () => {
+		const { result } = renderThread();
+		await waitFor(() => expect(result.current.spans).toHaveLength(3));
+		await act(() => result.current.fetchPreviousPage());
+
+		const params = mockGetTraceThread.mock.calls.map(([, query]) => query);
+		expect(params).toStrictEqual([
+			expect.objectContaining({ spanId: 'span', before: undefined }),
+			expect.objectContaining({ spanId: undefined, before: 'c2' }),
+		]);
+	});
+
+	it('re-anchors when the interested span changes', async () => {
+		mockThread({ other: 1 });
+		const { result, rerender } = renderThread();
+		await waitFor(() => expect(result.current.spans).toHaveLength(3));
+		await act(() => result.current.fetchPreviousPage());
+		expect(result.current.spansAboveFirstPage).toBe(3);
+
+		rerender({ interestedSpanId: 'other' });
+		await waitFor(() =>
+			expect(result.current.spans[0]?.span_id).toBe('span-1-0'),
+		);
+		await act(() => result.current.fetchPreviousPage());
+
+		expect(result.current.spans).toHaveLength(6);
+		expect(result.current.spansAboveFirstPage).toBe(3);
+	});
+
+	it('does not retry a 404', async () => {
+		mockGetTraceThread.mockRejectedValue(httpError(404));
+		const { result } = renderThread();
+
+		await waitFor(() => expect(result.current.isError).toBe(true));
+		expect(mockGetTraceThread).toHaveBeenCalledTimes(1);
+	});
+
+	it('retries other errors', async () => {
+		mockGetTraceThread.mockRejectedValue(httpError(500));
+		const { result } = renderThread();
+
+		await waitFor(() => expect(result.current.isError).toBe(true));
+		expect(mockGetTraceThread).toHaveBeenCalledTimes(4);
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/useThreadSpanSelection.ts

@@ -0,0 +1,80 @@
+import { useCallback, useMemo, useState } from 'react';
+import { useDetailsPanel } from 'components/DetailsPanel';
+import { DetailsPanelState } from 'components/DetailsPanel/types';
+import { useSafeNavigate } from 'hooks/useSafeNavigate';
+import useUrlQuery from 'hooks/useUrlQuery';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
+
+import { ThreadSpan } from '../types';
+
+const SPAN_ID_PARAM = 'spanId';
+
+interface ThreadSpanSelection {
+	// The spanId the thread was opened with; it shapes the first page fetched.
+	interestedSpanId?: string;
+	clearInterestedSpan: () => void;
+	selectedSpanId?: string;
+	selectSpan: (span: ThreadSpan) => void;
+	panelState: DetailsPanelState;
+}
+
+export function useThreadSpanSelection(): ThreadSpanSelection {
+	const urlQuery = useUrlQuery();
+	const { safeNavigate } = useSafeNavigate();
+	const selectedSpanId = urlQuery.get(SPAN_ID_PARAM) || undefined;
+	const [interestedSpanId, setInterestedSpanId] = useState(selectedSpanId);
+
+	const setSpanIdParam = useCallback(
+		(spanId?: string): void => {
+			const params = getUnstableCurrentSearchParams();
+			if (spanId) {
+				params.set(SPAN_ID_PARAM, spanId);
+			} else {
+				params.delete(SPAN_ID_PARAM);
+			}
+			safeNavigate({ search: params.toString() }, { replace: true });
+		},
+		[safeNavigate],
+	);
+
+	const handleClose = useCallback(
+		(): void => setSpanIdParam(undefined),
+		[setSpanIdParam],
+	);
+
+	const panelState = useDetailsPanel({
+		entityId: selectedSpanId,
+		onClose: handleClose,
+	});
+
+	const { open: openPanel } = panelState;
+	const selectSpan = useCallback(
+		(span: ThreadSpan): void => {
+			setSpanIdParam(span.span_id);
+			openPanel();
+		},
+		[setSpanIdParam, openPanel],
+	);
+
+	const clearInterestedSpan = useCallback((): void => {
+		setInterestedSpanId(undefined);
+		setSpanIdParam(undefined);
+	}, [setSpanIdParam]);
+
+	return useMemo(
+		() => ({
+			interestedSpanId,
+			clearInterestedSpan,
+			selectedSpanId,
+			selectSpan,
+			panelState,
+		}),
+		[
+			interestedSpanId,
+			clearInterestedSpan,
+			selectedSpanId,
+			selectSpan,
+			panelState,
+		],
+	);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/useThreadView.ts

@@ -0,0 +1,12 @@
+import { parseAsStringEnum, useQueryState, UseQueryStateReturn } from 'nuqs';
+
+import { ThreadView } from '../types';
+
+export function useThreadView(): UseQueryStateReturn<ThreadView, ThreadView> {
+	return useQueryState(
+		'view',
+		parseAsStringEnum(Object.values(ThreadView)).withDefault(
+			ThreadView.Formatted,
+		),
+	);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/useTraceThread.ts

@@ -0,0 +1,109 @@
+import { useMemo, useRef } from 'react';
+import { useInfiniteQuery } from 'react-query';
+import {
+	getGetTraceThreadQueryKey,
+	getTraceThread,
+} from 'api/generated/services/tracedetail';
+import type { GetTraceThreadParams } from 'api/generated/services/sigNoz.schemas';
+
+import { ThreadSpan } from '../types';
+import { isNotFoundError, toThreadSpan } from '../utils';
+
+const THREAD_PAGE_LIMIT = 100;
+const MAX_RETRIES = 3;
+const STALE_TIME_MS = 5 * 60 * 1000;
+
+type PageParam = Pick<GetTraceThreadParams, 'after' | 'before'>;
+
+interface UseTraceThreadOptions {
+	traceId: string;
+	interestedSpanId?: string;
+}
+
+interface UseTraceThreadResult {
+	spans: ThreadSpan[];
+	spansAboveFirstPage: number;
+	isLoading: boolean;
+	isError: boolean;
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	isFetchingNextPage: boolean;
+	isFetchingPreviousPage: boolean;
+	fetchNextPage: () => Promise<unknown>;
+	fetchPreviousPage: () => Promise<unknown>;
+}
+
+export function useTraceThread({
+	traceId,
+	interestedSpanId,
+}: UseTraceThreadOptions): UseTraceThreadResult {
+	const query = useInfiniteQuery({
+		queryKey: getGetTraceThreadQueryKey(
+			{ traceID: traceId },
+			{ spanId: interestedSpanId },
+		),
+		queryFn: ({ pageParam, signal }) => {
+			const { after, before } = (pageParam ?? {}) as PageParam;
+			return getTraceThread(
+				{ traceID: traceId },
+				{
+					limit: THREAD_PAGE_LIMIT,
+					after,
+					before,
+					// The interested span only shapes the first page; cursors drive the rest.
+					spanId: after || before ? undefined : interestedSpanId,
+				},
+				signal,
+			);
+		},
+		getNextPageParam: (lastPage): PageParam | undefined =>
+			lastPage.data.nextCursor ? { after: lastPage.data.nextCursor } : undefined,
+		getPreviousPageParam: (firstPage): PageParam | undefined =>
+			firstPage.data.prevCursor
+				? { before: firstPage.data.prevCursor }
+				: undefined,
+		// An unknown interested span is a 404; retrying won't find it.
+		retry: (failureCount, error): boolean =>
+			!isNotFoundError(error) && failureCount < MAX_RETRIES,
+		enabled: !!traceId,
+		refetchOnWindowFocus: false,
+		staleTime: STALE_TIME_MS,
+	});
+
+	const spans = useMemo(
+		() =>
+			query.data?.pages.flatMap((page) => page.data.spans.map(toThreadSpan)) ?? [],
+		[query.data],
+	);
+
+	// Index of the first span shown on mount, so it grows only on prepend (Virtuoso's firstItemIndex).
+	// Not from pageParams: a react-query v3 refetch rebuilds later pages with `after` cursors.
+	const anchorRef = useRef<{ key: string; spanId: string }>();
+	const anchorKey = `${traceId}:${interestedSpanId ?? ''}`;
+	const spansAboveFirstPage = useMemo(() => {
+		if (spans.length === 0) {
+			return 0;
+		}
+		if (anchorRef.current?.key !== anchorKey) {
+			anchorRef.current = { key: anchorKey, spanId: spans[0].span_id };
+		}
+		const { spanId } = anchorRef.current;
+		return Math.max(
+			0,
+			spans.findIndex((span) => span.span_id === spanId),
+		);
+	}, [spans, anchorKey]);
+
+	return {
+		spans,
+		spansAboveFirstPage,
+		isLoading: query.isLoading,
+		isError: query.isError,
+		hasNextPage: !!query.hasNextPage,
+		hasPreviousPage: !!query.hasPreviousPage,
+		isFetchingNextPage: query.isFetchingNextPage,
+		isFetchingPreviousPage: query.isFetchingPreviousPage,
+		fetchNextPage: query.fetchNextPage,
+		fetchPreviousPage: query.fetchPreviousPage,
+	};
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/types.ts

@@ -0,0 +1,22 @@
+import { SpanV3 } from 'types/api/trace/getTraceV3';
+
+import { ThreadMessage } from '../AIThreadMessage/types';
+
+export type ThreadSpan = SpanV3 & {
+	formattedInput?: ThreadMessage[];
+	formattedOutput?: ThreadMessage[];
+};
+
+export enum ThreadView {
+	Formatted = 'formatted',
+	Json = 'json',
+}
+
+export enum InterestedSpanStatus {
+	None = 'none',
+	Loading = 'loading',
+	Found = 'found',
+	// Backend anchors on the span's position but drops it for lacking messages.
+	NoIOMessages = 'noIOMessages',
+	NotFound = 'notFound',
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/utils.ts

@@ -0,0 +1,44 @@
+import type { SpantypesThreadSpanDTO } from 'api/generated/services/sigNoz.schemas';
+import { isAxiosError } from 'axios';
+
+import { collectToolCallKeys } from '../AIThreadMessage/utils';
+import { InterestedSpanStatus, ThreadSpan } from './types';
+
+/** Derives SpanV3's `timestamp` and `service.name`, as the waterfall does. */
+export function toThreadSpan(span: SpantypesThreadSpanDTO): ThreadSpan {
+	return {
+		...(span as unknown as ThreadSpan),
+		'service.name': span.resource?.['service.name'] || '',
+		timestamp: span.time_unix,
+	};
+}
+
+export function isNotFoundError(error: unknown): boolean {
+	return isAxiosError(error) && error.response?.status === 404;
+}
+
+export function buildToolCallIndex(span: ThreadSpan): Set<string> {
+	return new Set([
+		...collectToolCallKeys(span.formattedInput ?? []),
+		...collectToolCallKeys(span.formattedOutput ?? []),
+	]);
+}
+
+export function getInterestedSpanStatus(
+	interestedSpanId: string | undefined,
+	spans: ThreadSpan[],
+	isLoading: boolean,
+): InterestedSpanStatus {
+	if (!interestedSpanId) {
+		return InterestedSpanStatus.None;
+	}
+	if (isLoading) {
+		return InterestedSpanStatus.Loading;
+	}
+	if (spans.length === 0) {
+		return InterestedSpanStatus.NotFound;
+	}
+	return spans.some((span) => span.span_id === interestedSpanId)
+		? InterestedSpanStatus.Found
+		: InterestedSpanStatus.NoIOMessages;
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsWrapper/TraceDetailsWrapper.module.scss

@@ -0,0 +1,6 @@
+.root {
+	flex: 1;
+	min-height: 0;
+	display: flex;
+	flex-direction: column;
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsWrapper/TraceDetailsWrapper.tsx

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+
+import TraceStoreSync from '../stores/TraceStoreSync';
+
+import styles from './TraceDetailsWrapper.module.scss';
+
+interface TraceDetailsWrapperProps {
+	children: ReactNode;
+}
+
+function TraceDetailsWrapper({
+	children,
+}: TraceDetailsWrapperProps): JSX.Element {
+	return (
+		<TraceStoreSync>
+			<div className={styles.root}>{children}</div>
+		</TraceStoreSync>
+	);
+}
+
+export default TraceDetailsWrapper;

frontend/src/pages/TraceDetailsV3/TraceFlamegraph/TraceFlamegraph.tsx

@@ -1,8 +1,9 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import { useHistory, useLocation, useParams } from 'react-router-dom';
+import { useHistory, useParams } from 'react-router-dom';
 import { Skeleton } from 'antd';
 import useGetTraceFlamegraphV3 from 'hooks/trace/useGetTraceFlamegraphV3';
 import useUrlQuery from 'hooks/useUrlQuery';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
 import { TraceDetailFlamegraphURLProps } from 'types/api/trace/getTraceFlamegraph';
 import { SpanV3 } from 'types/api/trace/getTraceV3';
 
@@ -30,7 +31,6 @@ function TraceFlamegraph({
 	const { id: traceId } = useParams<TraceDetailFlamegraphURLProps>();
 	const urlQuery = useUrlQuery();
 	const history = useHistory();
-	const { search } = useLocation();
 	const [firstSpanAtFetchLevel, setFirstSpanAtFetchLevel] = useState<string>(
 		urlQuery.get('spanId') || '',
 	);
@@ -42,14 +42,14 @@ function TraceFlamegraph({
 	const handleSpanClick = useCallback(
 		(spanId: string): void => {
 			setFirstSpanAtFetchLevel(spanId);
-			const searchParams = new URLSearchParams(search);
+			const searchParams = getUnstableCurrentSearchParams();
 			//tood: use from query params constants
 			if (searchParams.get('spanId') !== spanId) {
 				searchParams.set('spanId', spanId);
 				history.replace({ search: searchParams.toString() });
 			}
 		},
-		[history, search],
+		[history],
 	);
 
 	const previewFields = useTraceStore((s) => s.previewFields);

frontend/src/pages/TraceDetailsV3/TraceWaterfall/TraceWaterfallStates/Success/Filters/Filters.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
-import { useHistory, useLocation } from 'react-router-dom';
+import { useHistory } from 'react-router-dom';
 import { ArrowRightFromLine, Search, X } from '@signozhq/icons';
 import { Switch } from '@signozhq/ui/switch';
 import { ToggleGroup } from '@signozhq/ui/toggle-group';
@@ -12,6 +12,7 @@ import { ENTITY_VERSION_V5 } from 'constants/app';
 import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
 import { useGetQueryRange } from 'hooks/queryBuilder/useGetQueryRange';
 import { uniqBy } from 'lodash-es';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
 import NozButton from 'pages/TraceDetailsV3/TraceDetailsHeader/NozButton';
 import CopyButton from 'periscope/components/CopyButton/CopyButton';
 import { Query } from 'types/api/queryBuilder/queryBuilderData';
@@ -163,12 +164,11 @@ function Filters({
 	const { selectedCategory, categories, handleCategoryChange } =
 		useSpanCategoryFilter(filterProps);
 
-	const { search } = useLocation();
 	const history = useHistory();
 
 	const handlePrevNext = useCallback(
 		(index: number, spanId?: string): void => {
-			const searchParams = new URLSearchParams(search);
+			const searchParams = getUnstableCurrentSearchParams();
 			if (spanId) {
 				searchParams.set('spanId', spanId);
 			} else {
@@ -177,7 +177,7 @@ function Filters({
 
 			history.replace({ search: searchParams.toString() });
 		},
-		[filteredSpanIds, history, search],
+		[filteredSpanIds, history],
 	);
 
 	const isFilterActive = committedExpression.trim().length > 0;

frontend/src/pages/TraceDetailsV3/TraceWaterfall/TraceWaterfallStates/Success/Success.tsx

@@ -25,7 +25,7 @@ import { convertTimeToRelevantUnit } from 'utils/traceUtils';
 import { useCopySpanLink } from 'hooks/trace/useCopySpanLink';
 import { useIsDarkMode } from 'hooks/useDarkMode';
 import { useSafeNavigate } from 'hooks/useSafeNavigate';
-import useUrlQuery from 'hooks/useUrlQuery';
+import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
 import { colorToRgb } from 'lib/uPlotLib/utils/generateColor';
 import {
 	ChevronDown,
@@ -676,19 +676,19 @@ function Success(props: ISuccessProps): JSX.Element {
 		setSelectedSpanToAddToFunnel(span);
 	}, []);
 
-	const urlQuery = useUrlQuery();
 	const { safeNavigate } = useSafeNavigate();
 
 	const handleSpanClick = useCallback(
 		(span: SpanV3): void => {
 			setSelectedSpan(span);
+			const params = getUnstableCurrentSearchParams();
 			if (span?.span_id) {
-				urlQuery.set('spanId', span?.span_id);
+				params.set('spanId', span?.span_id);
 			}
 
-			safeNavigate({ search: urlQuery.toString() }, { replace: true });
+			safeNavigate({ search: params.toString() }, { replace: true });
 		},
-		[setSelectedSpan, urlQuery, safeNavigate],
+		[setSelectedSpan, safeNavigate],
 	);
 
 	// Left side columns using TanStack React Table (extensible for future columns)

frontend/src/pages/TraceDetailsV3/TraceWaterfall/TraceWaterfallStates/Success/__tests__/UnifiedSpanClick.test.tsx

@@ -1,6 +1,10 @@
 import React from 'react';
 import { render, screen, userEvent, waitFor } from 'tests/test-utils';
 import { SpanV3 } from 'types/api/trace/getTraceV3';
+import {
+	__resetSearchParamsGetter,
+	__setSearchParamsGetterForTest,
+} from 'utils/getUnstableCurrentSearchParams';
 
 // Local identity-proxy mock for this module so `styles.foo` resolves to
 // `'foo'` in test assertions. The global `__mocks__/cssMock.ts` stays as
@@ -226,6 +230,11 @@ describe('Span Click User Flows', () => {
 		jest.clearAllMocks();
 		// Clear all URL parameters
 		Array.from(mockUrlQuery.keys()).forEach((key) => mockUrlQuery.delete(key));
+		__setSearchParamsGetterForTest(() => new URLSearchParams(mockUrlQuery));
+	});
+
+	afterEach(() => {
+		__resetSearchParamsGetter();
 	});
 
 	it('clicking span updates URL with spanId parameter', async () => {
@@ -260,7 +269,6 @@ describe('Span Click User Flows', () => {
 		) as HTMLElement;
 		await user.click(spanElement);
 
-		expect(mockUrlQuery.get('spanId')).toBe('span-1');
 		expect(mockSafeNavigate).toHaveBeenCalledWith(
 			{
 				search: expect.stringContaining('spanId=span-1'),
@@ -428,10 +436,6 @@ describe('Span Click User Flows', () => {
 		await user.click(spanElement);
 
 		// Verify existing parameters are preserved and spanId is added
-		expect(mockUrlQuery.get('existingParam')).toBe('existingValue');
-		expect(mockUrlQuery.get('anotherParam')).toBe('anotherValue');
-		expect(mockUrlQuery.get('spanId')).toBe('span-1');
-
 		expect(mockSafeNavigate).toHaveBeenCalledWith(
 			{
 				search: expect.stringMatching(
@@ -441,4 +445,41 @@ describe('Span Click User Flows', () => {
 			{ replace: true },
 		);
 	});
+
+	it('keeps a tab param the router has not seen when selecting spans', async () => {
+		const user = userEvent.setup({ pointerEventsCheck: 0 });
+
+		// nuqs wrote ?tab=thread to the real URL; react-router's copy is stale.
+		__setSearchParamsGetterForTest(() => new URLSearchParams('tab=thread'));
+
+		renderWithTraceProvider(
+			<Success
+				spans={mockSpans}
+				traceMetadata={mockTraceMetadata}
+				interestedSpanId={{ spanId: '', isUncollapsed: false }}
+				uncollapsedNodes={mockSpans.map((s) => s.span_id)}
+				isFullDataLoaded={false}
+				localUncollapsedNodes={new Set()}
+				setLocalUncollapsedNodes={jest.fn()}
+				setInterestedSpanId={jest.fn()}
+				selectedSpan={undefined}
+				setSelectedSpan={jest.fn()}
+				filteredSpanIds={[]}
+				isFilterActive={false}
+			/>,
+			undefined,
+			{ initialRoute: '/trace' },
+		);
+
+		const spanOverview = screen.getByTestId(FIRST_SPAN_TEST_ID);
+		const spanElement = spanOverview.querySelector(
+			SPAN_OVERVIEW_CLASS,
+		) as HTMLElement;
+		await user.click(spanElement);
+
+		expect(mockSafeNavigate).toHaveBeenCalledWith(
+			{ search: expect.stringMatching(/tab=thread.*spanId=span-1/) },
+			{ replace: true },
+		);
+	});
 });

frontend/src/pages/TraceDetailsV3/constants.ts

@@ -53,3 +53,11 @@ export const COLOR_BY_FIELDS: TelemetryFieldKey[] = COLOR_BY_OPTIONS.map(
 );
 
 export const DEFAULT_COLOR_BY_FIELD = COLOR_BY_FIELDS[0];
+
+export enum TraceDetailsTab {
+	Overview = 'overview',
+	Thread = 'thread',
+}
+
+export const LLM_OBSERVABILITY_DOCS_URL =
+	'https://signoz.io/docs/llm-observability/';

frontend/src/pages/TraceDetailsV3/hooks/useSpanDetailVariant.ts

@@ -0,0 +1,26 @@
+import { useCallback, useState } from 'react';
+import getLocalStorageKey from 'api/browser/localstorage/get';
+import setLocalStorageKey from 'api/browser/localstorage/set';
+import { LOCALSTORAGE } from 'constants/localStorage';
+
+import { SpanDetailVariant } from '../SpanDetailsPanel/constants';
+
+/** Span details position, persisted under the same key Overview uses. */
+export function useSpanDetailVariant(): [
+	SpanDetailVariant,
+	(variant: SpanDetailVariant) => void,
+] {
+	const [variant, setVariant] = useState<SpanDetailVariant>(
+		() =>
+			(getLocalStorageKey(
+				LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION,
+			) as SpanDetailVariant) || SpanDetailVariant.DOCKED_RIGHT,
+	);
+
+	const changeVariant = useCallback((next: SpanDetailVariant): void => {
+		setLocalStorageKey(LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION, next);
+		setVariant(next);
+	}, []);
+
+	return [variant, changeVariant];
+}

frontend/src/pages/TraceDetailsV3/hooks/useTraceDetailsTab.ts

@@ -0,0 +1,15 @@
+import { parseAsStringEnum, useQueryState, UseQueryStateReturn } from 'nuqs';
+
+import { TraceDetailsTab } from '../constants';
+
+export function useTraceDetailsTab(): UseQueryStateReturn<
+	TraceDetailsTab,
+	TraceDetailsTab
+> {
+	return useQueryState(
+		'tab',
+		parseAsStringEnum(Object.values(TraceDetailsTab)).withDefault(
+			TraceDetailsTab.Overview,
+		),
+	);
+}

frontend/src/pages/TraceDetailsV3/index.tsx

@@ -1,90 +1,21 @@
-/* eslint-disable sonarjs/cognitive-complexity */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { useParams } from 'react-router-dom';
-import {
-	ChartNoAxesGantt,
-	ChevronDown,
-	ChevronRight,
-	Info,
-	TriangleAlert,
-} from '@signozhq/icons';
-import getLocalStorageKey from 'api/browser/localstorage/get';
-import setLocalStorageKey from 'api/browser/localstorage/set';
-import { Collapse } from 'antd';
-import { useDetailsPanel } from 'components/DetailsPanel';
-import WarningPopover from 'components/WarningPopover/WarningPopover';
-import { LOCALSTORAGE } from 'constants/localStorage';
-import useGetTraceV4 from 'hooks/trace/useGetTraceV4';
-import { useTraceDetailsStripInfo } from './useTraceDetailsStripInfo';
-import { useSafeNavigate } from 'hooks/useSafeNavigate';
-import useUrlQuery from 'hooks/useUrlQuery';
-import { ResizableBox } from 'periscope/components/ResizableBox';
-import { SpanV3, TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
+import { useCallback, useRef, useState } from 'react';
 
-import { TraceDetailEventKeys, TraceDetailEvents } from './events';
-import { useTraceDetailLogEvent } from './hooks/useTraceDetailLogEvent';
-import NoData from './NoData/NoData';
-import TraceStoreSync from './stores/TraceStoreSync';
-import { useTraceStore } from './stores/traceStore';
-import {
-	SPAN_DETAILS_PANEL_MIN_WIDTH,
-	SpanDetailVariant,
-} from './SpanDetailsPanel/constants';
-import SpanDetailsPanel from './SpanDetailsPanel/SpanDetailsPanel';
+import { TraceDetailsTab } from './constants';
+import { useTraceDetailsTab } from './hooks/useTraceDetailsTab';
 import TraceDetailsHeader from './TraceDetailsHeader/TraceDetailsHeader';
-import { FLAMEGRAPH_SPAN_LIMIT } from './TraceFlamegraph/constants';
-import TraceFlamegraph from './TraceFlamegraph/TraceFlamegraph';
-import TraceWaterfall from './TraceWaterfall/TraceWaterfall';
-import { IInterestedSpan } from './TraceWaterfall/types';
-import { getAncestorSpanIds } from './TraceWaterfall/utils';
-import { getAvailableColorByFieldNames } from './utils';
-
-import cx from 'classnames';
-
-import styles from './TraceDetailsV3.module.scss';
-
-// Lucide chevrons for the flame/waterfall accordion headers, matching the
-// span-tree chevrons in the waterfall.
-function renderPanelExpandIcon({
-	isActive,
-}: {
-	isActive?: boolean;
-}): JSX.Element {
-	return isActive ? <ChevronDown size={14} /> : <ChevronRight size={14} />;
-}
+import TraceDetailsOverview from './TraceDetailsOverview/TraceDetailsOverview';
+import TraceDetailsThread from './TraceDetailsThread/TraceDetailsThread';
+import TraceDetailsWrapper from './TraceDetailsWrapper/TraceDetailsWrapper';
 
 function TraceDetailsV3(): JSX.Element {
-	const { id: traceId } = useParams<TraceDetailV3URLProps>();
-	const urlQuery = useUrlQuery();
-	const [interestedSpanId, setInterestedSpanId] = useState<IInterestedSpan>(
-		() => ({
-			spanId: urlQuery.get('spanId') || '',
-			isUncollapsed: urlQuery.get('spanId') !== '',
-		}),
-	);
-	const [uncollapsedNodes, setUncollapsedNodes] = useState<string[]>([]);
-	const [localUncollapsedNodes, setLocalUncollapsedNodes] = useState<
-		Set<string>
-	>(new Set());
-	const [selectedSpan, setSelectedSpan] = useState<SpanV3>();
+	const [tab] = useTraceDetailsTab();
+	const isOverview = tab === TraceDetailsTab.Overview;
 	const [filteredSpanIds, setFilteredSpanIds] = useState<string[]>([]);
 	const [isFilterActive, setIsFilterActive] = useState(false);
-
-	const selectedSpanId = urlQuery.get('spanId') || undefined;
-	const { safeNavigate } = useSafeNavigate();
-
-	const logTraceEvent = useTraceDetailLogEvent('v3', traceId || '');
+	const [hasTraceData, setHasTraceData] = useState(false);
 	// Tracks which traceId the load event already fired for, so navigating
 	// between traces (the route component stays mounted) re-fires it once each.
-	const dataLoadedFiredForRef = useRef('');
-	const colorByField = useTraceStore((s) => s.colorByField);
-	const previewFieldsCount = useTraceStore((s) => s.previewFields.length);
-	const userPrefsReady = useTraceStore((s) => s.userPreferences !== null);
-
-	const handleSpanDetailsClose = useCallback((): void => {
-		urlQuery.delete('spanId');
-		safeNavigate({ search: urlQuery.toString() }, { replace: true });
-	}, [urlQuery, safeNavigate]);
+	const dataLoadedFiredForRef = useRef<string>('');
 
 	const handleFilteredSpansChange = useCallback(
 		(spanIds: string[], isActive: boolean): void => {
@@ -94,421 +25,23 @@ function TraceDetailsV3(): JSX.Element {
 		[],
 	);
 
-	const panelState = useDetailsPanel({
-		entityId: selectedSpanId,
-		onClose: handleSpanDetailsClose,
-	});
-
-	const allSpansRef = useRef<SpanV3[]>([]);
-	const deepLinkResolvedRef = useRef(false);
-
-	// Refetch only when the URL target isn't already loaded. Keeps row clicks
-	// and other in-window URL navigation from triggering a backend window slide.
-	useEffect(() => {
-		const spanId = urlQuery.get('spanId') || '';
-		if (!spanId) {
-			return;
-		}
-		const idx = allSpansRef.current.findIndex((s) => s.span_id === spanId);
-		if (idx !== -1) {
-			setSelectedSpan(allSpansRef.current[idx]);
-			return;
-		}
-		setInterestedSpanId({ spanId, isUncollapsed: true });
-	}, [urlQuery]);
-
-	// Once all spans are loaded (frontend mode), freeze query params so
-	// subsequent interestedSpanId changes don't trigger unnecessary refetches.
-	const fullDataLoadedRef = useRef(false);
-	const frozenParamsRef = useRef({
-		selectedSpanId: interestedSpanId.spanId,
-		isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
-		uncollapsedSpans: uncollapsedNodes,
-	});
-
-	const queryParams = fullDataLoadedRef.current
-		? frozenParamsRef.current
-		: {
-				selectedSpanId: interestedSpanId.spanId,
-				isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
-				uncollapsedSpans: uncollapsedNodes,
-			};
-
-	const {
-		data: traceData,
-		isFetching: isFetchingTraceData,
-		error: errorFetchingTraceData,
-	} = useGetTraceV4({
-		traceId,
-		uncollapsedSpans: queryParams.uncollapsedSpans,
-		selectedSpanId: queryParams.selectedSpanId,
-		isSelectedSpanIDUnCollapsed: queryParams.isSelectedSpanIDUnCollapsed,
-	});
-
-	const allSpans = traceData?.payload?.spans || [];
-	const totalSpansCount = traceData?.payload?.totalSpansCount || 0;
-	const totalErrorSpansCount = traceData?.payload?.totalErrorSpansCount || 0;
-
-	useTraceDetailsStripInfo({ totalSpansCount, totalErrorSpansCount });
-
-	const isFullDataLoaded =
-		totalSpansCount > 0 && totalSpansCount <= allSpans.length;
-
-	// Color-by options, gated on fields in loaded spans. Resource attrs are
-	// trace-wide, so any window has the full set — no need to accumulate.
-	const availableColorByFields = useMemo(() => {
-		const spans = traceData?.payload?.spans;
-		return spans?.length ? getAvailableColorByFieldNames(spans) : undefined;
-	}, [traceData?.payload?.spans]);
-
-	// Lock the ref once we confirm all data is loaded
-	if (isFullDataLoaded && !fullDataLoadedRef.current) {
-		fullDataLoadedRef.current = true;
-		frozenParamsRef.current = {
-			selectedSpanId: interestedSpanId.spanId,
-			isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
-			uncollapsedSpans: uncollapsedNodes,
-		};
-	}
-
-	useEffect(() => {
-		allSpansRef.current = allSpans;
-	}, [allSpans]);
-
-	useEffect(() => {
-		if (
-			!traceId ||
-			dataLoadedFiredForRef.current === traceId ||
-			!userPrefsReady
-		) {
-			return;
-		}
-		const payload = traceData?.payload;
-		if (!payload?.spans?.length) {
-			return;
-		}
-		dataLoadedFiredForRef.current = traceId;
-		const numServices = new Set(payload.spans.map((s) => s['service.name'])).size;
-		logTraceEvent(TraceDetailEvents.DataLoaded, {
-			[TraceDetailEventKeys.TotalSpansCount]: totalSpansCount,
-			[TraceDetailEventKeys.NumServices]: numServices,
-			[TraceDetailEventKeys.TraceDurationMs]:
-				payload.endTimestampMillis - payload.startTimestampMillis,
-			[TraceDetailEventKeys.HadErrors]: (payload.totalErrorSpansCount || 0) > 0,
-			[TraceDetailEventKeys.FlamegraphSampled]:
-				totalSpansCount > FLAMEGRAPH_SPAN_LIMIT,
-			[TraceDetailEventKeys.SpanPanelVariant]:
-				getLocalStorageKey(LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION) ||
-				SpanDetailVariant.DOCKED_RIGHT,
-			[TraceDetailEventKeys.ColorByField]: colorByField.name,
-			[TraceDetailEventKeys.PreviewFieldsCount]: previewFieldsCount,
-		});
-	}, [
-		traceId,
-		userPrefsReady,
-		traceData,
-		totalSpansCount,
-		colorByField,
-		previewFieldsCount,
-		logTraceEvent,
-	]);
-
-	// Frontend mode: expand all parents by default when full data arrives
-	useEffect(() => {
-		if (isFullDataLoaded && allSpans.length > 0) {
-			const parentIds = new Set(
-				allSpans.filter((s) => s.has_children).map((s) => s.span_id),
-			);
-			setLocalUncollapsedNodes(parentIds);
-		}
-	}, [isFullDataLoaded, allSpans]);
-
-	// Backend mode: sync uncollapsed state from API response
-	useEffect(() => {
-		if (
-			!isFullDataLoaded &&
-			traceData &&
-			traceData.payload &&
-			traceData.payload.uncollapsedSpans
-		) {
-			setUncollapsedNodes(traceData.payload.uncollapsedSpans);
-		}
-	}, [traceData, isFullDataLoaded]);
-
-	// Tracks whether we've already done the initial URL→selectedSpan handoff
-	//Lets `interestedSpanId` stay purely as the refetch trigger in frontend mode.
-	useEffect(() => {
-		if (deepLinkResolvedRef.current) {
-			return;
-		}
-		if (allSpans.length === 0) {
-			return;
-		}
-		if (selectedSpanId) {
-			const span = allSpans.find((s) => s.span_id === selectedSpanId);
-			if (!span) {
-				// Span not in the current window — wait for more data (backend
-				// pagination) before marking resolved.
-				return;
-			}
-			setSelectedSpan(span);
-		} else {
-			setSelectedSpan((prev) => prev ?? allSpans[0]);
-		}
-		deepLinkResolvedRef.current = true;
-	}, [selectedSpanId, allSpans]);
-
-	// Frontend mode: auto-expand ancestors of the URL-targeted span so it's
-	// visible. Keyed on URL `spanId`(selectedSpanId).
-	useEffect(() => {
-		if (!isFullDataLoaded || !selectedSpanId || allSpans.length === 0) {
-			return;
-		}
-		const ancestors = getAncestorSpanIds(allSpans, selectedSpanId);
-		if (ancestors.size === 0) {
-			return;
-		}
-		setLocalUncollapsedNodes((prev) => {
-			// Check if all ancestors are already expanded — avoid unnecessary state update
-			let allPresent = true;
-			for (const id of ancestors) {
-				if (!prev.has(id)) {
-					allPresent = false;
-					break;
-				}
-			}
-			if (allPresent) {
-				return prev;
-			}
-
-			const next = new Set(prev);
-			for (const id of ancestors) {
-				next.add(id);
-			}
-			return next;
-		});
-	}, [isFullDataLoaded, selectedSpanId, allSpans]);
-
-	const [activeKeys, setActiveKeys] = useState<string[]>(['flame', 'waterfall']);
-
-	const handleCollapseChange = (key: string): void => {
-		logTraceEvent(
-			key === 'flame'
-				? TraceDetailEvents.FlameGraphToggled
-				: TraceDetailEvents.WaterfallToggled,
-			{ [TraceDetailEventKeys.Expanded]: !activeKeys.includes(key) },
-		);
-		setActiveKeys((prev) =>
-			prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key],
-		);
-	};
-
-	const [spanDetailVariant, setSpanDetailVariant] = useState<SpanDetailVariant>(
-		() =>
-			(getLocalStorageKey(
-				LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION,
-			) as SpanDetailVariant) || SpanDetailVariant.DOCKED_RIGHT,
-	);
-
-	const RIGHT_DOCK_MIN = SPAN_DETAILS_PANEL_MIN_WIDTH;
-	const RIGHT_DOCK_MAX = 720;
-	const [rightDockWidth, setRightDockWidth] = useState(RIGHT_DOCK_MIN);
-
-	const handleVariantChange = useCallback(
-		(newVariant: SpanDetailVariant): void => {
-			setLocalStorageKey(
-				LOCALSTORAGE.TRACE_DETAILS_SPAN_DETAILS_POSITION,
-				newVariant,
-			);
-			setSpanDetailVariant(newVariant);
-		},
-		[],
-	);
-
-	const showNoData =
-		!isFetchingTraceData &&
-		(!!errorFetchingTraceData || !traceData?.payload?.spans?.length);
-
-	const isDocked = spanDetailVariant === SpanDetailVariant.DOCKED;
-	const isRightDocked = spanDetailVariant === SpanDetailVariant.DOCKED_RIGHT;
-	const isWaterfallDocked = panelState.isOpen && isDocked;
-	const showRightDock = panelState.isOpen && isRightDocked;
-
-	const waterfallChildren = (
-		<ResizableBox
-			defaultHeight={300}
-			minHeight={150}
-			disabled={!isWaterfallDocked}
-		>
-			<TraceWaterfall
-				traceData={traceData}
-				isFetchingTraceData={isFetchingTraceData}
-				errorFetchingTraceData={errorFetchingTraceData}
-				traceId={traceId || ''}
-				interestedSpanId={interestedSpanId}
-				setInterestedSpanId={setInterestedSpanId}
-				uncollapsedNodes={uncollapsedNodes}
-				isFullDataLoaded={isFullDataLoaded}
-				localUncollapsedNodes={localUncollapsedNodes}
-				setLocalUncollapsedNodes={setLocalUncollapsedNodes}
-				selectedSpan={selectedSpan}
-				setSelectedSpan={setSelectedSpan}
-				filteredSpanIds={filteredSpanIds}
-				isFilterActive={isFilterActive}
-			/>
-		</ResizableBox>
-	);
-
 	return (
-		<TraceStoreSync availableColorByFields={availableColorByFields}>
-			<div className={styles.root}>
-				<TraceDetailsHeader
-					onFilteredSpansChange={handleFilteredSpansChange}
-					showTraceDetailsHeaderOptions={
-						!!traceData?.payload?.spans?.length && !showNoData
-					}
+		<TraceDetailsWrapper>
+			<TraceDetailsHeader
+				onFilteredSpansChange={handleFilteredSpansChange}
+				showTraceDetailsHeaderOptions={hasTraceData}
+			/>
+			{isOverview ? (
+				<TraceDetailsOverview
+					filteredSpanIds={filteredSpanIds}
+					isFilterActive={isFilterActive}
+					onHasTraceDataChange={setHasTraceData}
+					dataLoadedFiredForRef={dataLoadedFiredForRef}
 				/>
-
-				{showNoData ? (
-					<NoData />
-				) : (
-					<>
-						<div className={styles.layoutRow}>
-							<div className={styles.content}>
-								<Collapse
-									// @ts-expect-error motion is passed through to rc-collapse to disable animation
-									motion={false}
-									activeKey={activeKeys.filter((k) => k === 'flame')}
-									onChange={(): void => handleCollapseChange('flame')}
-									size="small"
-									expandIcon={renderPanelExpandIcon}
-									className={styles.flameCollapse}
-									items={[
-										{
-											key: 'flame',
-											label: (
-												<div className={styles.collapseLabel}>
-													<span className={styles.collapseTitle}>
-														Flame Graph
-														{traceData?.payload?.totalSpansCount &&
-															traceData.payload.totalSpansCount > FLAMEGRAPH_SPAN_LIMIT && (
-																<WarningPopover
-																	message="The total span count exceeds the visualization limit. Displaying a sampled subset of spans in flamegraph."
-																	placement="bottomLeft"
-																>
-																	<Info
-																		size={16}
-																		color="var(--l2-foreground)"
-																		style={{ cursor: 'pointer' }}
-																	/>
-																</WarningPopover>
-															)}
-													</span>
-													{traceData?.payload?.totalSpansCount ? (
-														<span className={styles.collapseCount}>
-															<span className={styles.collapseCountItem}>
-																<ChartNoAxesGantt size={13} />
-																Spans: {traceData.payload.totalSpansCount}
-															</span>
-															<span
-																className={cx(styles.collapseCountItem, {
-																	[styles.hasErrors]: traceData.payload.totalErrorSpansCount > 0,
-																})}
-															>
-																<TriangleAlert size={13} />
-																Errors:{' '}
-																{traceData.payload.totalErrorSpansCount ?? (
-																	<span className="translate-safe">{0}</span>
-																)}
-															</span>
-														</span>
-													) : null}
-												</div>
-											),
-											children: (
-												<ResizableBox defaultHeight={300} minHeight={100} maxHeight={400}>
-													<TraceFlamegraph
-														filteredSpanIds={filteredSpanIds}
-														isFilterActive={isFilterActive}
-														selectedSpan={selectedSpan}
-														totalSpansCount={totalSpansCount}
-													/>
-												</ResizableBox>
-											),
-										},
-									]}
-								/>
-
-								<Collapse
-									// @ts-expect-error motion is passed through to rc-collapse to disable animation
-									motion={false}
-									activeKey={activeKeys.filter((k) => k === 'waterfall')}
-									onChange={(): void => handleCollapseChange('waterfall')}
-									size="small"
-									expandIcon={renderPanelExpandIcon}
-									className={cx(styles.waterfallCollapse, {
-										[styles.isDocked]: isWaterfallDocked,
-									})}
-									items={[
-										{
-											key: 'waterfall',
-											label: 'Waterfall',
-											children: activeKeys.includes('waterfall')
-												? waterfallChildren
-												: null,
-										},
-									]}
-								/>
-
-								{panelState.isOpen && isDocked && (
-									<div className={styles.dockedSpanDetails}>
-										<SpanDetailsPanel
-											panelState={panelState}
-											selectedSpan={selectedSpan}
-											variant={SpanDetailVariant.DOCKED}
-											onVariantChange={handleVariantChange}
-											traceStartTime={traceData?.payload?.startTimestampMillis}
-											traceEndTime={traceData?.payload?.endTimestampMillis}
-										/>
-									</div>
-								)}
-							</div>
-
-							{showRightDock && (
-								<ResizableBox
-									handle="left"
-									defaultWidth={rightDockWidth}
-									minWidth={RIGHT_DOCK_MIN}
-									maxWidth={RIGHT_DOCK_MAX}
-									onResize={setRightDockWidth}
-									className={styles.rightDock}
-								>
-									<SpanDetailsPanel
-										panelState={panelState}
-										selectedSpan={selectedSpan}
-										variant={SpanDetailVariant.DOCKED_RIGHT}
-										onVariantChange={handleVariantChange}
-										traceStartTime={traceData?.payload?.startTimestampMillis}
-										traceEndTime={traceData?.payload?.endTimestampMillis}
-									/>
-								</ResizableBox>
-							)}
-						</div>
-
-						{panelState.isOpen && spanDetailVariant === SpanDetailVariant.DIALOG && (
-							<SpanDetailsPanel
-								panelState={panelState}
-								selectedSpan={selectedSpan}
-								variant={SpanDetailVariant.DIALOG}
-								onVariantChange={handleVariantChange}
-								traceStartTime={traceData?.payload?.startTimestampMillis}
-								traceEndTime={traceData?.payload?.endTimestampMillis}
-							/>
-						)}
-					</>
-				)}
-			</div>
-		</TraceStoreSync>
+			) : (
+				<TraceDetailsThread />
+			)}
+		</TraceDetailsWrapper>
 	);
 }
 

frontend/src/pages/TraceDetailsV3/stores/TraceStoreSync.tsx

@@ -4,36 +4,28 @@ import updateUserPreferenceAPI from 'api/v1/user/preferences/name/update';
 import { useAppContext } from 'providers/App/App';
 
 import {
-	setTraceStoreAvailableColorByFields,
 	setTraceStoreCallbacks,
 	setTraceStoreUserPreferences,
 } from './traceStore';
 
 interface TraceStoreSyncProps {
-	availableColorByFields: string[] | undefined;
 	children: ReactNode;
 }
 
 /**
- * Bridges React-managed inputs (`availableColorByFields`, `userPreferences`
- * from AppContext, and the user-pref mutation hook) into the Zustand store.
+ * Bridges React-managed inputs (`userPreferences` from AppContext and the
+ * user-pref mutation hook) into the Zustand store. `availableColorByFields`
+ * is pushed by TraceDetailsOverview, which owns the span data.
  *
  * Renders nothing until `userPreferences` resolves so the flamegraph never
  * paints with the default colour first and then swaps to the user's
  * persisted choice. AppProvider fires the prefs query as soon as the user
  * is logged in, so this gate is usually already settled by mount time.
  */
-function TraceStoreSync({
-	availableColorByFields,
-	children,
-}: TraceStoreSyncProps): JSX.Element | null {
+function TraceStoreSync({ children }: TraceStoreSyncProps): JSX.Element | null {
 	const { userPreferences, updateUserPreferenceInContext } = useAppContext();
 	const { mutate: mutateUserPreference } = useMutation(updateUserPreferenceAPI);
 
-	useEffect(() => {
-		setTraceStoreAvailableColorByFields(availableColorByFields);
-	}, [availableColorByFields]);
-
 	useEffect(() => {
 		setTraceStoreUserPreferences(userPreferences ?? null);
 	}, [userPreferences]);

frontend/src/pages/TraceDetailsV3/stores/traceStore.ts

@@ -37,7 +37,7 @@ interface TraceStoreState {
 	availableColorByOptions: ColorByOption[];
 	previewFields: TelemetryFieldKey[];
 
-	// --- Setters used only by TraceStoreSync ---
+	// --- Setters used only by TraceStoreSync and TraceDetailsOverview ---
 	setAvailableColorByFields: (fieldNames: string[] | undefined) => void;
 	setUserPreferences: (userPreferences: UserPreference[] | null) => void;
 	setCallbacks: (callbacks: {

frontend/src/pages/TraceDetailsV3/utils/aiTraceUtils.ts

@@ -11,6 +11,8 @@ export const GEN_AI_KEYS = {
 	cacheCreationTokens: 'gen_ai.usage.cache_creation.input_tokens',
 	reasoningTokens: 'gen_ai.usage.reasoning.output_tokens',
 	cost: 'signoz.gen_ai.usage.tokens.cost',
+	inputMessages: 'gen_ai.input.messages',
+	outputMessages: 'gen_ai.output.messages',
 } as const;
 
 export enum AiSpanKind {

frontend/src/pages/TraceDetailsV3/utils/spanMessages.ts

@@ -0,0 +1,49 @@
+import { parseJsonObject } from '../AIThreadMessage/utils';
+import { ThreadMessage } from '../AIThreadMessage/types';
+import { ThreadSpan } from '../TraceDetailsThread/types';
+import { GEN_AI_KEYS } from './aiTraceUtils';
+
+/** Parsed JSON, or the original string when it isn't JSON. */
+export type RawMessagesValue = object | string;
+
+export interface SpanMessagesData {
+	formattedInput: ThreadMessage[];
+	formattedOutput: ThreadMessage[];
+	rawInput?: RawMessagesValue;
+	rawOutput?: RawMessagesValue;
+}
+
+function toRawValue(value: unknown): RawMessagesValue | undefined {
+	if (value === undefined || value === null || value === '') {
+		return undefined;
+	}
+	if (typeof value === 'string') {
+		return parseJsonObject(value) ?? value;
+	}
+	return typeof value === 'object' ? value : JSON.stringify(value);
+}
+
+export function getSpanMessages(span: ThreadSpan): SpanMessagesData {
+	const rawInput = toRawValue(span.attributes?.[GEN_AI_KEYS.inputMessages]);
+	const rawOutput = toRawValue(span.attributes?.[GEN_AI_KEYS.outputMessages]);
+
+	// Spans from before the JSON column have no formatted messages.
+	return {
+		formattedInput: span.formattedInput ?? [],
+		formattedOutput: span.formattedOutput ?? [],
+		rawInput,
+		rawOutput,
+	};
+}
+
+export function hasFormattedMessages(data: SpanMessagesData): boolean {
+	return data.formattedInput.length > 0 || data.formattedOutput.length > 0;
+}
+
+export function hasRawMessages(data: SpanMessagesData): boolean {
+	return !!data.rawInput || !!data.rawOutput;
+}
+
+export function hasAnyMessages(data: SpanMessagesData): boolean {
+	return hasFormattedMessages(data) || hasRawMessages(data);
+}

frontend/src/periscope/components/PrettyView/PrettyView.tsx

@@ -230,24 +230,26 @@ function PrettyView({
 					<span>{content}</span>
 					{/* The menu is portalled, but its clicks still bubble through the React
 					tree to react-json-tree's expand toggle around getItemString. */}
-					<span
-						role="presentation"
-						className="pretty-view__actions-boundary"
-						onClick={(e): void => {
-							e.stopPropagation();
-						}}
-					>
-						<Dropdown
-							items={menuItems}
-							nativeButton={false}
-							align="start"
-							side="bottom"
+					{menuItems.length > 0 && (
+						<span
+							role="presentation"
+							className="pretty-view__actions-boundary"
+							onClick={(e): void => {
+								e.stopPropagation();
+							}}
 						>
-							<span className="pretty-view__actions" role="button" tabIndex={0}>
-								<Ellipsis size={12} />
-							</span>
-						</Dropdown>
-					</span>
+							<Dropdown
+								items={menuItems}
+								nativeButton={false}
+								align="start"
+								side="bottom"
+							>
+								<span className="pretty-view__actions" role="button" tabIndex={0}>
+									<Ellipsis size={12} />
+								</span>
+							</Dropdown>
+						</span>
+					)}
 				</span>
 			);
 		},

go.mod

@@ -12,7 +12,6 @@ require (
 	github.com/SigNoz/signoz-otel-collector v0.144.6
 	github.com/antlr4-go/antlr/v4 v4.13.1
 	github.com/antonmedv/expr v1.15.3
-	github.com/bytedance/sonic v1.14.1
 	github.com/cespare/xxhash/v2 v2.3.0
 	github.com/coreos/go-oidc/v3 v3.17.0
 	github.com/dgraph-io/ristretto/v2 v2.3.0
@@ -112,6 +111,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.9 // indirect
 	github.com/aws/smithy-go v1.24.2 // indirect
 	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.14.1 // indirect
 	github.com/bytedance/sonic/loader v0.3.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
 	github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 // indirect

pkg/alertmanager/nfmanager/rulebasednotification/provider.go

@@ -8,7 +8,6 @@ import (
 	"github.com/SigNoz/signoz/pkg/alertmanager/nfmanager"
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/types/alertmanagertypes"
-	"github.com/expr-lang/expr"
 	"github.com/prometheus/common/model"
 
 	"github.com/SigNoz/signoz/pkg/factory"
@@ -219,8 +218,9 @@ func (r *provider) Match(ctx context.Context, orgID string, ruleID string, set m
 		return matchedChannels, nil
 	}
 
+	env := r.convertLabelSetToEnv(ctx, set)
 	for _, route := range expressionRoutes {
-		evaluateExpr, err := r.evaluateExpr(ctx, route.Expression, set)
+		evaluateExpr, err := alertmanagertypes.EvalExpression(route.Expression, env)
 		if err != nil {
 			//nolint:sloglint
 			r.settings.Logger().WarnContext(ctx, "failed to evaluate route policy expression", errors.Attr(err), slog.String("rule.id", ruleID))
@@ -243,23 +243,3 @@ func (r *provider) convertLabelSetToEnv(ctx context.Context, labelSet model.Labe
 	}
 	return env
 }
-
-func (r *provider) evaluateExpr(ctx context.Context, expression string, labelSet model.LabelSet) (bool, error) {
-	env := r.convertLabelSetToEnv(ctx, labelSet)
-
-	program, err := expr.Compile(expression, expr.Env(env), expr.AllowUndefinedVariables())
-	if err != nil {
-		return false, errors.NewInternalf(errors.CodeInternal, "error compiling route policy %s: %v", expression, err)
-	}
-
-	output, err := expr.Run(program, env)
-	if err != nil {
-		return false, errors.NewInternalf(errors.CodeInternal, "error running route policy %s: %v", expression, err)
-	}
-
-	if boolVal, ok := output.(bool); ok {
-		return boolVal, nil
-	}
-
-	return false, errors.NewInternalf(errors.CodeInternal, "error in evaluating route policy %s: %v", expression, err)
-}

pkg/alertmanager/nfmanager/rulebasednotification/provider_test.go

@@ -277,400 +277,6 @@ func TestProvider_ConcurrentAccess(t *testing.T) {
 	wg.Wait()
 }
 
-func TestProvider_EvaluateExpression(t *testing.T) {
-	provider := &provider{
-		settings: factory.NewScopedProviderSettings(createTestProviderSettings(), "provider_test"),
-	}
-
-	tests := []struct {
-		name       string
-		expression string
-		labelSet   model.LabelSet
-		expected   bool
-	}{
-		{
-			name:       "simple equality check - match",
-			expression: `threshold.name == 'auth' && ruleId == 'rule1'`,
-			labelSet: model.LabelSet{
-				"threshold.name": "auth",
-				"ruleId":         "rule1",
-			},
-			expected: true,
-		},
-		{
-			name:       "simple equality check - match",
-			expression: `threshold.name = 'auth' AND ruleId = 'rule1'`,
-			labelSet: model.LabelSet{
-				"threshold.name": "auth",
-				"ruleId":         "rule1",
-			},
-			expected: true,
-		},
-		{
-			name:       "simple equality check - no match",
-			expression: `service == "payment"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "simple equality check - no match",
-			expression: `service = "payment"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "multiple conditions with AND - both match",
-			expression: `service == "auth" && env == "production"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: true,
-		},
-		{
-			name:       "multiple conditions with AND - both match",
-			expression: `service = "auth" AND env = "production"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: true,
-		},
-		{
-			name:       "multiple conditions with AND - one doesn't match",
-			expression: `service == "auth" && env == "staging"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "multiple conditions with AND - one doesn't match",
-			expression: `service = "auth" AND env = "staging"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "multiple conditions with OR - one matches",
-			expression: `service == "payment" || env == "production"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: true,
-		},
-		{
-			name:       "multiple conditions with OR - one matches",
-			expression: `service = "payment" OR env = "production"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: true,
-		},
-		{
-			name:       "multiple conditions with OR - none match",
-			expression: `service == "payment" || env == "staging"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "multiple conditions with OR - none match",
-			expression: `service = "payment" OR env = "staging"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-				"env":     "production",
-			},
-			expected: false,
-		},
-		{
-			name:       "in operator - value in list",
-			expression: `service in ["auth", "payment", "notification"]`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: true,
-		},
-		{
-			name:       "in operator - value in list",
-			expression: `service IN ["auth", "payment", "notification"]`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: true,
-		},
-		{
-			name:       "in operator - value not in list",
-			expression: `service in ["payment", "notification"]`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: false,
-		},
-		{
-			name:       "in operator - value not in list",
-			expression: `service IN ["payment", "notification"]`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: false,
-		},
-		{
-			name:       "contains operator - substring match",
-			expression: `host contains "prod"`,
-			labelSet: model.LabelSet{
-				"host": "prod-server-01",
-			},
-			expected: true,
-		},
-		{
-			name:       "contains operator - substring match",
-			expression: `host CONTAINS "prod"`,
-			labelSet: model.LabelSet{
-				"host": "prod-server-01",
-			},
-			expected: true,
-		},
-		{
-			name:       "contains operator - no substring match",
-			expression: `host contains "staging"`,
-			labelSet: model.LabelSet{
-				"host": "prod-server-01",
-			},
-			expected: false,
-		},
-		{
-			name:       "contains operator - no substring match",
-			expression: `host CONTAINS "staging"`,
-			labelSet: model.LabelSet{
-				"host": "prod-server-01",
-			},
-			expected: false,
-		},
-		{
-			name:       "complex expression with parentheses",
-			expression: `(service == "auth" && env == "production") || critical == "true"`,
-			labelSet: model.LabelSet{
-				"service":  "payment",
-				"env":      "staging",
-				"critical": "true",
-			},
-			expected: true,
-		},
-		{
-			name:       "complex expression with parentheses",
-			expression: `(service = "auth" AND env = "production") OR critical = "true"`,
-			labelSet: model.LabelSet{
-				"service":  "payment",
-				"env":      "staging",
-				"critical": "true",
-			},
-			expected: true,
-		},
-		{
-			name:       "missing label key",
-			expression: `"missing_key" == "value"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: false,
-		},
-		{
-			name:       "missing label key",
-			expression: `"missing_key" = "value"`,
-			labelSet: model.LabelSet{
-				"service": "auth",
-			},
-			expected: false,
-		},
-		{
-			name:       "rule-based expression with threshold name and ruleId",
-			expression: `'threshold.name' == "high-cpu" && ruleId == "rule-123"`,
-			labelSet: model.LabelSet{
-				"threshold.name": "high-cpu",
-				"ruleId":         "rule-123",
-				"service":        "auth",
-			},
-			expected: false, //no commas
-		},
-		{
-			name:       "rule-based expression with threshold name and ruleId",
-			expression: `'threshold.name' = "high-cpu" AND ruleId == "rule-123"`,
-			labelSet: model.LabelSet{
-				"threshold.name": "high-cpu",
-				"ruleId":         "rule-123",
-				"service":        "auth",
-			},
-			expected: false, //no commas
-		},
-		{
-			name:       "alertname and ruleId combination",
-			expression: `alertname == "HighCPUUsage" && ruleId == "cpu-alert-001"`,
-			labelSet: model.LabelSet{
-				"alertname": "HighCPUUsage",
-				"ruleId":    "cpu-alert-001",
-				"severity":  "critical",
-			},
-			expected: true,
-		},
-		{
-			name:       "alertname and ruleId combination",
-			expression: `alertname = "HighCPUUsage" AND ruleId = "cpu-alert-001"`,
-			labelSet: model.LabelSet{
-				"alertname": "HighCPUUsage",
-				"ruleId":    "cpu-alert-001",
-				"severity":  "critical",
-			},
-			expected: true,
-		},
-		{
-			name:       "kubernetes namespace filtering",
-			expression: `k8s.namespace.name == "auth" && service in ["auth", "payment"]`,
-			labelSet: model.LabelSet{
-				"k8s.namespace.name": "auth",
-				"service":            "auth",
-				"host":               "k8s-node-1",
-			},
-			expected: true,
-		},
-		{
-			name:       "kubernetes namespace filtering",
-			expression: `k8s.namespace.name = "auth" && service IN ["auth", "payment"]`,
-			labelSet: model.LabelSet{
-				"k8s.namespace.name": "auth",
-				"service":            "auth",
-				"host":               "k8s-node-1",
-			},
-			expected: true,
-		},
-		{
-			name:       "migration expression format from SQL migration",
-			expression: `threshold.name == "HighCPUUsage" && ruleId == "rule-uuid-123"`,
-			labelSet: model.LabelSet{
-				"threshold.name": "HighCPUUsage",
-				"ruleId":         "rule-uuid-123",
-				"severity":       "warning",
-			},
-			expected: true,
-		},
-		{
-			name:       "migration expression format from SQL migration",
-			expression: `threshold.name = "HighCPUUsage" && ruleId = "rule-uuid-123"`,
-			labelSet: model.LabelSet{
-				"threshold.name": "HighCPUUsage",
-				"ruleId":         "rule-uuid-123",
-				"severity":       "warning",
-			},
-			expected: true,
-		},
-		{
-			name:       "case sensitive matching",
-			expression: `service == "Auth"`, // capital A
-			labelSet: model.LabelSet{
-				"service": "auth", // lowercase a
-			},
-			expected: false,
-		},
-		{
-			name:       "case sensitive matching",
-			expression: `service = "Auth"`, // capital A
-			labelSet: model.LabelSet{
-				"service": "auth", // lowercase a
-			},
-			expected: false,
-		},
-		{
-			name:       "numeric comparison as strings",
-			expression: `port == "8080"`,
-			labelSet: model.LabelSet{
-				"port": "8080",
-			},
-			expected: true,
-		},
-		{
-			name:       "numeric comparison as strings",
-			expression: `port = "8080"`,
-			labelSet: model.LabelSet{
-				"port": "8080",
-			},
-			expected: true,
-		},
-		{
-			name:       "quoted string with special characters",
-			expression: `service == "auth-service-v2"`,
-			labelSet: model.LabelSet{
-				"service": "auth-service-v2",
-			},
-			expected: true,
-		},
-		{
-			name:       "quoted string with special characters",
-			expression: `service = "auth-service-v2"`,
-			labelSet: model.LabelSet{
-				"service": "auth-service-v2",
-			},
-			expected: true,
-		},
-		{
-			name:       "boolean operators precedence",
-			expression: `service == "auth" && env == "prod" || critical == "true"`,
-			labelSet: model.LabelSet{
-				"service":  "payment",
-				"env":      "staging",
-				"critical": "true",
-			},
-			expected: true,
-		},
-		{
-			name:       "boolean operators precedence",
-			expression: `service = "auth" AND env = "prod" OR critical = "true"`,
-			labelSet: model.LabelSet{
-				"service":  "payment",
-				"env":      "staging",
-				"critical": "true",
-			},
-			expected: true,
-		},
-		{
-			name:       "nonexistent key OR check",
-			expression: `threshold.name = 'warning' OR ruleId = 'rule1'`,
-			labelSet: model.LabelSet{
-				"threshold.name": "warning",
-			},
-			expected: true,
-		},
-		{
-			name:       "nonexistent key && check",
-			expression: `threshold.name = 'warning' && nonexistent = 'auth'`,
-			labelSet: model.LabelSet{
-				"threshold.name": "warning",
-			},
-			expected: false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := provider.evaluateExpr(context.Background(), tt.expression, tt.labelSet)
-			assert.NoError(t, err)
-			assert.Equal(t, tt.expected, result, "Expression: %s", tt.expression)
-		})
-	}
-}
-
 func TestProvider_DeleteRoute(t *testing.T) {
 	ctx := context.Background()
 	providerSettings := createTestProviderSettings()

pkg/contextlinks/links.go

@@ -3,10 +3,13 @@ package contextlinks
 import (
 	"encoding/json"
 	"net/url"
+	"slices"
 	"strconv"
+	"strings"
 	"time"
 
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/ruletypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 )
 
@@ -52,40 +55,66 @@ func prepareExplorerParams(dataSource string, queryType qbtypes.QueryType, start
 	return params
 }
 
-// BuilderQueryForSignal returns the filter expression and group-by keys of the
-// builder query for the given signal, or found=false when the composite query
-// has no builder query for it (e.g. PromQL or ClickHouse SQL alerts). AI trace
-// queries (builder_ai_query) count as trace builder queries.
-// TODO(srikanthccv): re-visit this and support multiple queries.
-func BuilderQueryForSignal(queries []qbtypes.QueryEnvelope, signal telemetrytypes.Signal) (string, []qbtypes.GroupByKey, bool) {
-	switch signal {
-	case telemetrytypes.SignalLogs:
-		return builderQueryForSignal[qbtypes.LogAggregation](queries, signal)
-	case telemetrytypes.SignalTraces:
-		return builderQueryForSignal[qbtypes.TraceAggregation](queries, signal)
+func PrepareRuleFilterExpression(condition *ruletypes.RuleCondition, signal telemetrytypes.Signal, labels map[string]string) (string, bool, error) {
+	var expressions []string
+	if condition != nil && condition.CompositeQuery != nil {
+		names, err := resolveSelectedQueryNames(condition)
+		if err != nil {
+			return "", false, err
+		}
+		switch signal {
+		case telemetrytypes.SignalLogs:
+			expressions = prepareFilterExpressions[qbtypes.LogAggregation](condition.CompositeQuery.Queries, names, signal, labels)
+		case telemetrytypes.SignalTraces:
+			expressions = prepareFilterExpressions[qbtypes.TraceAggregation](condition.CompositeQuery.Queries, names, signal, labels)
+		}
 	}
-	return "", nil, false
+
+	switch {
+	case len(expressions) == 0:
+		// a ClickHouse SQL alert has no builder query; its link filters on the labels alone
+		return PrepareFilterExpression(labels, "", nil), false, nil
+	case len(expressions) == 1:
+		return expressions[0], true, nil
+	case slices.Contains(expressions, ""):
+		// an unfiltered formula input matches everything, so the merged filter does too
+		return "", true, nil
+	}
+	// the explorer list views render one query only, so a formula's inputs merge into one filter
+	return "(" + strings.Join(expressions, ") OR (") + ")", true, nil
 }
 
-func builderQueryForSignal[T any](queries []qbtypes.QueryEnvelope, signal telemetrytypes.Signal) (string, []qbtypes.GroupByKey, bool) {
-	var q qbtypes.QueryBuilderQuery[T]
-	found := false
+func resolveSelectedQueryNames(condition *ruletypes.RuleCondition) ([]string, error) {
+	selected := condition.SelectedQueryName()
+	for _, query := range condition.CompositeQuery.Queries {
+		if query.GetQueryName() != selected {
+			continue
+		}
+		if formula, ok := query.Spec.(qbtypes.QueryBuilderFormula); ok {
+			return formula.ExtractReferencedQueryNames()
+		}
+		return []string{selected}, nil
+	}
+	return nil, nil
+}
+
+func prepareFilterExpressions[T any](queries []qbtypes.QueryEnvelope, names []string, signal telemetrytypes.Signal, labels map[string]string) []string {
+	var expressions []string
 	for _, query := range queries {
 		if query.Type != qbtypes.QueryTypeBuilder && query.Type != qbtypes.QueryTypeBuilderAI {
 			continue
 		}
-		if spec, ok := query.Spec.(qbtypes.QueryBuilderQuery[T]); ok {
-			q = spec
-			found = true
+		spec, ok := query.Spec.(qbtypes.QueryBuilderQuery[T])
+		// spec.Disabled is deliberately not checked: a formula's inputs are
+		// usually hidden in the UI but must still make it into the link
+		if !ok || spec.Signal != signal || !slices.Contains(names, spec.Name) {
+			continue
 		}
+		filterExpr := ""
+		if spec.Filter != nil {
+			filterExpr = spec.Filter.Expression
+		}
+		expressions = append(expressions, PrepareFilterExpression(labels, filterExpr, spec.GroupBy))
 	}
-	if !found || q.Signal != signal {
-		return "", nil, false
-	}
-
-	filterExpr := ""
-	if q.Filter != nil {
-		filterExpr = q.Filter.Expression
-	}
-	return filterExpr, q.GroupBy, true
+	return expressions
 }

pkg/contextlinks/links_test.go

@@ -4,12 +4,13 @@ import (
 	"testing"
 
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/ruletypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestBuilderQueryForSignal(t *testing.T) {
+func TestPrepareRuleFilterExpression(t *testing.T) {
 	logQuery := qbtypes.QueryEnvelope{
 		Type: qbtypes.QueryTypeBuilder,
 		Spec: qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
@@ -19,62 +20,205 @@ func TestBuilderQueryForSignal(t *testing.T) {
 			GroupBy: []qbtypes.GroupByKey{{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "service.name"}}},
 		},
 	}
+	hiddenLogQuery := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeBuilder,
+		Spec: qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+			Name:     "B",
+			Signal:   telemetrytypes.SignalLogs,
+			Disabled: true,
+			Filter:   &qbtypes.Filter{Expression: "body CONTAINS 'timeout'"},
+		},
+	}
+	unfilteredLogQuery := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeBuilder,
+		Spec: qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+			Name:   "C",
+			Signal: telemetrytypes.SignalLogs,
+		},
+	}
 	traceQuery := qbtypes.QueryEnvelope{
 		Type: qbtypes.QueryTypeBuilder,
 		Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
-			Name:   "B",
+			Name:   "D",
 			Signal: telemetrytypes.SignalTraces,
 		},
 	}
 	promQuery := qbtypes.QueryEnvelope{
 		Type: qbtypes.QueryTypePromQL,
-		Spec: qbtypes.PromQuery{Name: "C"},
+		Spec: qbtypes.PromQuery{Name: "E"},
 	}
 	aiTraceQuery := qbtypes.QueryEnvelope{
 		Type: qbtypes.QueryTypeBuilderAI,
 		Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
-			Name:    "D",
+			Name:    "F",
 			Signal:  telemetrytypes.SignalTraces,
 			Filter:  &qbtypes.Filter{Expression: "trace.input_tokens > 1000"},
 			GroupBy: []qbtypes.GroupByKey{{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "session.id"}}},
 		},
 	}
+	errorRateFormula := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeFormula,
+		Spec: qbtypes.QueryBuilderFormula{Name: "F1", Expression: "B / A * 100"},
+	}
+	unfilteredFormula := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeFormula,
+		Spec: qbtypes.QueryBuilderFormula{Name: "F2", Expression: "A / C"},
+	}
+	brokenFormula := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeFormula,
+		Spec: qbtypes.QueryBuilderFormula{Name: "F3", Expression: "A +"},
+	}
 
-	t.Run("logs query among mixed queries", func(t *testing.T) {
-		filterExpr, groupBy, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{promQuery, logQuery, traceQuery}, telemetrytypes.SignalLogs)
-		require.True(t, found)
-		assert.Equal(t, "severity_text = 'ERROR'", filterExpr)
-		require.Len(t, groupBy, 1)
-		assert.Equal(t, "service.name", groupBy[0].Name)
-	})
+	testCases := []struct {
+		name               string
+		condition          *ruletypes.RuleCondition
+		signal             telemetrytypes.Signal
+		labels             map[string]string
+		expectedError      bool
+		expectedExpression string
+		expectedFound      bool
+	}{
+		{
+			name: "SelectedLogsQuery_AmongMixedQueries",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "A",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{promQuery, logQuery, traceQuery}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "(severity_text='ERROR') AND service.name='checkout'",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedLogsQuery_LeavesOutUnselectedQuery",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "A",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, hiddenLogQuery}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "(severity_text='ERROR') AND service.name='checkout'",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedFormula_MergesHiddenInputsInCompositeQueryOrder",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "F1",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{hiddenLogQuery, logQuery, errorRateFormula}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "((body CONTAINS 'timeout') AND service.name='checkout') OR ((severity_text='ERROR') AND service.name='checkout')",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedFormula_UnfilteredInputMatchesEverything",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "F2",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, unfilteredLogQuery, unfilteredFormula}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{},
+			expectedExpression: "",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedFormula_InvalidExpression",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "F3",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, brokenFormula}},
+			},
+			signal:        telemetrytypes.SignalLogs,
+			labels:        map[string]string{},
+			expectedError: true,
+		},
+		{
+			name: "NoSelectedQuery_FallsBackToFormula",
+			condition: &ruletypes.RuleCondition{
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, hiddenLogQuery, errorRateFormula}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "((severity_text='ERROR') AND service.name='checkout') OR ((body CONTAINS 'timeout') AND service.name='checkout')",
+			expectedFound:      true,
+		},
+		{
+			name: "NoSelectedQuery_OnlyHiddenQueries",
+			condition: &ruletypes.RuleCondition{
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{hiddenLogQuery}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{},
+			expectedExpression: "",
+			expectedFound:      false,
+		},
+		{
+			name: "SelectedTracesQuery_WithoutFilter",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "D",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, traceQuery}},
+			},
+			signal:             telemetrytypes.SignalTraces,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "service.name='checkout'",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedAITraceQuery_CountsAsTraces",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "F",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, aiTraceQuery}},
+			},
+			signal:             telemetrytypes.SignalTraces,
+			labels:             map[string]string{"session.id": "s1"},
+			expectedExpression: "(trace.input_tokens>1000) AND session.id='s1'",
+			expectedFound:      true,
+		},
+		{
+			name: "SelectedQuery_OfAnotherSignal_LabelsOnly",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "D",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery, traceQuery}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "service.name='checkout'",
+			expectedFound:      false,
+		},
+		{
+			name: "SelectedQuery_NotABuilderQuery",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "E",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{promQuery}},
+			},
+			signal:             telemetrytypes.SignalLogs,
+			labels:             map[string]string{},
+			expectedExpression: "",
+			expectedFound:      false,
+		},
+		{
+			name: "UnsupportedSignal_LabelsOnly",
+			condition: &ruletypes.RuleCondition{
+				SelectedQuery:  "A",
+				CompositeQuery: &ruletypes.AlertCompositeQuery{Queries: []qbtypes.QueryEnvelope{logQuery}},
+			},
+			signal:             telemetrytypes.SignalMetrics,
+			labels:             map[string]string{"service.name": "checkout"},
+			expectedExpression: "service.name='checkout'",
+			expectedFound:      false,
+		},
+	}
 
-	t.Run("traces query without filter", func(t *testing.T) {
-		filterExpr, groupBy, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{logQuery, traceQuery}, telemetrytypes.SignalTraces)
-		require.True(t, found)
-		assert.Empty(t, filterExpr)
-		assert.Empty(t, groupBy)
-	})
-
-	t.Run("ai trace query counts as traces", func(t *testing.T) {
-		filterExpr, groupBy, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{logQuery, aiTraceQuery}, telemetrytypes.SignalTraces)
-		require.True(t, found)
-		assert.Equal(t, "trace.input_tokens > 1000", filterExpr)
-		require.Len(t, groupBy, 1)
-		assert.Equal(t, "session.id", groupBy[0].Name)
-	})
-
-	t.Run("no builder query for signal", func(t *testing.T) {
-		_, _, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{traceQuery}, telemetrytypes.SignalLogs)
-		assert.False(t, found)
-	})
-
-	t.Run("no builder queries at all", func(t *testing.T) {
-		_, _, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{promQuery}, telemetrytypes.SignalLogs)
-		assert.False(t, found)
-	})
-
-	t.Run("unsupported signal", func(t *testing.T) {
-		_, _, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{logQuery}, telemetrytypes.SignalMetrics)
-		assert.False(t, found)
-	})
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			expression, found, err := PrepareRuleFilterExpression(testCase.condition, testCase.signal, testCase.labels)
+			if testCase.expectedError {
+				assert.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, testCase.expectedExpression, expression)
+			assert.Equal(t, testCase.expectedFound, found)
+		})
+	}
 }

pkg/modules/rulestatehistory/implrulestatehistory/links.go

@@ -3,9 +3,11 @@ package implrulestatehistory
 import (
 	"context"
 	"encoding/json"
+	"log/slog"
 	"time"
 
 	"github.com/SigNoz/signoz/pkg/contextlinks"
+	"github.com/SigNoz/signoz/pkg/errors"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/rulestatehistorytypes"
 	"github.com/SigNoz/signoz/pkg/types/ruletypes"
@@ -18,9 +20,10 @@ import (
 // explorer with the context that produced it.
 type relatedLinkBuilder struct {
 	alertType  ruletypes.AlertType
+	signal     telemetrytypes.Signal
 	evaluation ruletypes.Evaluation
-	filterExpr string
-	groupBy    []qbtypes.GroupByKey
+	condition  *ruletypes.RuleCondition
+	logger     *slog.Logger
 }
 
 // relatedLinkBuilderForRule returns nil when the rule cannot be loaded or is
@@ -49,7 +52,7 @@ func (m *module) relatedLinkBuilderForRule(ctx context.Context, orgID valuer.UUI
 		return nil
 	}
 
-	builder := &relatedLinkBuilder{alertType: rule.AlertType}
+	builder := &relatedLinkBuilder{alertType: rule.AlertType, signal: signal, condition: rule.RuleCondition, logger: m.logger.With(slog.String("rule.id", ruleID))}
 	if rule.Evaluation != nil {
 		if evaluation, err := rule.Evaluation.GetEvaluation(); err == nil {
 			builder.evaluation = evaluation
@@ -63,10 +66,6 @@ func (m *module) relatedLinkBuilderForRule(ctx context.Context, orgID valuer.UUI
 		builder.evaluation = ruletypes.RollingWindow{EvalWindow: evalWindow}
 	}
 
-	// links are still built from the labels alone when the rule has no builder
-	// query for the signal (e.g. ClickHouse SQL alerts)
-	builder.filterExpr, builder.groupBy, _ = contextlinks.BuilderQueryForSignal(rule.RuleCondition.CompositeQuery.Queries, signal)
-
 	return builder
 }
 
@@ -83,13 +82,19 @@ func (b *relatedLinkBuilder) queryWindow(unixMilli int64) (time.Time, time.Time)
 
 // links returns the explorer query params for the given entry labels and time
 // range.
-func (b *relatedLinkBuilder) links(labels rulestatehistorytypes.LabelsString, start, end time.Time) rulestatehistorytypes.RelatedLinks {
+func (b *relatedLinkBuilder) links(ctx context.Context, labels rulestatehistorytypes.LabelsString, start, end time.Time) rulestatehistorytypes.RelatedLinks {
 	lbls := map[string]string{}
 	if err := json.Unmarshal([]byte(labels), &lbls); err != nil {
 		return rulestatehistorytypes.RelatedLinks{}
 	}
 
-	whereClause := contextlinks.PrepareFilterExpression(lbls, b.filterExpr, b.groupBy)
+	// links are still built from the labels alone when the rule has no builder
+	// query for the signal (e.g. ClickHouse SQL alerts)
+	whereClause, _, err := contextlinks.PrepareRuleFilterExpression(b.condition, b.signal, lbls)
+	if err != nil {
+		b.logger.ErrorContext(ctx, "failed to prepare the filter for related links", errors.Attr(err))
+		return rulestatehistorytypes.RelatedLinks{}
+	}
 
 	switch b.alertType {
 	case ruletypes.AlertTypeLogs:

pkg/modules/rulestatehistory/implrulestatehistory/module.go

@@ -2,6 +2,7 @@ package implrulestatehistory
 
 import (
 	"context"
+	"log/slog"
 	"math"
 	"time"
 
@@ -15,10 +16,11 @@ import (
 type module struct {
 	store     rulestatehistorytypes.Store
 	ruleStore ruletypes.RuleStore
+	logger    *slog.Logger
 }
 
-func NewModule(store rulestatehistorytypes.Store, ruleStore ruletypes.RuleStore) rulestatehistory.Module {
-	return &module{store: store, ruleStore: ruleStore}
+func NewModule(store rulestatehistorytypes.Store, ruleStore ruletypes.RuleStore, logger *slog.Logger) rulestatehistory.Module {
+	return &module{store: store, ruleStore: ruleStore, logger: logger}
 }
 
 func (m *module) GetLastSavedRuleStateHistory(ctx context.Context, ruleID string) ([]rulestatehistorytypes.RuleStateHistory, error) {
@@ -34,7 +36,7 @@ func (m *module) GetHistoryTimeline(ctx context.Context, orgID valuer.UUID, rule
 	if builder := m.relatedLinkBuilderForRule(ctx, orgID, ruleID); builder != nil {
 		for idx := range items {
 			start, end := builder.queryWindow(items[idx].UnixMilli)
-			items[idx].RelatedLinks = builder.links(items[idx].Labels, start, end)
+			items[idx].RelatedLinks = builder.links(ctx, items[idx].Labels, start, end)
 		}
 	}
 
@@ -60,7 +62,7 @@ func (m *module) GetHistoryContributors(ctx context.Context, orgID valuer.UUID,
 		// span it too instead of a single evaluation window
 		start, end := time.UnixMilli(query.Start), time.UnixMilli(query.End)
 		for idx := range contributors {
-			contributors[idx].RelatedLinks = builder.links(contributors[idx].Labels, start, end)
+			contributors[idx].RelatedLinks = builder.links(ctx, contributors[idx].Labels, start, end)
 		}
 	}
 

pkg/querier/consume.go

@@ -40,11 +40,19 @@ func stripKeyAlias(name string) string {
 	return keyAliasRe.ReplaceAllString(name, "")
 }
 
-// unwrapVariant returns the concrete value inside the chcol.Variant envelope the driver scans a
-// Dynamic column — a JSON path such as body_v2.level — into.
-func unwrapVariant(val any) any {
-	if v, ok := val.(chcol.Variant); ok {
+// unwrapVariant decodes a scan envelope: the chcol.Variant the driver scans a Dynamic column (a JSON
+// path such as body_v2.level) into, and the JSONValue a whole JSON column scans into. The attributes
+// bag decodes flat so its dotted keys merge with the legacy attribute maps and a key stored at both a
+// scalar and an object path stays two keys; every other JSON column decodes nested.
+func unwrapVariant(name string, val any) any {
+	switch v := val.(type) {
+	case chcol.Variant:
 		return v.Any()
+	case telemetrystoretypes.JSONValue:
+		if name == "attributes" {
+			return v.Flatten()
+		}
+		return v.Nest()
 	}
 	return val
 }
@@ -54,11 +62,11 @@ func unwrapVariant(val any) any {
 // series. JSON goes through encoding/json for its sorted map keys: ClickHouse groups documents by
 // structure, so two rows it considers equal have to produce the same label.
 func labelValue(val any) string {
-	val = unwrapVariant(val)
+	val = unwrapVariant("", val)
 	if val == nil {
 		return ""
 	}
-	if v, ok := val.(telemetrystoretypes.JSONValue); ok {
+	if v, ok := val.(map[string]any); ok {
 		if raw, err := json.Marshal(v); err == nil {
 			return string(raw)
 		}
@@ -478,7 +486,7 @@ func readAsScalar(rows driver.Rows, queryName string) (*qbtypes.ScalarData, erro
 		// 2. deref each slot into the output row
 		row := make([]any, len(scan))
 		for i, cell := range scan {
-			row[i] = unwrapVariant(derefValue(cell))
+			row[i] = unwrapVariant(stripKeyAlias(colNames[i]), derefValue(cell))
 		}
 		data = append(data, row)
 	}
@@ -536,7 +544,7 @@ func readAsRaw(rows driver.Rows, queryName string) (*qbtypes.RawData, error) {
 			name := stripKeyAlias(colNames[i])
 
 			// de-reference the typed pointer to any
-			val := unwrapVariant(reflect.ValueOf(cellPtr).Elem().Interface())
+			val := unwrapVariant(name, reflect.ValueOf(cellPtr).Elem().Interface())
 
 			// special-case: timestamp column
 			if name == "timestamp" || name == "timestamp_datetime" {
@@ -575,12 +583,15 @@ func mergeSpanAttributeColumns(data map[string]any) {
 	attrStr, hasStr := data["attributes_string"]
 	attrNum, hasNum := data["attributes_number"]
 	attrBool, hasBool := data["attributes_bool"]
-	attrJSON, _ := data["attributes"].(telemetrystoretypes.JSONValue)
+	// readAsRaw already decoded the JSON column into a flat bag of dotted keys via unwrapVariant.
+	attrJSON, _ := data["attributes"].(map[string]any)
 	// todo(nitya): move to resource json
 	resStr, hasRes := data["resources_string"]
 	if hasStr || hasNum || hasBool || attrJSON != nil || hasRes {
 		attributes := make(map[string]any)
-		attrJSON.FlattenInto("", attributes)
+		for k, v := range attrJSON {
+			attributes[k] = v
+		}
 		if m, ok := attrStr.(map[string]string); ok {
 			for k, v := range m {
 				attributes[k] = v

pkg/querier/consume_test.go

@@ -3,16 +3,13 @@ package querier
 import (
 	"reflect"
 	"testing"
-	"time"
 
 	"github.com/ClickHouse/clickhouse-go/v2/lib/chcol"
-	cmock "github.com/SigNoz/clickhouse-go-mock"
-	"github.com/SigNoz/signoz/pkg/telemetrystore"
-	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
-	"github.com/SigNoz/signoz/pkg/types/spantypes"
-	"github.com/SigNoz/signoz/pkg/types/telemetrystoretypes"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/SigNoz/signoz/pkg/types/spantypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrystoretypes"
 )
 
 func TestMergeSpanAttributeColumns_ParsesEventsAndLinks(t *testing.T) {
@@ -83,101 +80,40 @@ func TestMergeSpanAttributeColumns_ParsesEventsAndLinks(t *testing.T) {
 	}
 }
 
-// A ClickHouse query can put a JSON column in the result of any request type — e.g.
-// `select * from signoz_logs.logs_v2` on a body_v2 stack, where `*` covers body_v2.
-func TestConsume_JSONColumn(t *testing.T) {
-	ts := time.Date(2026, 8, 14, 10, 0, 0, 0, time.UTC)
-	body := `{"level":"error","attrs":{"code":500}}`
-	wantBody := telemetrystoretypes.JSONValue{
-		"level": "error",
-		"attrs": map[string]any{"code": float64(500)},
+// jsonColumn builds a JSONValue from dotted leaf paths, as ClickHouse stores them.
+func jsonColumn(paths map[string]any) telemetrystoretypes.JSONValue {
+	j := chcol.NewJSON()
+	for path, value := range paths {
+		j.SetValueAtPath(path, value)
 	}
-
-	// the scalar reader reuses its scan slots across rows, so each row must still carry its own body
-	t.Run("scalar", func(t *testing.T) {
-		rows := telemetrystore.WrapRows(cmock.NewRows([]cmock.ColumnType{
-			{Name: "body_v2", Type: "JSON"},
-			{Name: "__result_0", Type: "UInt64"},
-		}, [][]any{{body, uint64(3)}, {`{"level":"warn"}`, uint64(1)}}))
-
-		payload, err := consume(rows, qbtypes.RequestTypeScalar, nil, qbtypes.Step{}, "A")
-		require.NoError(t, err)
-
-		data := payload.(*qbtypes.ScalarData)
-		require.Len(t, data.Data, 2)
-		assert.Equal(t, wantBody, data.Data[0][0])
-		assert.Equal(t, uint64(3), data.Data[0][1])
-		assert.Equal(t, telemetrystoretypes.JSONValue{"level": "warn"}, data.Data[1][0])
-		assert.Equal(t, uint64(1), data.Data[1][1])
-	})
-
-	t.Run("time series", func(t *testing.T) {
-		rows := telemetrystore.WrapRows(cmock.NewRows([]cmock.ColumnType{
-			{Name: "ts", Type: "DateTime"},
-			{Name: "body_v2", Type: "JSON"},
-			{Name: "__result_0", Type: "UInt64"},
-		}, [][]any{{ts, body, uint64(3)}}))
-
-		payload, err := consume(rows, qbtypes.RequestTypeTimeSeries, nil, qbtypes.Step{}, "A")
-		require.NoError(t, err)
-
-		data := payload.(*qbtypes.TimeSeriesData)
-		require.Len(t, data.Aggregations, 1)
-		require.Len(t, data.Aggregations[0].Series, 1)
-		require.Len(t, data.Aggregations[0].Series[0].Values, 1)
-		assert.Equal(t, float64(3), data.Aggregations[0].Series[0].Values[0].Value)
-	})
-
-	// grouping by a JSON column is legal in ClickHouse, so each document has to label its own
-	// series rather than being dropped, which would merge every group into one
-	t.Run("time series grouped by the JSON column", func(t *testing.T) {
-		rows := telemetrystore.WrapRows(cmock.NewRows([]cmock.ColumnType{
-			{Name: "ts", Type: "DateTime"},
-			{Name: "body_v2", Type: "JSON"},
-			{Name: "__result_0", Type: "UInt64"},
-		}, [][]any{
-			{ts, `{"level":"error"}`, uint64(7)},
-			{ts, `{"level":"warn"}`, uint64(2)},
-		}))
-
-		payload, err := consume(rows, qbtypes.RequestTypeTimeSeries, nil, qbtypes.Step{}, "A")
-		require.NoError(t, err)
-
-		data := payload.(*qbtypes.TimeSeriesData)
-		require.Len(t, data.Aggregations, 1)
-		require.Len(t, data.Aggregations[0].Series, 2)
-
-		got := map[string]float64{}
-		for _, series := range data.Aggregations[0].Series {
-			require.Len(t, series.Labels, 1)
-			require.Len(t, series.Values, 1)
-			got[series.Labels[0].Value.(string)] = series.Values[0].Value
-		}
-		assert.Equal(t, map[string]float64{`{"level":"error"}`: 7, `{"level":"warn"}`: 2}, got)
-	})
-
-	t.Run("raw", func(t *testing.T) {
-		rows := telemetrystore.WrapRows(cmock.NewRows([]cmock.ColumnType{
-			{Name: "timestamp", Type: "DateTime"},
-			{Name: "body_v2", Type: "JSON"},
-		}, [][]any{{ts, body}}))
-
-		payload, err := consume(rows, qbtypes.RequestTypeRaw, nil, qbtypes.Step{}, "A")
-		require.NoError(t, err)
-
-		data := payload.(*qbtypes.RawData)
-		require.Len(t, data.Rows, 1)
-		assert.Equal(t, ts, data.Rows[0].Timestamp.UTC())
-		assert.Equal(t, wantBody, data.Rows[0].Data["body_v2"])
-	})
+	return telemetrystoretypes.NewJSONValue(*j)
 }
 
-// A JSON path (e.g. `body_v2.level`) comes back as a Dynamic column, which the driver scans
-// into a chcol.Variant envelope rather than the value itself.
+// A JSON path (e.g. body_v2.level) comes back as a Dynamic column scanned into a chcol.Variant
+// envelope; a whole JSON column scans into a JSONValue, which decodes flat for the attributes bag and
+// nested for every other column.
 func TestUnwrapVariant(t *testing.T) {
-	assert.Equal(t, "error", unwrapVariant(chcol.NewDynamicWithType("error", "String")))
-	assert.Nil(t, unwrapVariant(chcol.Dynamic{}))
-	assert.Equal(t, uint64(3), unwrapVariant(uint64(3)))
+	jsonCol := jsonColumn(map[string]any{"level": "error", "attrs.code": int64(500)})
+	nullCol := jsonColumn(map[string]any{"level": "error", "absent": chcol.Variant{}})
+
+	testCases := []struct {
+		name   string
+		column string
+		input  any
+		want   any
+	}{
+		{name: "VariantScalar", column: "", input: chcol.NewDynamicWithType("error", "String"), want: "error"},
+		{name: "EmptyDynamic", column: "", input: chcol.Dynamic{}, want: nil},
+		{name: "PlainValuePassthrough", column: "", input: uint64(3), want: uint64(3)},
+		{name: "JSONColumnNested", column: "body_v2", input: jsonCol, want: map[string]any{"level": "error", "attrs": map[string]any{"code": float64(500)}}},
+		{name: "AttributesColumnFlat", column: "attributes", input: jsonCol, want: map[string]any{"level": "error", "attrs.code": float64(500)}},
+		{name: "AttributesColumnDropsNullPaths", column: "attributes", input: nullCol, want: map[string]any{"level": "error"}},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			assert.Equal(t, testCase.want, unwrapVariant(testCase.column, testCase.input))
+		})
+	}
 }
 
 func TestMergeSpanAttributeColumns_EmptyEventsAndLinks(t *testing.T) {
@@ -196,8 +132,8 @@ func TestMergeSpanAttributeColumns_EmptyEventsAndLinks(t *testing.T) {
 	}
 }
 
-// Arrays stay native leaves: the collector stringifies top-level arrays and explodes nested ones
-// into indexed keys in the legacy maps; the JSON home keeps them whole and we do not mimic either.
+// readAsRaw decodes the JSON column into a flat bag of dotted keys before this runs; mergeSpanAttributeColumns
+// copies that bag and overlays the legacy string/number/bool maps, which win on collision.
 func TestMergeSpanAttributeColumns_JSONColumn(t *testing.T) {
 	testCases := []struct {
 		name string
@@ -205,12 +141,9 @@ func TestMergeSpanAttributeColumns_JSONColumn(t *testing.T) {
 		want map[string]any
 	}{
 		{
-			name: "JSONOnly_FlattensNestedPaths_PreservesTypes",
+			name: "JSONOnly_FlatBagCopied_PreservesTypes",
 			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{
-					"http":      map[string]any{"route": "/api/pay", "retry": map[string]any{"count": float64(3)}},
-					"cache.hit": true,
-				},
+				"attributes": map[string]any{"http.route": "/api/pay", "http.retry.count": float64(3), "cache.hit": true},
 			},
 			want: map[string]any{"http.route": "/api/pay", "http.retry.count": float64(3), "cache.hit": true},
 		},
@@ -219,17 +152,17 @@ func TestMergeSpanAttributeColumns_JSONColumn(t *testing.T) {
 			data: map[string]any{
 				"attributes_string": map[string]string{"http.route": "/old", "only.map": "m"},
 				"attributes_number": map[string]float64{"http.status": 500},
-				"attributes":        telemetrystoretypes.JSONValue{"http": map[string]any{"route": "/new"}, "only.json": "j"},
+				"attributes":        map[string]any{"http.route": "/new", "only.json": "j"},
 			},
 			want: map[string]any{"http.route": "/old", "only.map": "m", "http.status": float64(500), "only.json": "j"},
 		},
 		{
-			name: "MapOnly_EmptyJSONDoc_KeepsMapValues",
+			name: "MapOnly_EmptyJSONBag_KeepsMapValues",
 			data: map[string]any{
 				"attributes_string": map[string]string{"http.route": "/map"},
 				"attributes_number": map[string]float64{"http.status": 200},
 				"attributes_bool":   map[string]bool{"cache.hit": true},
-				"attributes":        telemetrystoretypes.JSONValue{},
+				"attributes":        map[string]any{},
 			},
 			want: map[string]any{"http.route": "/map", "http.status": float64(200), "cache.hit": true},
 		},
@@ -237,60 +170,39 @@ func TestMergeSpanAttributeColumns_JSONColumn(t *testing.T) {
 			name: "MapOnly_NilJSON_BehavesAsAbsent",
 			data: map[string]any{
 				"attributes_string": map[string]string{"http.route": "/map"},
-				"attributes":        telemetrystoretypes.JSONValue(nil),
+				"attributes":        map[string]any(nil),
 			},
 			want: map[string]any{"http.route": "/map"},
 		},
 		{
 			name: "Arrays_StayLeafValues",
 			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"http": map[string]any{"tags": []any{"a", "b"}, "codes": []any{float64(1), float64(2)}}},
+				"attributes": map[string]any{"http.tags": []any{"a", "b"}, "http.codes": []any{float64(1), float64(2)}},
 			},
 			want: map[string]any{"http.tags": []any{"a", "b"}, "http.codes": []any{float64(1), float64(2)}},
 		},
 		{
-			name: "TopLevelArrayOfMaps_StaysNativeLeaf",
+			name: "ScalarAndObjectKey_BothSurvive",
 			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"key": []any{map[string]any{"a": float64(1)}, map[string]any{"b": float64(2)}}},
+				"attributes": map[string]any{"db.function": "refresh", "db.function.arg": float64(2)},
 			},
-			want: map[string]any{"key": []any{map[string]any{"a": float64(1)}, map[string]any{"b": float64(2)}}},
+			want: map[string]any{"db.function": "refresh", "db.function.arg": float64(2)},
 		},
 		{
-			name: "NestedArrayOfMaps_StaysNativeLeaf_NoIndexPaths",
-			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"http": map[string]any{"items": []any{map[string]any{"a": float64(1)}}}},
-			},
-			want: map[string]any{"http.items": []any{map[string]any{"a": float64(1)}}},
-		},
-		{
-			name: "DualWritten_NestedArray_IndexKeysAndJSONArrayCoexist",
+			name: "DualWritten_IndexKeysAndJSONArrayCoexist",
 			data: map[string]any{
 				"attributes_number": map[string]float64{"http.items.0.a": 1},
-				"attributes":        telemetrystoretypes.JSONValue{"http": map[string]any{"items": []any{map[string]any{"a": float64(1)}}}},
+				"attributes":        map[string]any{"http.items": []any{map[string]any{"a": float64(1)}}},
 			},
 			want: map[string]any{"http.items.0.a": float64(1), "http.items": []any{map[string]any{"a": float64(1)}}},
 		},
 		{
-			name: "JSONNull_KeptAsNil",
+			name: "ScalarValueStaysScalar",
 			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"k": nil},
-			},
-			want: map[string]any{"k": nil},
-		},
-		{
-			name: "KeyIsLeafValue_NotFlattened",
-			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"http": "plaintext"},
+				"attributes": map[string]any{"http": "plaintext"},
 			},
 			want: map[string]any{"http": "plaintext"},
 		},
-		{
-			name: "KeyIsParent_FlattensToDottedPath",
-			data: map[string]any{
-				"attributes": telemetrystoretypes.JSONValue{"http": map[string]any{"route": "/a"}},
-			},
-			want: map[string]any{"http.route": "/a"},
-		},
 	}
 
 	for _, testCase := range testCases {

pkg/querier/postprocess.go

@@ -16,7 +16,6 @@ import (
 	"github.com/SigNoz/signoz/pkg/querybuilder"
 	"github.com/SigNoz/signoz/pkg/types/featuretypes"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
-	"github.com/SigNoz/signoz/pkg/types/telemetrystoretypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
 )
@@ -232,7 +231,11 @@ func postProcessMetricQuery(
 		}
 	}
 
-	result = q.applySeriesLimit(result, query.Limit, query.Order)
+	reducesToScalar := req.RequestType == qbtypes.RequestTypeScalar && config.ReduceTo != qbtypes.ReduceToUnknown
+
+	if !reducesToScalar {
+		result = q.applySeriesLimit(result, query.Limit, query.Order)
+	}
 
 	if len(query.Functions) > 0 {
 		step := query.StepInterval.Milliseconds()
@@ -241,9 +244,11 @@ func postProcessMetricQuery(
 	}
 
 	// Apply reduce to for scalar request type
-	if req.RequestType == qbtypes.RequestTypeScalar {
-		if len(query.Aggregations) > 0 && query.Aggregations[0].ReduceTo != qbtypes.ReduceToUnknown {
-			result = q.applyMetricReduceTo(result, query.Aggregations[0].ReduceTo)
+	if reducesToScalar {
+		result = q.applyMetricReduceTo(result, config.ReduceTo)
+		result = q.applySeriesLimit(result, query.Limit, query.Order)
+		if tsData, ok := result.Value.(*qbtypes.TimeSeriesData); ok {
+			result.Value = convertTimeSeriesDataToScalar(tsData, tsData.QueryName)
 		}
 	}
 
@@ -287,9 +292,6 @@ func (q *querier) applyMetricReduceTo(result *qbtypes.Result, reduceOp qbtypes.R
 		}
 	}
 
-	scalarData := convertTimeSeriesDataToScalar(tsData, tsData.QueryName)
-	result.Value = scalarData
-
 	return result
 }
 
@@ -497,6 +499,9 @@ func bucketFormulaOutputAsHeatmap(tsData *qbtypes.TimeSeriesData, bucketing qbty
 // to stay identical to them: a formula heatmap and a metric heatmap that
 // disagreed here would put their counts in different buckets.
 func calculateLinearValueUpperBound(bucketing qbtypes.HeatmapBucketing, value float64) float64 {
+	if value <= 0 {
+		return 0
+	}
 	if value > bucketing.MaxValue {
 		return math.Inf(1)
 	}
@@ -1202,7 +1207,7 @@ func (q *querier) postProcessLogBody(ctx context.Context, orgID valuer.UUID, res
 // carried one. Anything that is not a decoded document — the legacy string body, a NULL cell —
 // is legal under these names and left alone.
 func stripEmptyBodyMessage(val any) {
-	bodyMap, ok := val.(telemetrystoretypes.JSONValue)
+	bodyMap, ok := val.(map[string]any)
 	if !ok {
 		return
 	}

pkg/querier/postprocess_test.go

@@ -150,6 +150,107 @@ func TestProcessScalarFormula_AppliesOrderAndLimit(t *testing.T) {
 	})
 }
 
+func TestPostProcessMetricQuery_LimitRanksByReducedValue(t *testing.T) {
+	q := &querier{
+		logger: instrumentationtest.New().Logger(),
+	}
+
+	serviceKey := telemetrytypes.TelemetryFieldKey{Name: "service.name", FieldDataType: telemetrytypes.FieldDataTypeString}
+	series := func(service string, points ...float64) *qbtypes.TimeSeries {
+		values := make([]*qbtypes.TimeSeriesValue, 0, len(points))
+		for i, point := range points {
+			values = append(values, &qbtypes.TimeSeriesValue{Timestamp: int64(i) * 60000, Value: point})
+		}
+		return &qbtypes.TimeSeries{Labels: []*qbtypes.Label{{Key: serviceKey, Value: service}}, Values: values}
+	}
+	// avg: checkout 10, payment 8.8, auth 6, search 2
+	makeResult := func() *qbtypes.Result {
+		return &qbtypes.Result{Value: &qbtypes.TimeSeriesData{
+			QueryName: "A",
+			Aggregations: []*qbtypes.AggregationBucket{{Series: []*qbtypes.TimeSeries{
+				series("checkout", 10, 10, 10, 10, 10),
+				series("payment", 1, 1, 1, 1, 40),
+				series("auth", 0, 0, 0, 0, 30),
+				series("search", 2, 2, 2, 2, 2),
+			}}},
+		}}
+	}
+	orderByValue := func(direction qbtypes.OrderDirection) []qbtypes.OrderBy {
+		return []qbtypes.OrderBy{{
+			Key:       qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: qbtypes.DefaultOrderByKey}},
+			Direction: direction,
+		}}
+	}
+
+	testCases := []struct {
+		name     string
+		reduceTo qbtypes.ReduceTo
+		order    []qbtypes.OrderBy
+		expected [][]any
+	}{
+		{
+			name:     "Max_Desc_KeepsHighestPeaks",
+			reduceTo: qbtypes.ReduceToMax,
+			order:    orderByValue(qbtypes.OrderDirectionDesc),
+			expected: [][]any{{"payment", 40.0}, {"auth", 30.0}},
+		},
+		{
+			name:     "Last_Desc_KeepsHighestLastPoints",
+			reduceTo: qbtypes.ReduceToLast,
+			order:    orderByValue(qbtypes.OrderDirectionDesc),
+			expected: [][]any{{"payment", 40.0}, {"auth", 30.0}},
+		},
+		{
+			name:     "Min_Asc_KeepsLowestMinimums",
+			reduceTo: qbtypes.ReduceToMin,
+			order:    orderByValue(qbtypes.OrderDirectionAsc),
+			expected: [][]any{{"auth", 0.0}, {"payment", 1.0}},
+		},
+		{
+			name:     "Max_NoOrder_DefaultsToDesc",
+			reduceTo: qbtypes.ReduceToMax,
+			expected: [][]any{{"payment", 40.0}, {"auth", 30.0}},
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			query := qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+				Name:         "A",
+				Aggregations: []qbtypes.MetricAggregation{{MetricName: "http_requests_total", ReduceTo: testCase.reduceTo}},
+				Order:        testCase.order,
+				Limit:        2,
+			}
+			req := &qbtypes.QueryRangeRequest{RequestType: qbtypes.RequestTypeScalar}
+
+			out := postProcessMetricQuery(q, makeResult(), query, req)
+			scalar, ok := out.Value.(*qbtypes.ScalarData)
+			require.True(t, ok, "expected *ScalarData, got %T", out.Value)
+
+			assert.Equal(t, testCase.expected, scalar.Data)
+		})
+	}
+
+	t.Run("TimeSeries_RanksByAverage", func(t *testing.T) {
+		query := qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+			Name:         "A",
+			Aggregations: []qbtypes.MetricAggregation{{MetricName: "http_requests_total"}},
+			Order:        orderByValue(qbtypes.OrderDirectionDesc),
+			Limit:        2,
+		}
+		req := &qbtypes.QueryRangeRequest{RequestType: qbtypes.RequestTypeTimeSeries}
+
+		out := postProcessMetricQuery(q, makeResult(), query, req)
+		tsData, ok := out.Value.(*qbtypes.TimeSeriesData)
+		require.True(t, ok, "expected *TimeSeriesData, got %T", out.Value)
+		require.Len(t, tsData.Aggregations, 1)
+		require.Len(t, tsData.Aggregations[0].Series, 2)
+
+		assert.Equal(t, "checkout", tsData.Aggregations[0].Series[0].Labels[0].Value)
+		assert.Equal(t, "payment", tsData.Aggregations[0].Series[1].Labels[0].Value)
+	})
+}
+
 // Multiple series with different number of labels, shouldn't panic and should align labels correctly.
 func TestConvertTimeSeriesDataToScalar_RaggedLabels(t *testing.T) {
 	label := func(name string, value any) *qbtypes.Label {

pkg/query-service/rules/threshold_rule.go

@@ -85,9 +85,7 @@ func (r *ThresholdRule) prepareQueryRange(ctx context.Context, ts time.Time) (*q
 	return req, nil
 }
 
-func (r *ThresholdRule) prepareParamsForLogs(ctx context.Context, ts time.Time, lbls ruletypes.Labels) url.Values {
-	selectedQuery := r.SelectedQuery(ctx)
-
+func (r *ThresholdRule) prepareParamsForLogs(ctx context.Context, ts time.Time, resultLabels ruletypes.Labels) url.Values {
 	qr, err := r.prepareQueryRange(ctx, ts)
 	if err != nil {
 		return nil
@@ -95,24 +93,19 @@ func (r *ThresholdRule) prepareParamsForLogs(ctx context.Context, ts time.Time,
 	start := time.UnixMilli(int64(qr.Start))
 	end := time.UnixMilli(int64(qr.End))
 
-	// TODO(srikanthccv): handle formula queries
-	if selectedQuery < "A" || selectedQuery > "Z" {
+	whereClause, found, err := contextlinks.PrepareRuleFilterExpression(r.ruleCondition, telemetrytypes.SignalLogs, resultLabels.Map())
+	if err != nil {
+		r.logger.ErrorContext(ctx, "failed to prepare the filter for the logs link", errors.Attr(err))
 		return nil
 	}
-
-	filterExpr, groupBy, found := contextlinks.BuilderQueryForSignal(r.ruleCondition.CompositeQuery.Queries, telemetrytypes.SignalLogs)
 	if !found {
 		return nil
 	}
 
-	whereClause := contextlinks.PrepareFilterExpression(lbls.Map(), filterExpr, groupBy)
-
 	return contextlinks.PrepareParamsForLogsV5(start, end, whereClause)
 }
 
-func (r *ThresholdRule) prepareParamsForTraces(ctx context.Context, ts time.Time, lbls ruletypes.Labels) url.Values {
-	selectedQuery := r.SelectedQuery(ctx)
-
+func (r *ThresholdRule) prepareParamsForTraces(ctx context.Context, ts time.Time, resultLabels ruletypes.Labels) url.Values {
 	qr, err := r.prepareQueryRange(ctx, ts)
 	if err != nil {
 		return nil
@@ -120,18 +113,15 @@ func (r *ThresholdRule) prepareParamsForTraces(ctx context.Context, ts time.Time
 	start := time.UnixMilli(int64(qr.Start))
 	end := time.UnixMilli(int64(qr.End))
 
-	// TODO(srikanthccv): handle formula queries
-	if selectedQuery < "A" || selectedQuery > "Z" {
+	whereClause, found, err := contextlinks.PrepareRuleFilterExpression(r.ruleCondition, telemetrytypes.SignalTraces, resultLabels.Map())
+	if err != nil {
+		r.logger.ErrorContext(ctx, "failed to prepare the filter for the traces link", errors.Attr(err))
 		return nil
 	}
-
-	filterExpr, groupBy, found := contextlinks.BuilderQueryForSignal(r.ruleCondition.CompositeQuery.Queries, telemetrytypes.SignalTraces)
 	if !found {
 		return nil
 	}
 
-	whereClause := contextlinks.PrepareFilterExpression(lbls.Map(), filterExpr, groupBy)
-
 	return contextlinks.PrepareParamsForTracesV5(start, end, whereClause, r.typ.BuilderQueryType())
 }
 

pkg/signoz/module.go

@@ -159,7 +159,7 @@ func NewModules(
 		ServiceAccount:       serviceAccount,
 		ServiceAccountGetter: serviceAccountGetter,
 		LogsPipeline:         impllogspipeline.NewModule(sqlstore),
-		RuleStateHistory:     implrulestatehistory.NewModule(implrulestatehistory.NewStore(telemetryStore, telemetryMetadataStore, providerSettings.Logger), ruleStore),
+		RuleStateHistory:     implrulestatehistory.NewModule(implrulestatehistory.NewStore(telemetryStore, telemetryMetadataStore, providerSettings.Logger), ruleStore, providerSettings.Logger),
 		CloudIntegration:     cloudIntegrationModule,
 		TraceDetail:          impltracedetail.NewModule(impltracedetail.NewTraceStore(telemetryStore, telemetryMetadataStore, fl), providerSettings, config.TraceDetail),
 		SpanMapper:           spanMapper,

pkg/telemetrystore/clickhousetelemetrystore/provider.go

@@ -97,8 +97,10 @@ func New(ctx context.Context, providerSettings factory.ProviderSettings, config
 	options.MaxIdleConns = config.Connection.MaxIdleConns
 	options.MaxOpenConns = config.Connection.MaxOpenConns
 	options.DialTimeout = config.Connection.DialTimeout
-	// This is to avoid the driver decoding issues with JSON columns
-	options.Settings["output_format_native_write_json_as_string"] = 1
+	// Read JSON columns natively: the driver mis-decodes JSON(max_dynamic_paths=0) columns without
+	// the flattened serialization, and reading them as a string collapses a key stored at both a
+	// scalar and an object path.
+	options.Settings["output_format_native_use_flattened_dynamic_and_json_serialization"] = 1
 
 	chConn, err := clickhouse.Open(options)
 	if err != nil {