Merge branch '7.12' into backport/7.12/pr-91829

Author: kibanamachine

docs/apm/advanced-queries.asciidoc

@@ -2,42 +2,63 @@
 [[advanced-queries]]
 === Query your data
 
-Querying your APM data is a powerful tool that can make finding bottlenecks in your code even easier.
-Imagine you have a user that complains about a slow response time in a specific service.
-With the query bar, you can easily filter the APM app to only display trace data for that user,
-or, to only show transactions that are slower than a specified time threshold.
+Querying your APM data is an essential tool that can make finding bottlenecks in your code even more straightforward.
 
-[float]
-==== Example APM app queries
+Using the query bar, a powerful data query feature, you can pass advanced queries on your data
+to filter on specific pieces of information you’re interested in.
+
+The query bar 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 scanning recommendations.
 
-* Exclude response times slower than 2000 ms: `transaction.duration.us > 2000000`
-* Filter by response status code: `context.response.status_code ≥ 400`
-* Filter by single user ID: `context.user.id : 12`
+[float]
+[[apm-app-advanced-queries]]
+=== Querying in the APM app
 
-When querying in the APM app, you're merely searching and selecting data from fields in Elasticsearch documents.
-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.
+When querying in the APM app, you’re merely searching and selecting data from fields in {es} documents. 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.
 
 When you type, you can begin to see some of the transaction fields available for filtering:
 
 [role="screenshot"]
 image::apm/images/apm-query-bar.png[Example of the Kibana Query bar in APM app in Kibana]
 
-TIP: Read the {kibana-ref}/kuery-query.html[Kibana Query Language Enhancements] documentation to learn more about the capabilities of the {kib} query language.
+[TIP]
+=====
+To learn more about the {kib} query language capabilities, see the {kibana-ref}/kuery-query.html[Kibana Query Language Enhancements] documentation.
+=====
+
+[float]
+[[apm-app-queries]]
+==== APM app queries
+
+APM queries can be handy for removing noise from your data in the <<services,Services>>, <<transactions,Transactions>>,
+<<errors,Errors>>, <<metrics,Metrics>>, and <<traces,Traces>> views.
+
+For example, in the *Services* view, you can quickly view a list of all the instrumented services running on your production
+environment: `service.environment : production`. Or filter the list by including the APM agent's name and the host it’s running on:
+`service.environment : "production" and agent.name : "java" and host.name : "prod-server1"`.
+
+On the *Traces* view, you might want to view failed transaction results from any of your running containers:
+`transaction.result :"FAILURE" and container.id : *`.
+
+On the *Transactions* view, you may want to list only the slower transactions than a specified time threshold: `transaction.duration.us > 2000000`.
+Or filter the list by including the service version and the Kubernetes pod it's running on:
+`transaction.duration.us > 2000000 and service.version : "7.12.0" and kubernetes.pod.name : "pod-5468b47f57-pqk2m"`.
 
 [float]
 [[discover-advanced-queries]]
 === Querying in Discover
 
 Alternatively, you can query your APM documents in {kibana-ref}/discover.html[*Discover*].
-Querying documents in *Discover* works the same way as querying in the APM app,
+Querying documents in *Discover* works the same way as queries in the APM app,
 and *Discover* supports all of the example APM app queries shown on this page.
 
 [float]
-==== Example Discover query
+[[discover-queries]]
+==== Discover queries
 
 One example where you may want to make use of *Discover*,
-is for viewing  _all_ transactions for an endpoint, instead of just a sample.
+is to view  _all_ transactions for an endpoint instead of just a sample.
 
 TIP: Starting in v7.6, you can view ten samples per bucket in the APM app, instead of just one.
 

docs/apm/correlations.asciidoc

@@ -3,16 +3,16 @@
 === Find latency and error correlations
 
 **Correlations** surface attributes of your data that are potentially correlated with high-latency or erroneous transactions.
-Surfaced attributes are user-defined, meaning that they are completely customizable to your APM data.
+By default, a number of attributes commonly known to cause performance issues, like version,
+infrastructure, and location, are included, but all are completely customizable to your APM data.
 Find something interesting? A quick click of a button will auto-query your data as you work to resolve the underlying issue.
 
 For example, a site reliability engineer, who is responsible for keeping production systems up and running,
 notices an increase in latency in certain transactions.
 Analyzing metadata or tags that exist in high-latency transactions but not in lower-latency transactions
 can potentially point towards the root cause.
 They may find that a particular piece of hardware, like a host or pod, has failed, increasing latency.
-Or, perhaps a set of users, based on IP address or region, is physically too far away from the nearest
-data center, increasing latency.
+Or, perhaps set of users, based on IP address or region, is facing increased latency due to local data center issues.
 
 [discrete]
 [[view-correlations]]
@@ -27,8 +27,8 @@ Queries within the APM app apply to the correlations shown in the correlations f
 
 If a correlated field seems noteworthy, use the **Filter** quick links:
 
-* `+` creates a new query in the APM app for transactions containing the selected value.
-* `-` creates a new query in the APM app for transactions without the selected value.
+* `+` creates a new query in the APM app for filtering transactions containing the selected value.
+* `-` creates a new query in the APM app to filter out transactions containing the selected value.
 
 [discrete]
 [[correlations-latency]]
@@ -37,8 +37,9 @@ If a correlated field seems noteworthy, use the **Filter** quick links:
 Correlations help you discover which fields are contributing to increased service latency.
 
 A latency distribution chart visualizes the overall latency of the selected service's transactions.
-Correlated attributes are sorted by _Impact_–a visual representation of the score for the underlying
-aggregation that powers correlations.
+Correlated attributes are sorted by _Impact_–a visual representation of the
+{ref}/search-aggregations-bucket-significantterms-aggregation.html[significant terms aggregation]
+score that powers correlations.
 Attributes with a high impact, or attributes present in a large percentage of slow transactions,
 may contribute to increased latency.
 
@@ -51,19 +52,25 @@ exists primarily in higher-latency transactions between 3.7 and 8.7 seconds.
 [role="screenshot"]
 image::apm/images/correlations-hover.png[Correlations hover effect]
 
-Selecting the `+` filter creates a new query in the APM app for transactions with
+Select the `+` filter to create a new query in the APM app for transactions with
 `user_agent.name: HeadlessChrome`. With the "noise" now filtered out,
 you can begin viewing sample traces to continue your investigation.
 
+As you sift through high-latency transactions, you'll likely notice other interesting attributes.
+Return to the correlations fly-out and select *Customize fields* to search on these new attributes.
+You may need to do this a few times–each time filtering out more and more noise and bringing you
+closer to a diagnosis.
+
 [discrete]
 [[correlations-error-rate]]
 ==== Find error rate correlations
 
 Correlations help you discover which fields are contributing to failed transactions.
 
 The Error rate over time chart visualizes the change in error rate over the selected time frame.
-Correlated attributes are sorted by _Impact_–a visual representation of the score for the underlying
-aggregation that powers correlations.
+Correlated attributes are sorted by _Impact_–a visual representation of the
+{ref}/search-aggregations-bucket-significantterms-aggregation.html[significant terms aggregation]
+score that powers correlations.
 Attributes with a high impact, or attributes present in a large percentage of failed transactions,
 may contribute to increased error rates.
 
@@ -76,16 +83,41 @@ existed in 100% of failed transactions between 6:00 and 10:30.
 [role="screenshot"]
 image::apm/images/error-rate-hover.png[Correlations errors hover effect]
 
-Selecting the `+` filter creates a new query in the APM app for transactions with
+Select the `+` filter to create a new query in the APM app for transactions with
 `url.original: http://localhost:3100...`. With the "noise" now filtered out,
 you can begin viewing sample traces to continue your investigation.
 
+As you sift through erroneous transactions, you'll likely notice other interesting attributes.
+Return to the correlations fly-out and select *Customize fields* to search on these new attributes.
+You may need to do this a few times–each time filtering out more and more noise and bringing you
+closer to a diagnosis.
+
 [discrete]
-[[correlations-custom-fields]]
+[[correlations-customize-fields]]
 ====  Customize fields
 
 Correlations are only as good as the data they're searching for.
-By default, a handful of potentially useful fields are selected, like `lables`, `service.version`, and `host.ip`.
-You can remove and add fields to this list under the **Customize fields** dropdown.
+By default, a handful of attributes commonly known to cause performance issues are included.
+During the course of an investigation however, you may to need to add and remove fields from
+this list multiple times as you narrow in on a diagnosis.
+
+Add and remove fields under the **Customize fields** dropdown.
+The following fields are selected by default.
+To keep the default list manageable, only the first six matching fields with wildcards are used.
+
+**Frontend (RUM) agent:**
+
+* `labels.*`
+* `user.*`
+* `user_agent.name`
+* `user_agent.os.name`
+* `url.original`
+
+**Backend agents:**
+
+* `labels.*`
+* `host.ip`
+* `service.node.name`
+* `service.version`
 
 TIP: Want to start over? Select **reset** to clear your customizations.

docs/apm/filters.asciidoc

@@ -6,49 +6,34 @@
 <titleabbrev>Filter data</titleabbrev>
 ++++
 
-APM provides two different ways you can filter your data within the APM App:
-
-* <<global-filters>>
-* <<contextual-filters>>
-
-[[global-filters]]
-==== Global filters
-
-Global filters are ways you can filter any and all data across the APM app.
-They are available in the Services, Transactions, Errors, Metrics, and Traces views,
-and any filter applied will persist as you move between pages.
+Global filters are ways you can filter data across the APM app based on a specific
+time range or environment. 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 app 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
+[NOTE]
+=====
+If you prefer to use advanced queries on your data to filter on specific pieces
+of information, see <<advanced-queries,Query your data>>.
+=====
 
-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.
+[[global-time-range]]
+==== Global time range
 
-See <<query-bar,advanced queries>> for more information and sample queries.
+The <<set-time-filter,global time range filter>> in {kib} restricts APM data to a specific time period.
 
-[float]
 [[environment-selector]]
-===== Service environment filter
+==== 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.
+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 vital 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:
+To learn how to configure service environments, see the specific agent documentation:
 
 * *Go:* {apm-go-ref}/configuration.html#config-environment[`ELASTIC_APM_ENVIRONMENT`]
 * *Java:* {apm-java-ref}/config-core.html#config-environment[`environment`]
@@ -58,19 +43,3 @@ See the documentation for each agent you're using to learn how to configure serv
 * *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`]
-
-[[contextual-filters]]
-==== Contextual filters
-
-Contextual filters are ways you can filter your specific APM data on each individual page.
-The filters shown are relevant to your data, and will persist between pages,
-but only where they are applicable -- they are typically most useful in their original context.
-As an example, if you select a host on the Services overview, then select a transaction group,
-the host filter will still be applied.
-
-These filters are very useful for quickly and easily removing noise from your data.
-With just a click, you can filter your transactions by the transaction result,
-host, container ID, Kubernetes pod, and more.
-
-[role="screenshot"]
-image::apm/images/local-filter.png[Local filters available in the APM app in Kibana]