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

docs/apm/advanced-queries.asciidoc

@@ -1,26 +1,18 @@
-[[query-bar]]
+[[advanced-queries]]
 === Advanced queries
 
-The query bar is a powerful data query feature.
-Similar to the query bar in {kibana-ref}/discover.html[Discover],
-it enables you to pass advanced queries on your data to filter on particular pieces of information that you're interested in.
-It comes with a handy autocomplete that helps find the fields and even provides suggestions to the data they include.
-You can select the query bar and hit the down arrow on your keyboard to begin seeing recommendations.
-
 When querying, you're simply searching and selecting data from fields in Elasticsearch documents.
 It may be helpful to view some of your documents in {kibana-ref}/discover.html[Discover] to better understand how APM data is stored in Elasticsearch. 
 
-The query bar is available in the Services, Transactions, Errors, Metrics, and Traces views,
-and any input will persist as you move between pages.
-
-TIP: Interactions with the query bar change the URL of the page you're on.
-This means you can simply copy and paste the URL of your page to share a specific query or view with others.
+Queries entered into the query bar are also added as parameters to the URL,
+so it's easy to share a specific query or view with others.
 
 In the screenshot below, you can begin to see some of the transaction fields available for filtering on:  
 
 [role="screenshot"]
 image::apm/images/apm-query-bar.png[Example of the Kibana Query bar in APM UI in Kibana]
 
+[float]
 ==== Example queries
 
 * Exclude response times slower than 2000 ms: `transaction.duration.us > 2000000`

docs/apm/filters.asciidoc

@@ -0,0 +1,50 @@
+[[filters]]
+=== Filters
+
+Global filters are ways you can filter your data within the APM UI.
+They are available in the Services, Transactions, Errors, Metrics, and Traces views,
+and any filter applied will persist as you move between pages.
+
+[role="screenshot"]
+image::apm/images/global-filters.png[Global filters available in the APM UI in Kibana]
+
+[float]
+==== Global time range
+
+The <<set-time-filter,global time range filter>> in {kib} restricts APM data to a specific time period.
+
+[float]
+[[query-bar]]
+==== Query bar
+
+The query bar is a powerful data query feature.
+Similar to the query bar in {kibana-ref}/discover.html[Discover],
+it enables you to pass advanced queries on your data to filter on particular pieces of information that you're interested in.
+It comes with a handy autocomplete that helps find the fields and even provides suggestions to the data they include.
+You can select the query bar and hit the down arrow on your keyboard to begin seeing recommendations.
+
+See <<query-bar,advanced queries>> for more information and sample queries.
+
+[float]
+[[environment-selector]]
+==== Service environment filter
+
+The environment selector is a global filter for `service.environment`.
+It allows you to view only relevant data, and is especially useful for separating development from production environments.
+By default, all environments are displayed. If there are no environment options, you'll see "not defined".
+
+Service environments are defined when configuring your APM agents.
+It's very important to be consistent when naming environments in your agents.
+See the documentation for each agent you're using to learn how to configure service environments:
+
+|===
+|*Environment configuration*
+v|*Go:* {apm-go-ref}/configuration.html#config-environment[`ELASTIC_APM_ENVIRONMENT`]
+*Java:* {apm-java-ref}/config-core.html#config-environment[`environment`]
+*Python:* {apm-py-ref}/configuration.html#config-environment[`environment`]
+*Ruby:* {apm-ruby-ref}/configuration.html#config-environment[`environment`]
+*Real User Monitoring:* {apm-rum-ref}/configuration.html#environment[`environment`]
+|===
+
+// Add to above table when docs are ready
+// *Node.js:* {apm-node-ref}/configuration.html#environment[`environment`]

docs/apm/metrics.asciidoc

@@ -1,7 +1,8 @@
 [[metrics]]
 === Metrics overview
 
-The *Metrics* overview shows a combination of transaction, error, CPU, and memory data.
+The *Metrics* overview provides agent-specific metrics,
+which lets you perform more in-depth root cause analysis investigations within the APM UI.
 
 If you're experiencing a problem with your service, you can use this page to attempt to find the underlying cause.
 For example, you might be able to correlate a high number of errors with a long transaction duration, high CPU usage, or a memory leak.   

docs/apm/services.asciidoc

@@ -2,7 +2,6 @@
 === Services overview
 
 The *Services* overview gives you quick insights into the health and general performance of each service.
-The <<set-time-filter,global time range filter>> in {kib} defines which services are available.
 
 You can add services by setting the `service.name` configuration in each of the {apm-agents-ref}[APM agents] you’re instrumenting.
 

docs/apm/transactions.asciidoc

@@ -4,9 +4,10 @@
 TIP: A {apm-overview-ref-v}/transactions.html[transaction] describes an event captured by an Elastic APM agent instrumenting a service.
 The APM agents automatically collect performance metrics on HTTP requests, database queries, and much more.
 
-// Clicking *service* brings you to detail of transaction
-Selecting a <<services,*service*>> will display all associated *transactions*.
-The charts and table on this dashboard display the transaction duration, requests per minute, and a list of transactions for the selected service.
+Selecting a <<services,*service*>> brings you to the *transactions* overview.
+The *transaction duration* and *requests per minute* chart display information on all transactions associated with the selected service.
+The *Transactions* table, however, provides only a list of _transaction groups_ for the selected service.
+In other words, this view groups all transactions of the same name together, and only displays one transaction for each group.
 
 [role="screenshot"]
 image::apm/images/apm-transactions-overview.png[Example view of transactions table in the APM UI in Kibana]
@@ -20,9 +21,9 @@ and all of the data on the page will update accordingly.
 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.
 
-The table at the bottom is similar to the <<traces,traces>> overview and shows the name of each transaction occurring in the selected service.
+The *Transactions* table is similar to the <<traces,traces>> overview and shows the name of each transaction occurring in the selected service.
 Transactions with the same name are grouped together and only shown once in this table.
-By default, transactions are sorted by _Impact_.
+By default, transaction groups are sorted by _Impact_.
 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>>.
@@ -73,18 +74,18 @@ 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 tabs:
+For a particular transaction sample, we can get even more information in the *metadata* tab:
 
-* *Timeline* - See the <<spans, Spans>> section for more information.
-* *Request* - The URL, headers, body, etc..
-* *Response* - The response.
-* *System* - The system hostname, architecture, platform, etc..
-* *Service* - The service/application runtime, agent, name, etc..
-* *Process* - The process id that served up the request.
-* *User* - This requires additional configuration, but allows you to see which user experienced the current transaction.
-This can be extremely useful if it's determined that specific users are getting slow requests.
-* *Tags* - Useful if you want to start correlating transactions with log files or metrics from Metricbeat.
-* *Custom* - You can configure your agent to add custom contextual information on transactions.
+* Labels - Custom labels added by agents
+* HTTP request/response information
+* Host information
+* Container information
+* Service - The service/application runtime, agent, name, etc..
+* Process - The process id that served up the request.
+* 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.

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

@@ -8,6 +8,7 @@ Not to worry, we've created this guide to help you get the most out of Elastic A
 
 APM is available via the navigation sidebar in {Kib}.
 
+* <<filters,Filters>>
 * <<services,Services overview>>
 * <<traces,Traces overview>>
 * <<transactions,Transaction overview>>
@@ -17,6 +18,8 @@ APM is available via the navigation sidebar in {Kib}.
 * <<machine-learning-integration,Machine learning integration>>
 * <<query-bar,Advanced queries>>
 
+include::filters.asciidoc[]
+
 include::services.asciidoc[]
 
 include::traces.asciidoc[]
@@ -29,4 +32,4 @@ include::errors.asciidoc[]
 
 include::metrics.asciidoc[]
 
-include::query-bar.asciidoc[]
+include::advanced-queries.asciidoc[]