Add dedicated traces view docs by alexandra5000 · Pull Request #5547 · elastic/docs-content

alexandra5000 · 2026-03-18T16:36:04Z

Summary

This PR closes #3020 and adds docs for the traces-specific Discover view.

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: Claude Sonnet 4.6

github-actions · 2026-03-18T16:37:24Z

Vale Linting Results

Summary: 1 suggestion found

💡 Suggestions (1)

File	Line	Rule	Message
solutions/observability/apm/discover-traces.md	13	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

github-actions · 2026-03-18T16:39:44Z

🔍 Preview links for changed docs

alexandra5000 · 2026-03-18T16:48:11Z

solutions/observability/apm/discover-traces.md

+The traces experience is available in:
+
+* **{{data-source-cap}} mode**: Select a {{data-source}} that matches a `traces-*` index pattern from the **Discover** main page.
+
+* **{{esql}} mode**: Select **Try {{esql}}** and use the `FROM` command to query your trace data:


I was able to use it in both modes when testing, but I used 9.3.1 - to be confirmed if it works in data view on 9.2 as well.

benironside

Looks excellent. Just left a few conceptual questions for your consideration — hope they're helpful, ignore 'em if not!

benironside · 2026-03-18T18:49:55Z

solutions/observability/apm/discover-traces.md

+
+### Data recognition [traces-data-recognition]
+
+By default, data stored in `traces-*` indices is recognized as trace data and triggers the **Discover** experience described on this page.


If we're going to say this is the default behavrior, maybe worth mentioning how to change the default?

benironside · 2026-03-18T18:51:07Z

solutions/observability/apm/discover-traces.md

+
+## Traces-specific features [traces-specific-features]
+
+When **Discover** recognizes trace data, it pre-selects a set of relevant fields as columns in the data grid: `service.name`, `transaction.name`, `span.name`, `transaction.duration.us`, `span.duration.us`, and `event.outcome`.


Maybe link to more info about how to change which columns are selected, if relevant.

solutions/observability/apm/discover-traces.md

mdbirnstiehl

Overall LGTM! It looks like there might be some differences depending on the version you're using with the ES|QL button and some headings in details flyout. I could also see the updated details flyout when using a 9.3 deployment, but I couldn't see the new Latency, Error rate, and Throughput charts. That could be operator error however 😄.

mdbirnstiehl · 2026-03-18T20:40:26Z

solutions/observability/apm/discover-traces.md

@@ -0,0 +1,121 @@
+---
+applies_to:
+  stack: preview 9.2


Are we sure this was available in 9.2? I'm seeing the traces features in ES|QL view when using Serverless and 9.4, but not in 9.3. Maybe the deployments I have access to don't have the right data.

I see it in 9.3 for sure, should be available in 9.2 as well - @davismcphee could you confirm please?

mdbirnstiehl · 2026-03-18T20:45:35Z

solutions/observability/apm/discover-traces.md

+
+* **{{data-source-cap}} mode**: Select a {{data-source}} that matches a `traces-*` index pattern from the **Discover** main page.
+
+* **{{esql}} mode**: Select **Try {{esql}}** and use the `FROM` command to query your trace data:


I think the button in serverless and 9.4 now just says "</> ES|QL"

I don't have access to the 9.4 deployment, in my version is still says "Try ESQL". I might have to create tabs for stack vs serverless

solutions/observability/apm/discover-traces.md

mdbirnstiehl · 2026-03-18T20:51:42Z

solutions/observability/apm/discover-traces.md

+
+Select **Open in Discover** to open a filtered view of all similar spans.
+
+### Trace waterfall [trace-waterfall]


Suggested change

### Trace waterfall [trace-waterfall]

### Trace summary [trace-waterfall]

Looks like the name in the actual UI is "Trace summary" now? Looks like this is maybe a 9.4 and serverless update right now.

mdbirnstiehl · 2026-03-18T20:57:24Z

solutions/observability/apm/discover-traces.md

+
+### Trace waterfall [trace-waterfall]
+
+The **Trace** section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.


Suggested change

The **Trace** section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.

The **Trace summary** section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.

This heading might be version-dependent since I see your screenshot is showing as "Trace"

Yup, looks like it - I don't have access to 9.4 yet though. Thanks for pointing it out!

alexandra5000 · 2026-03-19T16:59:32Z

Hi @davismcphee could you please review / check if this is technically correct? 🙏

davismcphee

Thanks for the ping and adding traces docs! Left a few minor comments, but nothing blocking.

davismcphee · 2026-03-20T18:31:22Z

solutions/observability/apm/discover-traces.md

@@ -0,0 +1,121 @@
+---
+applies_to:
+  stack: preview 9.2+


I think it was technically 9.1 since that's when this PR merged: elastic/kibana#224869.

davismcphee · 2026-03-20T18:31:24Z

solutions/observability/apm/discover-traces.md

+applies_to:
+  stack: preview 9.2+
+  serverless: preview
+description: Explore trace data in Discover using the traces profile.


"Profile" is more of an implementation detail than a user concept. I think we've been avoiding it so far in other Discover docs.

davismcphee · 2026-03-20T18:31:26Z

solutions/observability/apm/discover-traces.md

+# Explore traces in Discover [explore-traces-discover]
+
+:::{important}
+This functionality is experimental and not supported. It may change or be removed at anytime.


Nit: I don't really understand what "unsupported" means in this context.

davismcphee · 2026-03-20T18:31:27Z

solutions/observability/apm/discover-traces.md

+This functionality is experimental and not supported. It may change or be removed at anytime.
+:::
+
+**Discover** offers a dedicated experience for exploring trace data. When **Discover** detects data in `traces-*` indices, it automatically selects relevant fields and enables features that help you investigate distributed traces more effectively. The traces experience includes a pre-selected set of trace fields in the data grid, a structured overview of each document's key attributes, latency comparisons for similar spans, and a waterfall visualization of the full trace timeline.


Suggested change

**Discover** offers a dedicated experience for exploring trace data. When **Discover** detects data in `traces-*` indices, it automatically selects relevant fields and enables features that help you investigate distributed traces more effectively. The traces experience includes a pre-selected set of trace fields in the data grid, a structured overview of each document's key attributes, latency comparisons for similar spans, and a waterfall visualization of the full trace timeline.

**Discover** offers a dedicated experience for exploring trace data. When **Discover** detects data in `traces-*` indices, it automatically enables features that help you investigate distributed traces more effectively. The traces experience includes a pre-selected set of trace fields in the data grid, a structured overview of each document's key attributes, latency comparisons for similar spans, and a waterfall visualization of the full trace timeline.

Nit: we mention default fields two sentences in a row. I think it would still read well if we dropped the first occurrence.

davismcphee · 2026-03-20T18:31:46Z

solutions/observability/apm/discover-traces.md

+:screenshot:
+:::
+
+Select **Expand trace timeline** to open the full-screen waterfall view.


It's no longer a full screen view, they replaced it with a dedicated flyout view. Maybe we could just go with "to open the expanded waterfall view" or similar instead.

alexandra5000 and others added 3 commits March 18, 2026 15:01

Add traces exploration section to Discover documentation

9bbf199

update screenshot

a69947a

Merge branch 'main' into traces-discover

4dc3b50

github-actions bot deployed to docs-preview March 18, 2026 16:37 View deployment

alexandra5000 commented Mar 18, 2026

View reviewed changes

alexandra5000 marked this pull request as ready for review March 18, 2026 16:52

alexandra5000 requested review from a team as code owners March 18, 2026 16:52

benironside approved these changes Mar 18, 2026

View reviewed changes

mdbirnstiehl reviewed Mar 18, 2026

View reviewed changes

alexandra5000 requested a review from davismcphee March 19, 2026 16:58

Apply peer review comments (partially)

c329c5d

github-actions bot deployed to docs-preview March 20, 2026 17:17 View deployment

davismcphee approved these changes Mar 20, 2026

View reviewed changes


		### Data recognition [traces-data-recognition]

		By default, data stored in `traces-` indices is recognized as trace data and triggers the Discover* experience described on this page.


		## Traces-specific features [traces-specific-features]

		When Discover recognizes trace data, it pre-selects a set of relevant fields as columns in the data grid: `service.name`, `transaction.name`, `span.name`, `transaction.duration.us`, `span.duration.us`, and `event.outcome`.


		* {{data-source-cap}} mode: Select a {{data-source}} that matches a `traces-` index pattern from the Discover* main page.

		* {{esql}} mode: Select Try {{esql}} and use the `FROM` command to query your trace data:


		Select Open in Discover to open a filtered view of all similar spans.

		### Trace waterfall [trace-waterfall]

	### Trace waterfall [trace-waterfall]
	### Trace summary [trace-waterfall]


		### Trace waterfall [trace-waterfall]

		The Trace section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.

	The Trace section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.
	The Trace summary section shows a condensed waterfall of the trace the selected document belongs to. Each row represents a span or transaction, positioned on a timeline to show when it started and how long it took.

Conversation

alexandra5000 commented Mar 18, 2026

Summary

Generative AI disclosure

Uh oh!

github-actions bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

alexandra5000 Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benironside left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mdbirnstiehl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexandra5000 commented Mar 19, 2026

Uh oh!

davismcphee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 18, 2026 •

edited

Loading

github-actions bot commented Mar 18, 2026 •

edited

Loading

alexandra5000 Mar 18, 2026 •

edited

Loading