[8.7] [APM] 8.7.0 Documentation and screenshot updates (#153140) (#153967)

# Backport

This will backport the following commits from `main` to `8.7`:
- [[APM] 8.7.0 Documentation and screenshot updates
(#153140)](https://github.com/elastic/kibana/pull/153140)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Brandon
Morelli","email":"brandon.morelli@elastic.co"},"sourceCommit":{"committedDate":"2023-03-29T17:21:44Z","message":"[APM]
8.7.0 Documentation and screenshot updates (#153140)\n\n###
Summary\r\n\r\n- Closes
https://github.com/elastic/observability-docs/issues/2632.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2631.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2633.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2630.\r\n- Closes
https://github.com/elastic/observability-docs/issues/1339.","sha":"733a6c22444599ca5133802e613737555cec124d","branchLabelMapping":{"^v8.8.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","docs","v8.7.0","v8.8.0"],"number":153140,"url":"https://github.com/elastic/kibana/pull/153140","mergeCommit":{"message":"[APM]
8.7.0 Documentation and screenshot updates (#153140)\n\n###
Summary\r\n\r\n- Closes
https://github.com/elastic/observability-docs/issues/2632.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2631.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2633.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2630.\r\n- Closes
https://github.com/elastic/observability-docs/issues/1339.","sha":"733a6c22444599ca5133802e613737555cec124d"}},"sourceBranch":"main","suggestedTargetBranches":["8.7"],"targetPullRequestStates":[{"branch":"8.7","label":"v8.7.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.8.0","labelRegex":"^v8.8.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/153140","number":153140,"mergeCommit":{"message":"[APM]
8.7.0 Documentation and screenshot updates (#153140)\n\n###
Summary\r\n\r\n- Closes
https://github.com/elastic/observability-docs/issues/2632.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2631.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2633.\r\n- Closes
https://github.com/elastic/observability-docs/issues/2630.\r\n- Closes
https://github.com/elastic/observability-docs/issues/1339.","sha":"733a6c22444599ca5133802e613737555cec124d"}}]}]
BACKPORT-->

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

docs/apm/agent-configuration.asciidoc

@@ -6,11 +6,11 @@
 <titleabbrev>Configure APM agents with central config</titleabbrev>
 ++++
 
-APM Agent configuration allows you to fine-tune your agent configuration from within the APM app.
+APM Agent configuration allows you to fine-tune your APM agent configuration from within the APM app.
 Changes are automatically propagated to your APM agents, so there's no need to redeploy.
 
 To get started, choose the services and environments you wish to configure.
-The APM app will let you know when your agents have applied your configurations.
+The APM app will let you know when your APM agents have applied your configurations.
 
 [role="screenshot"]
 image::apm/images/apm-agent-configuration.png[APM Agent configuration in Kibana]
@@ -18,28 +18,38 @@ image::apm/images/apm-agent-configuration.png[APM Agent configuration in Kibana]
 [float]
 ==== Precedence
 
-Configurations set from the APM app take precedence over configurations set locally in each Agent.
+Configurations set from the APM app take precedence over configurations set locally in each APM agent.
 However, if APM Server is slow to respond, is offline, reports an error, etc.,
 APM agents will use local defaults until they're able to update the configuration.
-For this reason, it is still essential to set custom default configurations locally in each of your agents.
+For this reason, it is still essential to set custom default configurations locally in each of your APM agents.
 
 [float]
 ==== Supported configurations
 
-Each Agent has a list of supported configurations.
+Each APM agent has a list of supported configurations.
 After selecting a Service name and environment in the APM app,
 a list of all supported configuration options,
 including descriptions and default values, will be displayed.
 
-Supported configurations are also tagged with the image:./images/dynamic-config.svg[] badge in each Agent's configuration reference:
+Supported configurations are also tagged with the image:./images/dynamic-config.svg[] badge in each APM agent's configuration reference:
 
 [horizontal]
-Go Agent:: {apm-go-ref}/configuration.html[Configuration reference]
+Go agent:: {apm-go-ref}/configuration.html[Configuration reference]
 iOS agent:: _Not yet supported_
-Java Agent:: {apm-java-ref}/configuration.html[Configuration reference]
-.NET Agent:: {apm-dotnet-ref}/configuration.html[Configuration reference]
-Node.js Agent:: {apm-node-ref}/configuration.html[Configuration reference]
-PHP Agent:: {apm-php-ref}/configuration.html[Configuration reference]
-Python Agent:: {apm-py-ref}/configuration.html[Configuration reference]
-Ruby Agent:: {apm-ruby-ref}/configuration.html[Configuration reference]
-Real User Monitoring (RUM) Agent:: {apm-rum-ref}/configuration.html[Configuration reference]
+Java agent:: {apm-java-ref}/configuration.html[Configuration reference]
+.NET agent:: {apm-dotnet-ref}/configuration.html[Configuration reference]
+Node.js agent:: {apm-node-ref}/configuration.html[Configuration reference]
+PHP agent:: {apm-php-ref}/configuration.html[Configuration reference]
+Python agent:: {apm-py-ref}/configuration.html[Configuration reference]
+Ruby agent:: {apm-ruby-ref}/configuration.html[Configuration reference]
+Real User Monitoring (RUM) agent:: {apm-rum-ref}/configuration.html[Configuration reference]
+
+[float]
+==== APM Server configuration
+
+For most users, APM agent configuration should work out-of-the-box.
+If you run into trouble, it may be because you're not using the {es} output,
+or because your {es} credentials don't have sufficient privileges.
+
+See {apm-guide-ref}/configure-agent-config.html[configure APM agent configuration]
+to learn how to configure APM Server to avoid these problems.

docs/apm/api.asciidoc

@@ -87,15 +87,15 @@ which you can use to automate certain aspects of configuring and deploying Kiban
 [[agent-config-api]]
 === Agent Configuration API
 
-The Agent configuration API allows you to fine-tune your APM agent configuration,
+The APM agent configuration API allows you to fine-tune your APM agent configuration,
 without needing to redeploy your application.
 
-The following Agent configuration APIs are available:
+The following APM agent configuration APIs are available:
 
-* <<apm-update-config>> to create or update an Agent configuration
-* <<apm-delete-config>> to delete an Agent configuration.
-* <<apm-list-config>> to list all Agent configurations.
-* <<apm-search-config>> to search for an Agent configuration.
+* <<apm-update-config>> to create or update an APM agent configuration
+* <<apm-delete-config>> to delete an APM agent configuration.
+* <<apm-list-config>> to list all APM agent configurations.
+* <<apm-search-config>> to search for an APM agent configuration.
 
 [float]
 [[use-agent-config-api]]
@@ -307,7 +307,7 @@ GET  /api/apm/settings/agent-configuration
 ======
 
 `etag`::
-(required) etag is sent by the agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its `applied_by_agent` property will be set to `true`. Every time a configuration is edited `applied_by_agent` is reset to `false`.
+(required) etag is sent by the APM agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its `applied_by_agent` property will be set to `true`. Every time a configuration is edited `applied_by_agent` is reset to `false`.
 
 [[apm-search-config-body]]
 ===== Response body
@@ -719,11 +719,11 @@ curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9"
 [[agent-key-api]]
 === APM agent Key API
 
-The Agent Key API allows you to configure agent keys to authorize requests from APM agents to the APM Server.
+The APM agent Key API allows you to configure APM agent keys to authorize requests from APM agents to the APM Server.
 
-The following Agent key APIs are available:
+The following APM agent key APIs are available:
 
-* <<apm-create-agent-key>> to create an agent key
+* <<apm-create-agent-key>> to create an APM agent key
 
 [float]
 [[use-agent-key-api]]
@@ -778,13 +778,13 @@ POST /_security/role/apm_agent_key_user
 ===== Request body
 
 `name`::
-(required, string) Name of the agent key.
+(required, string) Name of the APM agent key.
 
 `privileges`::
 (required, array) APM agent key privileges. It can take one or more of the following values:
 
-  - `event:write`. Required for ingesting agent events.
-  - `config_agent:read`. Required for agents to read agent configuration remotely.
+  - `event:write`. Required for ingesting APM agent events.
+  - `config_agent:read`. Required for APM agents to read agent configuration remotely.
 
 [[apm-agent-key-create-example]]
 ===== Example

docs/apm/apm-app-users.asciidoc

@@ -175,7 +175,7 @@ See <<apm-app-api-user>>.
 [[apm-app-central-config-manager]]
 ==== Central configuration manager
 
-Central configuration users need to be able to view, create, update, and delete Agent configurations.
+Central configuration users need to be able to view, create, update, and delete APM agent configurations.
 
 . Create a new role, named something like `central-config-manager`, and assign the following privileges:
 +

docs/apm/errors.asciidoc

@@ -20,14 +20,16 @@ Selecting an error group ID or error message brings you to the *Error group*.
 [role="screenshot"]
 image::apm/images/apm-error-group.png[APM Error group]
 
-Here, you'll see the error message, culprit, and the number of occurrences over time.
+The error group details page visualizes the number of error occurrences over time and compared to a recent time range.
+This allows you to quickly determine if the error rate is changing or remaining constant.
+You'll also see the top 5 affected transactions--enabling you to quickly narrow down which transactions are most impacted
+by the selected error.
 
-Further down, you'll see the Error occurrence table.
-This table shows the details of a sampled error within this group.
+Further down, you'll see an Error sample.
 The error shown is always the most recent to occur.
+The sample includes the exception message, culprit, stack trace where the error occurred,
+and additional contextual information to help debug the issue--all of which can be copied with the click of a button.
 
-Each error occurrence features a breakdown of the exception, including the stack trace from when the error occurred,
-and additional contextual information to help debug the issue.
 In some cases, you might also see a Transaction sample ID.
 This feature allows you to make a connection between the errors and transactions,
 by linking you to the specific transaction where the error occurred.

docs/apm/filters.asciidoc

@@ -32,8 +32,8 @@ It allows you to view only relevant data and is especially useful for separating
 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.
-To learn how to configure service environments, see the specific agent documentation:
+It's vital to be consistent when naming environments in your APM agents.
+To learn how to configure service environments, see the specific APM agent documentation:
 
 * *Go:* {apm-go-ref}/configuration.html#config-environment[`ELASTIC_APM_ENVIRONMENT`]
 * *iOS agent:* _Not yet supported_

docs/apm/getting-started.asciidoc

@@ -35,6 +35,7 @@ start with:
 Notice something awry? Select a service or trace and dive deeper with:
 
 * <<service-overview>>
+* <<mobile-service-overview>>
 * <<transactions>>
 * <<spans>>
 * <<errors>>
@@ -53,6 +54,8 @@ include::service-maps.asciidoc[]
 
 include::service-overview.asciidoc[]
 
+include::mobile-service.asciidoc[]
+
 include::transactions.asciidoc[]
 
 include::spans.asciidoc[]

docs/apm/index.asciidoc

@@ -7,7 +7,7 @@
 The APM app in {kib} allows you to monitor your software services and applications in real-time;
 visualize detailed performance information on your services,
 identify and analyze errors,
-and monitor host-level and agent-specific metrics like JVM and Go runtime metrics.
+and monitor host-level and APM agent-specific metrics like JVM and Go runtime metrics.
 
 [float]
 [[apm-bottlenecks]]

docs/apm/metrics.asciidoc

@@ -2,7 +2,7 @@
 [[metrics]]
 === Metrics
 
-The *Metrics* overview provides agent-specific metrics,
+The *Metrics* overview provides APM agent-specific metrics,
 which lets you perform more in-depth root cause analysis investigations within the APM app.
 
 If you're experiencing a problem with your service, you can use this page to attempt to find the underlying cause.
@@ -11,7 +11,7 @@ For example, you might be able to correlate a high number of errors with a long
 [role="screenshot"]
 image::apm/images/apm-metrics.png[Example view of the Metrics overview in APM app in Kibana]
 
-If you're using the Java Agent, you can view metrics for each JVM.
+If you're using the Java APM agent, you can view metrics for each JVM.
 
 [role="screenshot"]
 image::apm/images/jvm-metrics-overview.png[Example view of the Metrics overview for the Java Agent]

docs/apm/mobile-service.asciidoc

@@ -0,0 +1,59 @@
+[role="xpack"]
+[[mobile-service-overview]]
+=== Mobile service overview
+
+Selecting a mobile service brings you to the *Mobile service overview*.
+The *Mobile service overview* contains a wide variety of charts and tables that provide
+high-level visibility into how a mobile service is performing for your users--enabling you
+to make data-driven decisions about how to improve your user experience.
+
+For example, see:
+
+* Crash Rate (Crashes per minute) -- coming soon
+* Slowest App load time -- coming soon
+* Number of sessions
+* Number of HTTP requests
+* Map showing the total number of HTTP requests based on country and region
+* Most used devices, network connection type, OS version, and app version
+* Latency, throughput, and errors over time
+* Service dependencies
+
+All of these metrics & insights can help SREs and developers better understand the health
+of their mobile application environment and the impact of backend errors and bottlenecks on end-user experience.
+
+[discrete]
+[[mobile-service-stats]]
+=== Quick stats
+
+Understand the impact of slow application load times and variations in application crash rate on user traffic (coming soon).
+Visualize session and HTTP trends, and see where your users are located--enabling you to optimize your infrastructure deployment and routing topology.
+
+[role="screenshot"]
+image::apm/images/mobile-location.png[mobile service overview centered on location map]
+
+[discrete]
+[[mobile-service-most-used]]
+=== Most used
+
+Optimize your end-user experience and your application QA strategy based on your most used device models and operating system versions.
+
+[role="screenshot"]
+image::apm/images/mobile-most-used.png[mobile service overview showing most used devices, network, OS, and app version]
+
+
+[discrete]
+[[mobile-throughput-transactions]]
+=== Throughput and transactions
+
+include::./service-overview.asciidoc[tag=throughput-transactions]
+
+[discrete]
+[[mobile-error-and-dependencies]]
+=== Failed transaction rate and dependencies
+
+include::./service-overview.asciidoc[tag=ftr]
+
+include::./service-overview.asciidoc[tag=dependencies]
+
+[role="screenshot"]
+image::apm/images/mobile-tp.png[mobile service overview showing latency, throughput, and errors]

docs/apm/service-maps.asciidoc

@@ -55,19 +55,20 @@ By default, all instrumented services and connections are shown.
 Whether you're onboarding a new engineer, or just trying to grasp the big picture,
 drag things around, zoom in and out, and begin to visualize how your services are connected.
 
+Customize what the service map displays using either the query bar or the environment selector.
+The query bar enables you to use <<advanced-queries,advanced queries>> to customize the service map based on your needs.
+The environment selector allows you to narrow displayed results to a specific environment.
+This can be useful if you have two or more services, in separate environments, but with the same name.
+Use the environment drop-down to only see the data you're interested in, like `dev` or `production`.
+
 If there's a specific service that interests you, select that service to highlight its connections.
 Clicking **Focus map** will refocus the map on that specific service and lock the connection highlighting.
 From here, select **Service Details**, or click on the **Transaction** tab to jump to the Transaction overview
 for the selected service.
 You can also use the tabs at the top of the page to easily jump to the **Errors** or **Metrics** overview.
 
-Filter out your maps by picking the environment from the environment drop-down filter.
-This can be useful if you have two or more services, in separate environments, but with the same name.
-Use the environment drop-down to only see the data you're interested in, like `dev` or `production`.
-Additional filters are not currently available for service maps.
-
 [role="screenshot"]
-image::apm/images/service-maps-java.png[Example view of service maps with Java highlighted in the APM app in Kibana]
+image::apm/images/service-maps-java.png[Example view of service maps in the APM app in Kibana]
 
 [float]
 [[service-map-anomaly-detection]]
@@ -95,16 +96,16 @@ To learn how to create a machine learning job, see <<machine-learning-integratio
 
 Nodes appear on the map in one of two shapes:
 
-* **Circle**: Instrumented services. Interior icons are based on the language of the agent used.
+* **Circle**: Instrumented services. Interior icons are based on the language of the APM agent used.
 * **Diamond**: Databases, external, and messaging. Interior icons represent the generic type,
 with specific icons for known entities, like Elasticsearch.
 Type and subtype are based on `span.type`, and `span.subtype`.
 
 [float]
 [[service-maps-supported]]
-=== Supported APM Agents
+=== Supported APM agents
 
-Service maps are supported for the following Agent versions:
+Service maps are supported for the following APM agent versions:
 
 [horizontal]
 Go agent:: ≥ v1.7.0

docs/apm/service-overview.asciidoc

@@ -2,11 +2,11 @@
 [[service-overview]]
 === Service overview
 
-Selecting a <<services,*service*>> brings you to the *Service overview*.
+Selecting a non-mobile <<services,*service*>> brings you to the *Service overview*.
 The *Service overview* contains a wide variety of charts and tables that provide
 high-level visibility into how a service is performing across your infrastructure:
 
-* Service details like service version, runtime version, framework, and agent name and version
+* Service details like service version, runtime version, framework, and APM agent name and version
 * Container and orchestration information
 * Cloud provider, machine type, service name, region, and availability zone
 * Serverless function names and event trigger type
@@ -61,6 +61,7 @@ image::apm/images/latency.png[Service latency]
 [[service-throughput-transactions]]
 === Throughput and transactions
 
+// tag::throughput-transactions[]
 The *Throughput* chart visualizes the average number of transactions per minute for the selected service.
 
 The *Transactions* table displays a list of _transaction groups_ for the
@@ -73,11 +74,13 @@ list of similar transactions on the <<transactions, transactions overview>> page
 
 [role="screenshot"]
 image::apm/images/traffic-transactions.png[Traffic and transactions]
+// end::throughput-transactions[]
 
 [discrete]
 [[service-error-rates]]
 === Failed transaction rate and errors
 
+// tag::ftr[]
 The failed transaction rate represents the percentage of failed transactions from the perspective of the selected service.
 It's useful for visualizing unexpected increases, decreases, or irregular patterns in a service's transactions.
 
@@ -91,6 +94,7 @@ These spans will set `event.outcome=failure` and increase the failed transaction
 
 If there is no HTTP status, both transactions and spans are considered successful unless an error is reported.
 ====
+// end::ftr[]
 
 The *Errors* table provides a high-level view of each error message when it first and last occurred,
 along with the total number of occurrences. This makes it very easy to quickly see which errors affect
@@ -105,10 +109,11 @@ image::apm/images/error-rate.png[failed transaction rate and errors]
 
 The *Time spent by span type* chart visualizes each span type's average duration and helps you determine
 which spans could be slowing down transactions. The "app" label displayed under the
-chart indicates that something was happening within the application. This could signal that the
+chart indicates that something was happening within the application. This could signal that the APM
 agent does not have auto-instrumentation for whatever was happening during that time or that the time was spent in the
 application code and not in database or external requests.
 
+// tag::dependencies[]
 The *Dependencies* table displays a list of downstream services or external connections relevant
 to the service at the selected time range. The table displays latency, throughput, failed transaction rate, and the impact of
 each dependency. By default, dependencies are sorted by _Impact_ to show the most used and the slowest dependency.
@@ -119,14 +124,20 @@ requires an agent version ≥ v5.6.3.
 
 [role="screenshot"]
 image::apm/images/spans-dependencies.png[Span type duration and dependencies]
+// end::dependencies[]
 
 [discrete]
 [[service-cold-start]]
 === Cold start rate
 
-The cold start rate chart is specific to serverless services.
-It displays the percentage of requests that trigger a cold start of a serverless function.
-See <<apm-lambda-cold-start-info>> for more information.
+The cold start rate chart is specific to serverless services, and displays the
+percentage of requests that trigger a cold start of a serverless function.
+A cold start occurs when a serverless function has not been used for a certain period of time.
+Analyzing the cold start rate can be useful for deciding how much memory to allocate to a function,
+or when to remove a large dependency.
+
+The cold start rate chart is currently supported for <<apm-lambda-cold-start-info,AWS Lambda>>
+functions and Azure functions.
 
 [role="screenshot"]
 image::apm/images/lambda-cold-start.png[lambda cold start graph]
@@ -157,7 +168,7 @@ image::apm/images/metadata-icons.png[Service metadata]
 * Service version
 * Runtime name and version
 * Framework name
-* Agent name and version
+* APM agent name and version
 
 *Container information*
 

docs/apm/set-up.asciidoc

@@ -8,11 +8,7 @@
 
 APM is available via the navigation sidebar in {Kib}.
 If you have not already installed and configured Elastic APM,
-follow the three steps on the *Add data* page to get started:
-
-. Start APM Server
-. Add APM agents
-. Load Kibana objects
+follow the steps on the *Add data* page to get started.
 
 [role="screenshot"]
 image::apm/images/apm-setup.png[Installation instructions on the APM page in Kibana]

docs/apm/spans.asciidoc

@@ -23,6 +23,22 @@ Each span has a type and is defined by a different color in the timeline/waterfa
 [role="screenshot"]
 image::apm/images/apm-span-detail.png[Example view of a span detail in the APM app in Kibana]
 
+[float]
+[[trace-sample-investigate]]
+==== Investigate
+
+The trace sample timeline features an **Investigate** button which provides a quick way to jump
+to other areas of the Elastic Observability UI while maintaining the context of the currently selected trace sample.
+For example, quickly view:
+
+* logs and metrics for the selected pod
+* logs and metrics for the selected host
+* trace logs for the selected `trace.id`
+* uptime status of the selected domain
+* the <<service-maps,service map>> filtered by the selected trace
+* the selected transaction in <<discover,Discover>>
+* your <<custom-links,custom links>>
+
 [float]
 [[distributed-tracing]]
 ==== Distributed tracing

docs/apm/storage-explorer.asciidoc

@@ -74,7 +74,7 @@ tune the APM agent or agents that are collecting the data.
 You can disable the collection of specific metrics with the **disable metrics** configuration.
 Or, you can set the **metrics interval** to zero seconds to deactivate metrics entirely.
 Most APM agents support both options.
-See the relevant {apm-agents-ref}[agent configuration options] for more details.
+See the relevant {apm-agents-ref}[APM agent configuration options] for more details.
 
 [float]
 ===== Reduce the number of errors

docs/apm/transactions.asciidoc

@@ -44,7 +44,7 @@ For example, is your app spending time in external calls, database processing, o
 +
 The time a transaction took to complete is also recorded and displayed on the chart under the "app" label.
 "app" indicates that something was happening within the application, but we're not sure exactly what.
-This could be a sign that the agent does not have auto-instrumentation for whatever was happening during that time.
+This could be a sign that the APM agent does not have auto-instrumentation for whatever was happening during that time.
 +
 It's important to note that if you have asynchronous spans, the sum of all span times may exceed the duration of the transaction.
 
@@ -71,7 +71,7 @@ If there's a particular endpoint you're worried about, you can click on it to vi
 [IMPORTANT]
 ====
 If you only see one route in the Transactions table, or if you have transactions named "unknown route",
-it could be a symptom that the agent either wasn't installed correctly or doesn't support your framework.
+it could be a symptom that the APM agent either wasn't installed correctly or doesn't support your framework.
 
 For further details, including troubleshooting and custom implementation instructions,
 refer to the documentation for each {apm-agents-ref}[APM Agent] you've implemented.
@@ -81,7 +81,7 @@ refer to the documentation for each {apm-agents-ref}[APM Agent] you've implement
 [[rum-transaction-overview]]
 === RUM Transaction overview
 
-The transaction overview page is customized for the JavaScript RUM Agent.
+The transaction overview page is customized for the JavaScript RUM agent.
 Specifically, the page highlights *page load times* for your service:
 
 [role="screenshot"]
@@ -144,13 +144,13 @@ NOTE: More information on timeline waterfalls is available in <<spans, spans>>.
 
 Learn more about a trace sample in the *Metadata* tab:
 
-* Labels - Custom labels added by agents
+* Labels - Custom labels added by APM agents
 * HTTP request/response information
 * Host information
 * Container information
-* Service - The service/application runtime, agent, name, etc..
+* Service - The service/application runtime, APM agent, name, etc..
 * Process - The process id that served up the request.
-* Agent information
+* APM agent information
 * URL
 * User - Requires additional configuration, but allows you to see which user experienced the current transaction.
 * FaaS information, like cold start, AWS request ID, trigger type, and trigger request ID

docs/apm/troubleshooting.asciidoc

@@ -58,20 +58,20 @@ To force a rollover, use the {ref}/indices-rollover-index.html[rollover API] to
 [[troubleshooting-too-many-transactions]]
 === Too many unique transaction names
 
-Transaction names are defined in each APM Agent; when an Agent supports a framework,
+Transaction names are defined in each APM agent; when an APM agent supports a framework,
 it includes logic for naming the transactions that the framework creates.
-In some cases though, like when using an Agent's API to create custom transactions,
+In some cases though, like when using an APM agent's API to create custom transactions,
 it is up to the user to define a pattern for transaction naming.
 When transactions are named incorrectly, each unique URL can be associated with a unique transaction group—causing
 an explosion in the number of transaction groups per service, and leading to inaccuracies in the APM app.
 
 To fix a large number of unique transaction names,
-you need to change how you are using the Agent API to name your transactions.
+you need to change how you are using the APM agent API to name your transactions.
 To do this, ensure you are **not** naming based on parameters that can change.
 For example, user ids, product ids, order numbers, query parameters, etc.,
 should be stripped away, and commonality should be found between your unique URLs.
 
-Let's look at an example from the RUM Agent documentation. Here are a few URLs you might find on Elastic.co:
+Let's look at an example from the RUM agent documentation. Here are a few URLs you might find on Elastic.co:
 
 [source,yml]
 ----
@@ -109,14 +109,14 @@ You will see this warning if your results have more than `1000` unique transacti
 
 **More information**
 
-While this can happen with any APM Agent, it typically occurs with the RUM Agent.
-For more information on how to correctly set `transaction.name` in the RUM Agent,
+While this can happen with any APM agent, it typically occurs with the RUM agent.
+For more information on how to correctly set `transaction.name` in the RUM agent,
 see {apm-rum-ref}/custom-transaction-name.html[custom initial page load transaction names].
 
-The RUM Agent can also set the `transaction.name` when observing for transaction events.
+The RUM agent can also set the `transaction.name` when observing for transaction events.
 See {apm-rum-ref}/agent-api.html#observe[`apm.observe()`] for more information.
 
-If your problem is occurring in a different Agent, the tips above still apply.
+If your problem is occurring in a different APM agent, the tips above still apply.
 See the relevant {apm-agents-ref}[Agent API documentation] to adjust how you're naming your transactions.
 
 [float]
@@ -128,17 +128,17 @@ when the transactions in your services are named correctly.
 If you're seeing "GET unknown route" or "unknown route" in the APM app,
 it could be a sign that something isn't working as it should.
 
-Elastic APM Agents come with built-in support for popular frameworks out-of-the-box.
-This means, among other things, that the Agent will try to automatically name HTTP requests.
-As an example, the Node.js Agent uses the route that handled the request, while the Java Agent uses the Servlet name.
+Elastic APM agents come with built-in support for popular frameworks out-of-the-box.
+This means, among other things, that the APM agent will try to automatically name HTTP requests.
+As an example, the Node.js agent uses the route that handled the request, while the Java agent uses the Servlet name.
 
-"Unknown route" indicates that the Agent can't determine what to name the request,
-perhaps because the technology you're using isn't supported, the Agent has been installed incorrectly,
-or because something is happening to the request that the Agent doesn't understand.
+"Unknown route" indicates that the APM agent can't determine what to name the request,
+perhaps because the technology you're using isn't supported, the agent has been installed incorrectly,
+or because something is happening to the request that the agent doesn't understand.
 
-To resolve this, you'll need to head over to the relevant {apm-agents-ref}[Agent documentation].
-Specifically, view the Agent's supported technologies page.
-You can also use the Agent's public API to manually set a name for the transaction.
+To resolve this, you'll need to head over to the relevant {apm-agents-ref}[APM agent documentation].
+Specifically, view the agent's supported technologies page.
+You can also use the agent's public API to manually set a name for the transaction.
 
 [float]
 [[troubleshooting-fields-unsearchable]]
@@ -148,7 +148,7 @@ In Elasticsearch, index templates are used to define settings and mappings that
 The recommended index templates for APM are installed by {fleet} when the Elastic APM integration is installed.
 These templates, by default, enable and disable indexing on certain fields.
 
-As an example, some agents store cookie values in `http.request.cookies`.
+As an example, some APM agents store cookie values in `http.request.cookies`.
 Since `http.request` has disabled dynamic indexing, and `http.request.cookies` is not declared in a custom mapping,
 the values in `http.request.cookies` are not indexed and thus not searchable.
 
@@ -187,5 +187,5 @@ 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 agent adding the
+In other words, `distributedTracingOrigins` is consulted prior to the APM agent adding the
 distributed tracing `traceparent` header to each request.