[7.x] [docs] APM troubleshooting section (#47073) (#52348)

docs/apm/index.asciidoc

@@ -1,3 +1,9 @@
+// APM Server does not build a `7.x` branch.
+// This check changes `7.x` links to `master` instaed
+ifeval::[{branch} == 7.x]
+:apm-server-ref:       https://www.elastic.co/guide/en/apm/server/master
+endif::[]
+
 [role="xpack"]
 [[xpack-apm]]
 = APM

docs/apm/troubleshooting.asciidoc

@@ -0,0 +1,63 @@
+[[troubleshooting]] 
+=== Troubleshooting common problems
+
+If you have something to add to this section, please consider creating a pull request with
+your proposed changes in the https://github.com/elastic/kibana[Kibana repository].
+
+Also check out the https://discuss.elastic.co/c/apm[APM discussion forum].
+
+==== No APM data found
+
+This section can help with any of the following:
+
+* Data isn't displaying in the APM app
+* You're seeing a message like "No Services Found",
+* You're seeing errors like "Fielddata is disabled on text fields by default..."
+
+There are a number of factors that could be at play here.
+One important thing to double-check first is your index template.
+
+An APM index template must exist for the APM app to work correctly.
+By default, this index template is created by APM Server on startup.
+However, this only happens if `setup.template.enabled` is `true` in `apm-server.yml`.
+You can create the index template manually by running `apm-server setup`.
+Take note that index templates *cannot* be applied retroactively -- they are only applied at index creation time.
+More information is available in {apm-server-ref}/apm-server-configuration.html[Set up and configure].
+
+You can check for the existence of an APM index template using the
+{ref}/indices-get-template.html[Get index template API].
+If you're using the default index naming pattern, that request would be:
+
+[source,js]
+--------------------------------------------------
+GET /_template/apm-{version}
+--------------------------------------------------
+// CONSOLE
+
+If you're not outputting data directly from APM Server to Elasticsearch (perhaps you're using Logstash or Kafka),
+then the index template will not be set up automatically. Instead, you'll need to
+{apm-server-ref}/_manually_loading_template_configuration.html#load-template-manually-alternate[load the template manually].
+
+Finally, this problem can also occur if you've changed the index name that you write APM data to.
+The default index pattern can be found {apm-server-ref}/elasticsearch-output.html#index-option-es[here].
+If you change this setting, you must also configure the `setup.template.name` and `setup.template.pattern` options.
+See {apm-server-ref}/configuration-template.html[Load the Elasticsearch index template].
+
+==== Unknown route
+
+The {apm-app-ref}/transactions.html[transaction overview] will only display helpful information
+when the transactions in your services are named correctly.
+If you're seeing "GET unknown route" or "unknown route" in the APM app,
+it could be a sign that something isn't working like it should.
+
+Elastic APM Agents come with built-in support for popular frameworks out-of-the-box.
+This means, among other things, that the Agent will try to automatically name HTTP requests.
+As an example, the Node.js Agent uses the route that handled the request, while the Java Agent uses the Servlet name.
+
+"Unknown route" indicates that the Agent can't determine what to name the request,
+perhaps because the technology you're using isn't supported, the Agent has been installed incorrectly,
+or because something is happening to the request that the Agent doesn't understand.
+
+To resolve this, you'll need to head over to the relevant {apm-agents-ref}[Agent documentation].
+Specifically, view the Agent's supported technologies page.
+You can also use the Agent's public API to manually set a name for the transaction.

docs/apm/using-the-apm-ui.asciidoc

@@ -35,3 +35,5 @@ include::metrics.asciidoc[]
 include::agent-configuration.asciidoc[]
 
 include::advanced-queries.asciidoc[]
+
+include::troubleshooting.asciidoc[]