docs: APM 7.11 updates (#87072) (#87374)

docs/apm/deployment-annotations.asciidoc

@@ -6,6 +6,9 @@
 <titleabbrev>Track deployments with annotations</titleabbrev>
 ++++
 
+[role="screenshot"]
+image::apm/images/apm-transaction-annotation.png[Example view of transactions annotation in the APM app in Kibana]
+
 For enhanced visibility into your deployments, we offer deployment annotations on all transaction charts.
 This feature enables you to easily determine if your deployment has increased response times for an end-user,
 or if the memory/CPU footprint of your application has changed.
@@ -43,6 +46,3 @@ See the <<apm-annotation-api,annotation API>> reference for more information.
 
 
 NOTE: If custom annotations have been created for the selected time period, any derived annotations, i.e., those created automatically when `service.version` changes, will not be shown.
-
-[role="screenshot"]
-image::apm/images/apm-transaction-annotation.png[Example view of transactions annotation in the APM app in Kibana]

docs/apm/errors.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[errors]]
-=== Errors overview
+=== Errors
 
 TIP: {apm-overview-ref-v}/errors.html[Errors] are groups of exceptions with a similar exception or log message.
 

docs/apm/getting-started.asciidoc

@@ -6,26 +6,20 @@
 <titleabbrev>Get started</titleabbrev>
 ++++
 
-Elastic APM captures different types of information from within instrumented applications:
-
-* *Spans* contain information about the execution of a specific code path.
-They measure from the start to end of an activity,
-and they can have a parent/child relationship with other spans.
-* *Transactions* are a special kind of span;
-they are the first span for a particular service and have extra metadata associated with them.
-As an example, a transaction could be a request to your server, a batch job, or a custom transaction type.
-*Traces* link together related transactions to show an end-to-end performance of how a request was served and which services were part of it.
-* *Errors* contain information about the original exception that occurred or about a log created when the exception occurred.
-
-Curated charts and tables display the different types of APM data, which allows you to compare and debug your applications easily.
+For a quick, high-level overview of the health and performance of your application,
+start with:
 
 * <<services>>
 * <<traces>>
+* <<service-maps>>
+
+Notice something awry? Select a service or trace and dive deeper with:
+
+* <<service-overview>>
 * <<transactions>>
 * <<spans>>
 * <<errors>>
 * <<metrics>>
-* <<service-maps>>
 
 TIP: Want to learn more about the Elastic APM ecosystem?
 See the {apm-overview-ref-v}/overview.html[APM Overview].
@@ -34,6 +28,10 @@ include::services.asciidoc[]
 
 include::traces.asciidoc[]
 
+include::service-maps.asciidoc[]
+
+include::service-overview.asciidoc[]
+
 include::transactions.asciidoc[]
 
 include::spans.asciidoc[]
@@ -41,5 +39,3 @@ include::spans.asciidoc[]
 include::errors.asciidoc[]
 
 include::metrics.asciidoc[]
-
-include::service-maps.asciidoc[]

docs/apm/metrics.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[metrics]]
-=== Metrics overview
+=== Metrics
 
 The *Metrics* overview provides agent-specific metrics,
 which lets you perform more in-depth root cause analysis investigations within the APM app.

docs/apm/service-maps.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [[service-maps]]
-=== Service maps
+=== Service map
 
 A service map is a real-time visual representation of the instrumented services in your application's architecture.
 It shows you how these services are connected, along with high-level metrics like average transaction duration,
 requests per minute, and errors per minute.
 If enabled, service maps also integrate with machine learning--for real time health indicators based on anomaly detection scores.
-All of these features can help you to quickly and visually assess the status and health of your services.
+All of these features can help you quickly and visually assess your services' status and health.
 
 We currently surface two types of service maps:
 

docs/apm/service-overview.asciidoc

@@ -0,0 +1,5 @@
+[role="xpack"]
+[[service-overview]]
+=== Service overview
+
+Selecting a <<services,*service*>> brings you to the *Service overview*.

docs/apm/services.asciidoc

@@ -1,14 +1,14 @@
 [role="xpack"]
 [[services]]
-=== Services overview
+=== Services
 
-The *Services* overview page provides a quick, high-level overview of the health and general
+*Service* inventory provides a quick, high-level overview of the health and general
 performance of all instrumented services.
 
 To help surface potential issues, services are sorted by their health status:
 **critical** > **warning** > **healthy** > **unknown**.
-Health status is powered by machine learning and requires anomaly detection to be enabled.
-Learn more in <<machine-learning-integration,machine learning>>.
+Health status is powered by <<machine-learning-integration,machine learning>>
+and requires anomaly detection to be enabled.
 
 [role="screenshot"]
 image::apm/images/apm-services-overview.png[Example view of services table the APM app in Kibana]

docs/apm/traces.asciidoc

@@ -1,20 +1,21 @@
 [role="xpack"]
 [[traces]]
-=== Traces overview
+=== Traces
 
 TIP: Traces link together related transactions to show an end-to-end performance of how a request was served
 and which services were part of it.
 In addition to the Traces overview, you can view your application traces in the <<spans,trace sample timeline waterfall>>.
 
-The *Traces* overview displays the entry transaction for all traces in your application.
+*Traces* displays your application's entry transactions.
+Transactions with the same name are grouped together and only shown once in this table.
 If you're using <<distributed-tracing,distributed tracing>>,
 this view is key to finding the critical paths within your application.
-Transactions with the same name are grouped together and only shown once in this table.
 
 By default, transactions are sorted by _Impact_.
-Impact helps show the most used and slowest endpoints in your service--in other words,
+Impact helps show the most used and slowest endpoints in your service -- in other words,
 it's the collective amount of pain a specific endpoint is causing your users.
-If there's a particular endpoint you're worried about, you can click on it to view the <<transaction-details, transaction details>>.
+If there's a particular endpoint you're worried about, select it to view its
+<<transaction-details,transaction details>>.
 
 [role="screenshot"]
 image::apm/images/apm-traces.png[Example view of the Traces overview in APM app in Kibana]

docs/apm/transactions.asciidoc

@@ -1,20 +1,18 @@
 [role="xpack"]
 [[transactions]]
-=== Transaction overview
+=== Transactions
 
 TIP: A {apm-overview-ref-v}/transactions.html[transaction] describes an event captured by an Elastic APM agent instrumenting a service.
 APM agents automatically collect performance metrics on HTTP requests, database queries, and much more.
 
-Selecting a <<services,*service*>> brings you to the *transactions* overview.
-
 [role="screenshot"]
 image::apm/images/apm-transactions-overview.png[Example view of transactions table in the APM app in Kibana]
 
-The *transaction duration*, *transactions per minute*, *transaction error rate*, and *time spent by span type*
+The *Latency*, *transactions per minute*, *Error rate*, and *Average duration by span type*
 charts display information on all transactions associated with the selected service:
 
-*Transaction duration*::
-Response times for this service, broken down into average, 95th, and 99th percentile.
+*Latency*::
+Response times for the service. Options include average, 95th, and 99th percentile.
 If there's a weird spike that you'd like to investigate,
 you can simply zoom in on the graph - this will adjust the specific time range,
 and all of the data on the page will update accordingly.
@@ -24,12 +22,12 @@ Visualize response codes: `2xx`, `3xx`, `4xx`, etc.,
 and is useful for determining if you're serving more of one code than you typically do.
 Like in the Transaction duration graph, you can zoom in on anomalies to further investigate them.
 
-*Transaction error rate*::
+*Error rate*::
 Visualize the total number of transactions with errors divided by the total number of transactions.
 Any unexpected increases, decreases, or irregular patterns can be investigated further
 with the <<errors,errors overview>>.
 
-*Time spent by span type*::
+*Average duration by span type*::
 Visualize where your application is spending most of its time.
 For example, is your app spending time in external calls, database processing, or application code execution?
 +
@@ -39,8 +37,9 @@ This could be a sign that the agent does not have auto-instrumentation for whate
 +
 It's important to note that if you have asynchronous spans, the sum of all span times may exceed the duration of the transaction.
 
+[discrete]
 [[transactions-table]]
-==== Transactions table
+=== Transactions table
 
 The *Transactions* table displays a list of _transaction groups_ for the selected service.
 In other words, this view groups all transactions of the same name together,
@@ -63,8 +62,9 @@ For further details, including troubleshooting and custom implementation instruc
 refer to the documentation for each {apm-agents-ref}[APM Agent] you've implemented.
 ====
 
+[discrete]
 [[rum-transaction-overview]]
-==== RUM Transaction overview
+=== RUM Transaction overview
 
 The transaction overview page is customized for the JavaScript RUM Agent.
 Specifically, the page highlights *page load times* for your service:
@@ -77,8 +77,9 @@ are available in the Observability User Experience tab.
 // To do
 // Add link to the Observability UE docs when complete
 
+[discrete]
 [[transaction-details]]
-==== Transaction details
+=== Transaction details
 
 Selecting a transaction group will bring you to the *transaction* details.
 This page is visually similar to the transaction overview, but it shows data from all transactions within
@@ -87,20 +88,32 @@ the selected transaction group.
 [role="screenshot"]
 image::apm/images/apm-transaction-response-dist.png[Example view of response time distribution]
 
-Up to ten sampled transactions are also displayed.
-These sampled transactions are based on the _bucket_ selection in the *Transactions duration distribution* chart.
-You can update the sampled transactions by selecting a new _bucket_.
-The number of requests per bucket is displayed when hovering over the graph,
-and the selected bucket is highlighted to stand out.
+[[transaction-duration-distribution]]
+==== Transactions duration distribution
 
-The screenshot below shows a typical distribution, and indicates most of our requests were served quickly--awesome!
+This chart plots all transaction durations for the given time period.
+The screenshot below shows a typical distribution,
+and indicates most of our requests were served quickly -- awesome!
 It's the requests on the right, the ones taking longer than average, that we probably want to focus on.
 
 [role="screenshot"]
 image::apm/images/apm-transaction-duration-dist.png[Example view of transactions duration distribution graph]
 
-When you select a bucket,
-you're presented with up to ten trace samples.
+Select a transaction duration _bucket_ to display up to ten trace samples.
+
+[[transaction-trace-sample]]
+==== Trace sample
+
+Trace samples are based on the _bucket_ selection in the *Transactions duration distribution* chart;
+update the samples by selecting a new _bucket_.
+The number of requests per bucket is displayed when hovering over the graph,
+and the selected bucket is highlighted to stand out.
+
+Each bucket presents up to ten trace samples in a *timeline*, trace sample *metadata*,
+and any related *logs*.
+
+*Trace sample timeline*
+
 Each sample has a trace timeline waterfall that shows how a typical request in that bucket executed.
 This waterfall is useful for understanding the parent/child hierarchy of transactions and spans,
 and ultimately determining _why_ a request was slow.
@@ -112,7 +125,9 @@ image::apm/images/apm-transaction-sample.png[Example view of transactions sample
 
 NOTE: More information on timeline waterfalls is available in <<spans, spans>>.
 
-For a particular transaction sample, we can get even more information in the *metadata* tab:
+*Trace sample metadata*
+
+Learn more about a trace sample in the *Metadata* tab:
 
 * Labels - Custom labels added by agents
 * HTTP request/response information
@@ -123,7 +138,22 @@ For a particular transaction sample, we can get even more information in the *me
 * Agent information
 * URL
 * User - Requires additional configuration, but allows you to see which user experienced the current transaction.
-* Custom - You can configure your agent to add custom contextual information on transactions.
 
 TIP: All of this data is stored in documents in Elasticsearch.
 This means you can select "Actions - View sample document" to see the actual Elasticsearch document under the discover tab.
+
+*Trace sample logs*
+
+The *Logs* tab displays logs related to the sampled trace.
+
+Logs provide detailed information about specific events,
+and are crucial to successfully debugging slow or erroneous transactions.
+
+If you've correlated your application's logs and traces, you never have to search for relevant data;
+it's all provided on this. Viewing log and trace data together allows you to quickly diagnose
+and solve problems.
+
+[role="screenshot"]
+image::apm/images/apm-logs-tab.png[APM logs tab]
+
+// To do: link to log correlation