From 35306cf35310a9b195f6443ba11be873941ea562 Mon Sep 17 00:00:00 2001
From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Date: Thu, 19 Oct 2023 11:07:09 -0400
Subject: [PATCH] [8.11] [DOCS] Clean up APM UI docs (#169269) (#169411)

# Backport

This will backport the following commits from `main` to `8.11`:
- [[DOCS] Clean up APM UI docs
(#169269)](https://github.com/elastic/kibana/pull/169269)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Colleen
McGinnis","email":"colleen.mcginnis@elastic.co"},"sourceCommit":{"committedDate":"2023-10-19T14:42:45Z","message":"[DOCS]
Clean up APM UI docs (#169269)\n\nCloses
https://github.com/elastic/observability-docs/issues/3292\r\n\r\n##
Summary\r\n\r\nUpdates documentation related to the APM UI based on
issues found during\r\nthe Observability docs bug bash last
week.\r\n\r\n### Checklist\r\n\r\nDelete any items that are not
applicable to this PR.\r\n\r\n- [x]
@colleenmcginnis\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials:\r\n- [x]
Clarify that distributed traces aren't the only colorful traces
in\r\n[Trace
sample\r\ntimeline](https://www.elastic.co/guide/en/kibana/current/spans.html#distributed-tracing)\r\n(https://github.com/elastic/kibana/commit/b707c3936bbf6fd3dcf2651653d5fa527a085171)\r\n-
[x] Clarify the implications of the traces table only showing
root\r\ntransactions
in\r\n[Traces](https://www.elastic.co/guide/en/kibana/current/traces.html)\r\n(https://github.com/elastic/kibana/commit/c1de678f912c03159926119aead13912a6d9239b)\r\n-
[x] Add beta admonition to
APM\r\n[Infrastucture](https://www.elastic.co/guide/en/kibana/current/infrastructure.html)\r\npage\r\n(https://github.com/elastic/kibana/commit/d3bc4a972d3066485f9c6feb747af64298758f59)\r\n-
[x] @bmorelli25
review","sha":"7b0d842096500ef569f8d879d8fb913ac29cf318","branchLabelMapping":{"^v8.12.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","docs","v8.10.0","v8.11.0","v8.12.0"],"number":169269,"url":"https://github.com/elastic/kibana/pull/169269","mergeCommit":{"message":"[DOCS]
Clean up APM UI docs (#169269)\n\nCloses
https://github.com/elastic/observability-docs/issues/3292\r\n\r\n##
Summary\r\n\r\nUpdates documentation related to the APM UI based on
issues found during\r\nthe Observability docs bug bash last
week.\r\n\r\n### Checklist\r\n\r\nDelete any items that are not
applicable to this PR.\r\n\r\n- [x]
@colleenmcginnis\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials:\r\n- [x]
Clarify that distributed traces aren't the only colorful traces
in\r\n[Trace
sample\r\ntimeline](https://www.elastic.co/guide/en/kibana/current/spans.html#distributed-tracing)\r\n(https://github.com/elastic/kibana/commit/b707c3936bbf6fd3dcf2651653d5fa527a085171)\r\n-
[x] Clarify the implications of the traces table only showing
root\r\ntransactions
in\r\n[Traces](https://www.elastic.co/guide/en/kibana/current/traces.html)\r\n(https://github.com/elastic/kibana/commit/c1de678f912c03159926119aead13912a6d9239b)\r\n-
[x] Add beta admonition to
APM\r\n[Infrastucture](https://www.elastic.co/guide/en/kibana/current/infrastructure.html)\r\npage\r\n(https://github.com/elastic/kibana/commit/d3bc4a972d3066485f9c6feb747af64298758f59)\r\n-
[x] @bmorelli25
review","sha":"7b0d842096500ef569f8d879d8fb913ac29cf318"}},"sourceBranch":"main","suggestedTargetBranches":["8.10","8.11"],"targetPullRequestStates":[{"branch":"8.10","label":"v8.10.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.11","label":"v8.11.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.12.0","labelRegex":"^v8.12.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/169269","number":169269,"mergeCommit":{"message":"[DOCS]
Clean up APM UI docs (#169269)\n\nCloses
https://github.com/elastic/observability-docs/issues/3292\r\n\r\n##
Summary\r\n\r\nUpdates documentation related to the APM UI based on
issues found during\r\nthe Observability docs bug bash last
week.\r\n\r\n### Checklist\r\n\r\nDelete any items that are not
applicable to this PR.\r\n\r\n- [x]
@colleenmcginnis\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials:\r\n- [x]
Clarify that distributed traces aren't the only colorful traces
in\r\n[Trace
sample\r\ntimeline](https://www.elastic.co/guide/en/kibana/current/spans.html#distributed-tracing)\r\n(https://github.com/elastic/kibana/commit/b707c3936bbf6fd3dcf2651653d5fa527a085171)\r\n-
[x] Clarify the implications of the traces table only showing
root\r\ntransactions
in\r\n[Traces](https://www.elastic.co/guide/en/kibana/current/traces.html)\r\n(https://github.com/elastic/kibana/commit/c1de678f912c03159926119aead13912a6d9239b)\r\n-
[x] Add beta admonition to
APM\r\n[Infrastucture](https://www.elastic.co/guide/en/kibana/current/infrastructure.html)\r\npage\r\n(https://github.com/elastic/kibana/commit/d3bc4a972d3066485f9c6feb747af64298758f59)\r\n-
[x] @bmorelli25
review","sha":"7b0d842096500ef569f8d879d8fb913ac29cf318"}}]}]
BACKPORT-->

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>
---
 docs/apm/infrastructure.asciidoc | 2 ++
 docs/apm/spans.asciidoc          | 5 +++--
 docs/apm/traces.asciidoc         | 4 ++++
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/apm/infrastructure.asciidoc b/docs/apm/infrastructure.asciidoc
index f9cf45aa490c2..8ca919ffca6c4 100644
--- a/docs/apm/infrastructure.asciidoc
+++ b/docs/apm/infrastructure.asciidoc
@@ -2,6 +2,8 @@
 [[infrastructure]]
 === Infrastructure
 
+beta::[]
+
 The *Infrastructure* tab provides information about the containers, pods, and hosts,
 that the selected service is linked to.
 
diff --git a/docs/apm/spans.asciidoc b/docs/apm/spans.asciidoc
index 5b23e69b18c6b..40af80cb864a9 100644
--- a/docs/apm/spans.asciidoc
+++ b/docs/apm/spans.asciidoc
@@ -43,8 +43,9 @@ For example, quickly view:
 [[distributed-tracing]]
 ==== Distributed tracing
 
-If your trace sample timeline is colorful, it's indicative of a distributed trace.
-Services in a distributed trace are separated by color and listed in the order they occur.
+When a trace travels through multiple services it is known as a _distributed trace_.
+In APM, the colors in a distributed trace represent different services and
+are listed in the order they occur.
 
 [role="screenshot"]
 image::apm/images/apm-services-trace.png[Example of distributed trace colors in the APM app in Kibana]
diff --git a/docs/apm/traces.asciidoc b/docs/apm/traces.asciidoc
index 1269781e7798e..4c912a03dcf64 100644
--- a/docs/apm/traces.asciidoc
+++ b/docs/apm/traces.asciidoc
@@ -17,6 +17,10 @@ it's the collective amount of pain a specific endpoint is causing your users.
 If there's a particular endpoint you're worried about, select it to view its
 <<transaction-details,transaction details>>.
 
+You can also use queries to filter and search the transactions shown on this page.
+Note that only properties available on root transactions are searchable.
+For example, you can't search for `label.tier: 'high'`, as that field is only available on non-root transactions.
+
 [role="screenshot"]
 image::apm/images/apm-traces.png[Example view of the Traces overview in APM app in Kibana]