[apm] Clarify how data is populated in the APM Infrastructure tab (#4692

) (#4807) * first draft * remove code comments * remove code comment (cherry picked from commit 6a482ac) Co-authored-by: Colleen McGinnis <[email protected]>
elastic · Jan 29, 2025 · 5581a31 · 5581a31
1 parent 12568fa
commit 5581a31
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 3 deletions.
diff --git a/docs/en/observability/apm/troubleshooting/common-problems.asciidoc b/docs/en/observability/apm/troubleshooting/common-problems.asciidoc
@@ -17,6 +17,7 @@ This section describes common problems you might encounter when using APM Server
 * <<troubleshooting-unknown-route>>
 * <<troubleshooting-fields-unsearchable>>
 * <<service-map-rum-connections>>
+* <<troubleshooting-apm-infra-data>>
 
 [float]
 [[apm-no-data-indexed]]
@@ -282,10 +283,35 @@ If the service map is not showing an expected connection between the client and
 it's likely because you haven't configured
 {apm-rum-ref}/distributed-tracing-guide.html[`distributedTracingOrigins`].
 
-
 This setting is necessary, for example, for cross-origin requests.
 If you have a basic web application that provides data via an API on `localhost:4000`,
 and serves HTML from `localhost:4001`, you'd need to set `distributedTracingOrigins: ['https://localhost:4000']`
 to ensure the origin is monitored as a part of distributed tracing.
 In other words, `distributedTracingOrigins` is consulted prior to the APM agent adding the
 distributed tracing `traceparent` header to each request.
+
+[float]
+[[troubleshooting-apm-infra-data]]
+== No data shown in the infrastructure tab
+
+If you don't see any data in the *Infrastructure* tab for a selected service in the Applications UI,
+there are a few possible causes and solutions.
+
+*If you also do _not_ see the data in the* <<view-infrastructure-metrics,*Infrastructure inventory*>>
+
+Refer to the <<troubleshooting-infrastructure-monitoring,Infrastructure troubleshooting docs>>.
+
+*If you _do_ see the data in the* <<view-infrastructure-metrics,*Infrastructure inventory*>>
+
+// Why this happens
+It's likely that there is a problem correlating APM and infrastructure data. The `host.hostname`
+field value in the APM data and the `host.name` field value in infrastructure data are used to
+correlate data, and the queries used to correlate the data are case sensitive.
+
+// Potential fix
+To fix this, make sure these two fields match exactly.
+
+For example, if the APM agent is not configured to use the correct host name,
+the host name might be set to the container name or the Kubernetes pod name.
+To get the correct host name, you need to set some additional configuration options,
+specifically `system.kubernetes.node.name` as described in <<apm-api-kubernetes-data>>.
diff --git a/docs/en/observability/apm/view-and-analyze/drill-down/infrastructure.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/infrastructure.asciidoc
@@ -4,11 +4,27 @@
 beta::[]
 
 The *Infrastructure* tab provides information about the containers, pods, and hosts
-that the selected service is linked to.
+that the selected service is linked to:
+
+* *Pods*: Uses the `kubernetes.pod.name` from the <<apm-data-model-metrics,APM metrics data streams>>.
+* *Containers*: Uses the `container.id` from the <<apm-data-model-metrics,APM metrics data streams>>.
+* *Hosts*: If the application is containerized--if the APM metrics documents include `container.id`--
+the `host.name` is used from the infrastructure data streams (filtered by `container.id`).
+If not, `host.hostname` is used from the APM metrics data streams.
 
 [role="screenshot"]
 image::./images/infra.png[Example view of the Infrastructure tab in Applications UI in Kibana]
 
 IT ops and software reliability engineers (SREs) can use this tab
 to quickly find a service's underlying infrastructure resources when debugging a problem.
-Knowing what infrastructure is related to a service allows you to remediate issues by restarting, killing hanging instances, changing configuration, rolling back deployments, scaling up, scaling out, and so on.
+Knowing what infrastructure is related to a service allows you to remediate issues by restarting, killing hanging instances, changing configuration, rolling back deployments, scaling up, scaling out, and so on.
+
+// Link to troubleshooting so we can keep
+// troubleshooting content centralized
+[TIP]
+.Why is the infrastructure tab empty?
+====
+If there is no data in the Application UI's infrastructure tab for a selected service,
+you can read more about why this happens and how to fix it in the
+<<troubleshooting-apm-infra-data,troubleshooting docs>>.
+====