Move APM UI documentation to observability-docs with history #3723

bmorelli25 · 2024-04-03T19:22:48Z

Summary

Moves our APM UI documentation from the Kibana repo to the Observability docs repo
Maintains commit history
Restructures APM UI docs into the preexisting APM content

Potential future improvements

Combine API sections
Combine troubleshooting sections
Combine settings sections
Move storage explorer docs into manage storage section

@gchaps

Adding new documentation about the APM UI and definitions of terminology and more. * Images added to docs * Adding Using APM UI page contents * Including new APM UI page * Updated Watcher copy * Copy feedback from @gchaps

Adding content for Machine Learning integration and query bar UI in the Using the APM UI docs.

* docs: initial APM UI updates * docs: using-the-apm-ui updates * more docs updates * quick edits * docs: apply feedback and fix screenshots * docs: incorporate feedback, bold page names * finishing touches and clean up * docs: incorporate feedback from sarah * docs: add feedback * docs: incorporate feedback from gchaps

* [DOCS] Removed ss above spatial references * Removed above from n numeral formatting page

@gchaps

## Summary @gchaps and I met to review text on some APM UI pages. Outcomes: 1. Service **m**ap or Service **M**ap — there is inconsistency in the APM UI with how we refer to Service maps. In some cases, we use title case (Service Map). In others, we use sentence case (Service map). As per the [EUI writing guidelines](https://eui.elastic.co/#/guidelines/writing/guidelines#capitalization), we should use title case for product features. 2. Storage **e**xplorer or Storage **E**xplorer — same story here. We use title case sometimes and sentence case others. We should use title case as this is a product feature. 3. Various text enhancements and changes.

Updates docs for storage explorer. Closes elastic#2960 Closes elastic/kibana#151302 Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

## Summary We need a way to decode Android crash's stacktraces so that they can provide meaningful insights to our customers, this is because, due to security reasons, android apps tend to obfuscate their code before publishing it online, making crash reports contain obfuscated names, which don't make any sense before mapping them to the actual source code names. In order to help our customers deobfuscate their stacktraces, we need to allow them to provide us with an R8 map file, which is generated by the code obfuscation tool (R8) at compile time. This map file is needed to later do the deobfuscation process. So these code changes take care of adding a new endpoint that our customers can use to upload their map files, similarly to what's currently available to [RUM Sourcemaps](https://www.elastic.co/guide/en/apm/guide/current/source-map-how-to.html#source-map-rum-upload), the Android map files will be uploaded to ES, using the same index as the one currently used to store RUM Sourcemaps. There's a couple of reasons why a new endpoint to upload android maps is needed instead of re-using the existing RUM Sourcemaps one: * The Sourcemaps upload endpoint has validations in place to check the sourcemap format, which must be a JSON with some expected keys available. Android map files don't have a JSON format, so they are rejected by the sourcemaps endpoint. * Android map files tend to be large in size, just as an example, the map file generated for our [sample app](https://github.com/elastic/opbeans-android) has a size of ~7 MB, so for real apps this number can be larger, which would also cause issues with the RUM upload endpoint since it has a max file limit size of 1 MB. * The RUM upload endpoint contains a parameter (`bundle_filepath `) that doesn't have an equivalent for the android map use case. This PR depends on elastic/kibana#161152 ### Checklist Delete any items that are not applicable to this PR. - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios ### For maintainers - [ ] This was checked for breaking API changes and was [labeled appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process) --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Søren Louv-Jansen <sorenlouv@gmail.com> Co-authored-by: Brandon Morelli <bmorelli25@gmail.com> Co-authored-by: Katerina Patticha <kate@kpatticha.com>

## Summary Closes elastic/kibana#165393 ### Checklist ### Risk Matrix ### For maintainers - [ ] This was checked for breaking API changes and was [labeled appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)

## Summary Closes elastic#3021.

@colleenmcginnis

Closes elastic#3292 ## Summary Updates documentation related to the APM UI based on issues found during the Observability docs bug bash last week. ### Checklist Delete any items that are not applicable to this PR. - [x] @colleenmcginnis [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials: - [x] Clarify that distributed traces aren't the only colorful traces in [Trace sample timeline](https://www.elastic.co/guide/en/kibana/current/spans.html#distributed-tracing) (elastic/kibana@b707c39) - [x] Clarify the implications of the traces table only showing root transactions in [Traces](https://www.elastic.co/guide/en/kibana/current/traces.html) (elastic/kibana@c1de678) - [x] Add beta admonition to APM [Infrastucture](https://www.elastic.co/guide/en/kibana/current/infrastructure.html) page (elastic/kibana@d3bc4a9) - [x] @bmorelli25 review

@colleenmcginnis

Closes elastic#3160 ## Summary Adds information on KQL filtering in APM rules. ### Checklist - [x] @colleenmcginnis initial draft - [x] @benakansara review * In what version was this initially added? 8.10.0? - [ ] @colleenmcginnis address feedback, merge

## Summary This PR adds back the `Errors` tab to mobile apm services under the title `Errors & Crashes`. This new page is split into too sections: errors, and crashes. Error Tab: <img width="1456" alt="Screenshot 2023-10-25 at 10 57 00" src="https://github.com/elastic/kibana/assets/75274611/20277c31-d88c-44ae-b896-1da4223cb392"> Crashes Tab: <img width="1454" alt="Screenshot 2023-10-25 at 10 57 35" src="https://github.com/elastic/kibana/assets/75274611/2b0dea23-cbab-4e68-a14a-c3b14d4bd860"> ### Checklist Delete any items that are not applicable to this PR. - [x] Any text added follows [EUI's writing guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses sentence case text and includes [i18n support](https://github.com/elastic/kibana/blob/main/packages/kbn-i18n/README.md) - [x] [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios - [x] Any UI touched in this PR is usable by keyboard only (learn more about [keyboard accessibility](https://webaim.org/techniques/keyboard/)) - [x] Any UI touched in this PR does not create any new axe failures (run axe in browser: [FF](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/), [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US)) - [x] If a plugin configuration key changed, check if it needs to be allowlisted in the cloud and added to the [docker list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker) - [x] This renders correctly on smaller devices using a responsive layout. (You can test this [in your browser](https://www.browserstack.com/guide/responsive-testing-on-local-server)) - [x] This was checked for [cross-browser compatibility](https://www.elastic.co/support/matrix#matrix_browsers) ### Risk Matrix Delete this section if it is not applicable to this PR. Before closing this PR, invite QA, stakeholders, and other developers to identify risks that should be tested prior to the change/feature release. When forming the risk matrix, consider some of the following examples and how they may potentially impact the change: ### For maintainers - [ ] This was checked for breaking API changes and was [labeled appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process) --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Katerina <kate@kpatticha.com>

Part of elastic#3354 (comment) ## Summary `bundle_filepath` should not contain `.map`.

… (#175636) ## Summary Adds fixes that have already been made in the serverless docs. Closes elastic/staging-serverless-observability-docs#181 ### Checklist n/a Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

…vability-docs into moved-content # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.

cla-checker-service · 2024-04-03T19:22:57Z

❌ Author of the following commits did not sign a Contributor Agreement:
82e6850, 8360bcf, , , ,

Please, read and sign the above mentioned agreement if you want to contribute to this project

github-actions · 2024-04-03T19:23:04Z

A documentation preview will be available soon.

🔨 Buildkite builds
📚 HTML diff
📙 Preview page

Request a new doc build by commenting

Rebuild this PR: run docs-build
Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

mdbirnstiehl

I had a few comments. The APM UI is very complicated so it's kind of difficult to organize. Not sure if everything I commented is helpful, but I am open to any brainstorming on organizing this content that might come from this.

mdbirnstiehl · 2024-04-24T20:53:42Z

docs/en/observability/apm-ui/filters.asciidoc

+of information, see <<advanced-queries,Query your data>>.
+=====
+
+[[global-time-range]]


Global time range and Service environment filter are appearing on their own pages. Probably need a [float].

Suggested change

[[global-time-range]]

[float]

[[global-time-range]]

mdbirnstiehl · 2024-04-24T20:54:00Z

docs/en/observability/apm-ui/filters.asciidoc

+
+The global time range filter in {kib} restricts APM data to a specific time period.
+
+[[environment-selector]]


Suggested change

[[environment-selector]]

[float]

[[environment-selector]]

mdbirnstiehl · 2024-04-24T21:23:09Z

docs/en/observability/apm/how-to.asciidoc

@@ -1,17 +1,47 @@
 [[apm-how-to-guides]]
-== How-to guides
+== APM UI guides


I'm not sure if APM UI guides is really intuitive. I would probably expect to find guides that tell me about elements in the UI. Maybe something like APM in-app guides or APM Kibana guides?

mdbirnstiehl · 2024-04-24T21:32:26Z

docs/en/observability/apm-ui/mobile-session-explorer.asciidoc

@@ -0,0 +1,39 @@
+[[mobile-session-explorer]]
+=== Exploring mobile sessions with Discover


Suggested change

=== Exploring mobile sessions with Discover

=== Explore mobile sessions with Discover

mdbirnstiehl · 2024-04-24T21:33:31Z

docs/en/observability/apm-ui/mobile-session-explorer.asciidoc

+This allows for the recall of the activities of a specific user during a specific period of time. The best way recall
+these data points is using {kibana-ref}/document-explorer.html[Discover]. This guide will explain how to do that.
+
+=== Viewing sessions with Discover


This is showing as a new page.

mdbirnstiehl · 2024-04-24T21:48:56Z

docs/en/observability/apm-ui/transactions.asciidoc

+[role="screenshot"]
+image::./images/apm-transactions-overview.png[Example view of response time distribution]
+
+[[transaction-duration-distribution]]


I think you want this on the same page as the other transactions. It's currently on it's on page, not sure if it should be or not. I also see it's an element in both Trace samples and Correlations, so maybe that's why these pages are on their own.

mdbirnstiehl · 2024-04-24T21:54:34Z

docs/en/observability/apm-ui/transactions.asciidoc

+
+Click and drag to select a latency duration _bucket_ to display up to 500 trace samples.
+
+[[transaction-trace-sample]]


Do you want this on the same page with the other transactions?

mdbirnstiehl · 2024-04-24T21:55:06Z

docs/en/observability/apm-ui/transactions.asciidoc

+[role="screenshot"]
+image::./images/apm-logs-tab.png[APM logs tab]
+
+[[transaction-latency-correlations]]


Do you want this on the same page with the other transactions?

mdbirnstiehl · 2024-04-24T22:19:57Z

docs/en/observability/apm-ui/spans.asciidoc

@@ -0,0 +1,72 @@
+[[spans]]
+=== Trace sample timeline


Is this section kind of redundant with the Trace sample timeline section on the Trace samples page? There's definitely a lot more info here, not sure if this info would be to much to move into the Trace samples page. If we want to keep a separate page, should it be under Transactions, unless this element exists somewhere outside of the individual transactions pages.

mdbirnstiehl · 2024-04-24T22:32:45Z

docs/en/observability/apm-ui/index.asciidoc

@@ -0,0 +1,74 @@
+[[xpack-apm]]
+= Navigate the APM UI


This section is kind of a beast, but I'm not really sure how I would organize it differently. Seems like you have your top 3 in the Kibana UI with Services, Traces, Dependencies, but most of the headings are service-specific? I wonder if it would make sense to organize the things that are service specific under the services heading to make the initial list under Navigate the APM UI less daunting?

lcawl and others added 30 commits May 29, 2018 13:48

[DOCS] Moves apm folder to docs (#19518)

2d74249

[DOCS] Updating APM UI documentation (#19946)

4730332

Adding new documentation about the APM UI and definitions of terminology and more. * Images added to docs * Adding Using APM UI page contents * Including new APM UI page * Updated Watcher copy * Copy feedback from @gchaps

[DOCS] APM UI docs for ML and query bar features (#21727)

19cbfe7

Adding content for Machine Learning integration and query bar UI in the Using the APM UI docs.

[docs] Import APM dashboards in 6.4+ (#22439)

4952c04

[Docs] Remove beta notes for ML and Query bar (#24718)

46b2434

[DOCS] Updates X-Pack terminology (#28208)

e14e432

[APM][Docs] Update documentation for 7.0 (#31940)

952a356

[APM][Docs] 7.2 documentation updates (#38577)

2105f91

docs: add nodejs apm environment link (#40199)

6770c9b

[docs][APM] Agent config docs (#40084)

bf2bcd5

[docs][APM] Breakdown graph and screenshots (#41175)

978bde8

docs: lowercase app (#41612)

6275b29

docs: add tip on agent config in a dt (#43301)

2066908

[docs][APM] Update APM screenshots (#46235)

6258278

[docs] APM troubleshooting section (#47073)

204abea

[APM][docs] Updates to documentation for 7.5 (#50988)

b2e88be

docs: unknown route (#52703)

33abd98

[docs][APM] Add APM settings page (#53172)

8024c4b

[docs][APM] Clarify advanced queries (#53034)

319fced

[docs][APM] Add runtime index config documentation (#53907)

6f3885e

[APM][docs] Add troubleshooting for non-indexed fields (#54948)

8735bce

[APM][docs] 7.6 documentation updates (#57124)

3536d00

docs: feedback from @sqren (#57405)

c417ea8

[APM] Stabilize agent configuration API (#57767)

3f5ee8b

[DOCS] Removed spatial references (#59595)

9aed48a

* [DOCS] Removed ss above spatial references * Removed above from n numeral formatting page

[DOCS] Changed Discover app to Discover (#59769)

758be57

[DOCS] Removed below references (#60159)

912ce8d

docs: [APM] custom links (#60595)

0ffe854

docs: updates to apm agent config (#61893)

9386e48

bmorelli25 and others added 12 commits July 7, 2023 07:41

[APM] Update Storage Explorer docs (#162163)

22a6f0c

Updates docs for storage explorer. Closes elastic#2960 Closes elastic/kibana#151302 Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

[docs] Explain max payload size in RUM source map docs (#165732)

dc61cbc

## Summary Closes elastic#3021.

[Docs] remove .map from bundle_filepath value (#174834)

971394e

Part of elastic#3354 (comment) ## Summary `bundle_filepath` should not contain `.map`.

move to apm-ui dir

89628cc

bmorelli25 self-assigned this Apr 3, 2024

mergify bot added the backport-skip Skip notification from the automated backport with mergify label Apr 3, 2024

bmorelli25 mentioned this pull request Apr 3, 2024

Remove APM documentation from Kibana repo and Guide elastic/kibana#179981

Draft

bmorelli25 added 4 commits April 3, 2024 15:02

fix build

1004545

fix

f351500

fix for the fix

976e920

remove xpack, clean up settings

cb288df

bmorelli25 added backport-8.13 Automated backport with mergify and removed backport-skip Skip notification from the automated backport with mergify labels Apr 4, 2024

elastic deleted a comment from mergify bot Apr 4, 2024

bmorelli25 added the backport-8.14 Automated backport with mergify label Apr 18, 2024

bmorelli25 added 2 commits April 24, 2024 12:36

update nav

ed0f576

rearrange how-to section

606a852

bmorelli25 marked this pull request as ready for review April 24, 2024 19:58

bmorelli25 requested a review from a team as a code owner April 24, 2024 19:58

mdbirnstiehl reviewed Apr 24, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move APM UI documentation to observability-docs with history #3723

Move APM UI documentation to observability-docs with history #3723

bmorelli25 commented Apr 3, 2024 •

edited

cla-checker-service bot commented Apr 3, 2024

github-actions bot commented Apr 3, 2024

mdbirnstiehl left a comment

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024

mdbirnstiehl Apr 24, 2024


		The global time range filter in {kib} restricts APM data to a specific time period.

		[[environment-selector]]

		@@ -0,0 +1,39 @@
		[[mobile-session-explorer]]
		=== Exploring mobile sessions with Discover

	=== Exploring mobile sessions with Discover
	=== Explore mobile sessions with Discover


		Click and drag to select a latency duration _bucket_ to display up to 500 trace samples.

		[[transaction-trace-sample]]

Move APM UI documentation to observability-docs with history #3723

Are you sure you want to change the base?

Move APM UI documentation to observability-docs with history #3723

Conversation

bmorelli25 commented Apr 3, 2024 • edited

Summary

Potential future improvements

cla-checker-service bot commented Apr 3, 2024

github-actions bot commented Apr 3, 2024

mdbirnstiehl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bmorelli25 commented Apr 3, 2024 •

edited