diff --git a/docs/apm/deployment-annotations.asciidoc b/docs/apm/deployment-annotations.asciidoc
index 53fd963a81f7..8add9c58a4ca 100644
--- a/docs/apm/deployment-annotations.asciidoc
+++ b/docs/apm/deployment-annotations.asciidoc
@@ -6,6 +6,9 @@
Track deployments with annotations
++++
+[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 <> 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]
diff --git a/docs/apm/errors.asciidoc b/docs/apm/errors.asciidoc
index 49351ec25585..c468d7f0235b 100644
--- a/docs/apm/errors.asciidoc
+++ b/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.
diff --git a/docs/apm/getting-started.asciidoc b/docs/apm/getting-started.asciidoc
index 48c35ad21edf..1d77dbb405fe 100644
--- a/docs/apm/getting-started.asciidoc
+++ b/docs/apm/getting-started.asciidoc
@@ -6,26 +6,20 @@
Get started
++++
-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:
* <>
* <>
+* <>
+
+Notice something awry? Select a service or trace and dive deeper with:
+
+* <>
* <>
* <>
* <>
* <>
-* <>
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[]
diff --git a/docs/apm/images/apm-agent-configuration.png b/docs/apm/images/apm-agent-configuration.png
index 05518cb924d1..07398f060918 100644
Binary files a/docs/apm/images/apm-agent-configuration.png and b/docs/apm/images/apm-agent-configuration.png differ
diff --git a/docs/apm/images/apm-alert.png b/docs/apm/images/apm-alert.png
index c68b36f522bf..2ac91b6b1921 100644
Binary files a/docs/apm/images/apm-alert.png and b/docs/apm/images/apm-alert.png differ
diff --git a/docs/apm/images/apm-errors-overview.png b/docs/apm/images/apm-errors-overview.png
index 969a1f19f9f4..5b3b00a3b1ef 100644
Binary files a/docs/apm/images/apm-errors-overview.png and b/docs/apm/images/apm-errors-overview.png differ
diff --git a/docs/apm/images/apm-geo-ui.png b/docs/apm/images/apm-geo-ui.png
index 3757127bad9c..5bbe713c908a 100644
Binary files a/docs/apm/images/apm-geo-ui.png and b/docs/apm/images/apm-geo-ui.png differ
diff --git a/docs/apm/images/apm-logs-tab.png b/docs/apm/images/apm-logs-tab.png
new file mode 100644
index 000000000000..77aecf744bc7
Binary files /dev/null and b/docs/apm/images/apm-logs-tab.png differ
diff --git a/docs/apm/images/apm-metrics.png b/docs/apm/images/apm-metrics.png
index ffe5ffc7e1d8..af083b5ba3c0 100644
Binary files a/docs/apm/images/apm-metrics.png and b/docs/apm/images/apm-metrics.png differ
diff --git a/docs/apm/images/apm-query-bar.png b/docs/apm/images/apm-query-bar.png
index 90955fb61016..92398065c254 100644
Binary files a/docs/apm/images/apm-query-bar.png and b/docs/apm/images/apm-query-bar.png differ
diff --git a/docs/apm/images/apm-services-overview.png b/docs/apm/images/apm-services-overview.png
index 85d14cc7dfc6..85b441d47f0c 100644
Binary files a/docs/apm/images/apm-services-overview.png and b/docs/apm/images/apm-services-overview.png differ
diff --git a/docs/apm/images/apm-settings.png b/docs/apm/images/apm-settings.png
index 14cf32877b72..c821b7fb76e7 100644
Binary files a/docs/apm/images/apm-settings.png and b/docs/apm/images/apm-settings.png differ
diff --git a/docs/apm/images/apm-setup.png b/docs/apm/images/apm-setup.png
index 3f5f7761427d..3410ebf69d84 100644
Binary files a/docs/apm/images/apm-setup.png and b/docs/apm/images/apm-setup.png differ
diff --git a/docs/apm/images/apm-traces.png b/docs/apm/images/apm-traces.png
index bf1f7e783bb1..97e801606c61 100644
Binary files a/docs/apm/images/apm-traces.png and b/docs/apm/images/apm-traces.png differ
diff --git a/docs/apm/images/apm-transaction-annotation.png b/docs/apm/images/apm-transaction-annotation.png
index 8913770517ff..b9360db2ff47 100644
Binary files a/docs/apm/images/apm-transaction-annotation.png and b/docs/apm/images/apm-transaction-annotation.png differ
diff --git a/docs/apm/images/apm-transaction-response-dist.png b/docs/apm/images/apm-transaction-response-dist.png
index 1d268bbaac46..2f3e69f263a2 100644
Binary files a/docs/apm/images/apm-transaction-response-dist.png and b/docs/apm/images/apm-transaction-response-dist.png differ
diff --git a/docs/apm/images/apm-transaction-sample.png b/docs/apm/images/apm-transaction-sample.png
index bfdb6a5abe65..0e4bc5f3f878 100644
Binary files a/docs/apm/images/apm-transaction-sample.png and b/docs/apm/images/apm-transaction-sample.png differ
diff --git a/docs/apm/images/apm-transactions-overview.png b/docs/apm/images/apm-transactions-overview.png
index 53d7637b1864..80fca19ff96c 100644
Binary files a/docs/apm/images/apm-transactions-overview.png and b/docs/apm/images/apm-transactions-overview.png differ
diff --git a/docs/apm/images/global-filters.png b/docs/apm/images/global-filters.png
index 034828148c22..70ae50aea605 100644
Binary files a/docs/apm/images/global-filters.png and b/docs/apm/images/global-filters.png differ
diff --git a/docs/apm/images/jvm-metrics-overview.png b/docs/apm/images/jvm-metrics-overview.png
index 586836c6cfe3..4b882574e2b9 100644
Binary files a/docs/apm/images/jvm-metrics-overview.png and b/docs/apm/images/jvm-metrics-overview.png differ
diff --git a/docs/apm/images/jvm-metrics.png b/docs/apm/images/jvm-metrics.png
index 52a1ca5bea8d..70f7965b72df 100644
Binary files a/docs/apm/images/jvm-metrics.png and b/docs/apm/images/jvm-metrics.png differ
diff --git a/docs/apm/images/local-filter.png b/docs/apm/images/local-filter.png
index 8657e39f430a..edcaf8b6a609 100644
Binary files a/docs/apm/images/local-filter.png and b/docs/apm/images/local-filter.png differ
diff --git a/docs/apm/images/service-maps-java.png b/docs/apm/images/service-maps-java.png
index b3726bdc00ab..d7c0786e406d 100644
Binary files a/docs/apm/images/service-maps-java.png and b/docs/apm/images/service-maps-java.png differ
diff --git a/docs/apm/images/service-maps.png b/docs/apm/images/service-maps.png
index 878a31adc69c..190b7af3c560 100644
Binary files a/docs/apm/images/service-maps.png and b/docs/apm/images/service-maps.png differ
diff --git a/docs/apm/metrics.asciidoc b/docs/apm/metrics.asciidoc
index e64cbc846960..8adcf315d33d 100644
--- a/docs/apm/metrics.asciidoc
+++ b/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.
diff --git a/docs/apm/service-maps.asciidoc b/docs/apm/service-maps.asciidoc
index d44c4ff6caa5..7cc4da8a1fc1 100644
--- a/docs/apm/service-maps.asciidoc
+++ b/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:
diff --git a/docs/apm/service-overview.asciidoc b/docs/apm/service-overview.asciidoc
new file mode 100644
index 000000000000..970d4c61ed92
--- /dev/null
+++ b/docs/apm/service-overview.asciidoc
@@ -0,0 +1,5 @@
+[role="xpack"]
+[[service-overview]]
+=== Service overview
+
+Selecting a <> brings you to the *Service overview*.
\ No newline at end of file
diff --git a/docs/apm/services.asciidoc b/docs/apm/services.asciidoc
index 2bf2e35c21cd..90ebff3d8ad7 100644
--- a/docs/apm/services.asciidoc
+++ b/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 <>.
+Health status is powered by <>
+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]
diff --git a/docs/apm/traces.asciidoc b/docs/apm/traces.asciidoc
index 3bafebd73315..904be1c8e769 100644
--- a/docs/apm/traces.asciidoc
+++ b/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 <>.
-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 <>,
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 <>.
+If there's a particular endpoint you're worried about, select it to view its
+<>.
[role="screenshot"]
image::apm/images/apm-traces.png[Example view of the Traces overview in APM app in Kibana]
diff --git a/docs/apm/transactions.asciidoc b/docs/apm/transactions.asciidoc
index fef98a86de1d..3f624980e393 100644
--- a/docs/apm/transactions.asciidoc
+++ b/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 <> 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 <>.
-*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 <>.
-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
\ No newline at end of file