[APM] docs: storage explorer (#143024)

* initial draft

* nit

* docs: add storage explorer privs

* docs: chart and table fixes

* docs: add metrics

* Update docs/apm/apm-app-users.asciidoc

Co-authored-by: Giorgos Bamparopoulos <gbamparop@gmail.com>

Co-authored-by: Giorgos Bamparopoulos <gbamparop@gmail.com>

docs/apm/apm-app-users.asciidoc

@@ -28,6 +28,7 @@ Select your use-case to get started:
 * <<apm-app-reader>>
 * <<apm-app-annotation-user-create>>
 * <<apm-app-central-config-user>>
+* <<apm-app-storage-explorer-user-create>>
 * <<apm-app-api-user>>
 
 ////
@@ -53,11 +54,12 @@ To create an APM reader user:
 . Create a new role, named something like `read-apm`, and assign the following privileges:
 +
 --
+:apm-read-view:
+:apm-monitor:
 include::./tab-widgets/apm-app-reader/widget.asciidoc[]
+:!apm-read-view:
+:!apm-monitor:
 --
-+
-TIP: Using the deprecated APM Server binaries?
-Add the privileges under the **Classic APM indices** tab above.
 
 . Assign the `read-apm` role created in the previous step, and the following built-in roles to
 any APM reader users:
@@ -83,9 +85,6 @@ In some instances, you may wish to restrict certain Kibana apps that a user has
 --
 include::./tab-widgets/apm-app-reader/widget.asciidoc[]
 --
-+
-TIP: Using the deprecated APM Server binaries?
-Add the privileges under the **Classic APM indices** tab above.
 
 . Assign feature privileges to any Kibana feature that the user needs access to.
 Here are two examples:
@@ -235,6 +234,33 @@ See <<apm-app-api-user>>.
 ***********************************  ***********************************
 ////
 
+[role="xpack"]
+[[apm-app-storage-explorer-user-create]]
+=== APM app storage explorer user
+
+++++
+<titleabbrev>Create a storage explorer user</titleabbrev>
+++++
+
+[[apm-app-storage-explorer-user]]
+==== Storage explorer user
+
+View the **Storage explorer** in the APM app.
+
+. Create a new role, named something like `storage-explorer_user`,
+and assign the following privileges:
++
+--
+include::./tab-widgets/storage-explorer-user/widget.asciidoc[]
+--
+
+. Assign the `storage-explorer_user` created previously, and the roles and privileges necessary to create
+a <<apm-app-reader-full,full>> or <<apm-app-reader-partial,partial>> APM reader to any users that need to view **Storage explorer** in the APM app.
+
+////
+***********************************  ***********************************
+////
+
 [role="xpack"]
 [[apm-app-api-user]]
 === APM app API user

docs/apm/how-to-guides.asciidoc

@@ -14,6 +14,7 @@ Learn how to perform common APM app tasks.
 * <<machine-learning-integration>>
 * <<apm-lambda>>
 * <<advanced-queries>>
+* <<storage-explorer>>
 * <<transactions-annotations>>
 
 
@@ -35,4 +36,6 @@ include::lambda.asciidoc[]
 
 include::advanced-queries.asciidoc[]
 
+include::storage-explorer.asciidoc[]
+
 include::deployment-annotations.asciidoc[]

docs/apm/storage-explorer.asciidoc

@@ -0,0 +1,93 @@
+[[storage-explorer]]
+=== Storage explorer
+
+beta::[]
+
+Analyze your APM data and manage costs with **storage explorer**.
+For example, analyze the storage footprint of each of your services to see which are producing
+large amounts of data--then change the sample rate of a service to lower the amount of data ingested.
+Or, expand the time filter to visualize data trends over time so that you can better forecast
+and prepare for future storage needs.
+
+[role="screenshot"]
+image::apm/images/storage-explorer-overview.png[APM Storage explorer]
+
+[float]
+==== Index lifecycle phases
+
+A default {apm-guide-ref}/ilm-how-to.html[index lifecycle policy] is applied to each APM data stream,
+but can be customized depending on your business needs.
+Use the **Index lifecycle phase** dropdown to visualize and analyze your storage by phase.
+
+Customizing the default APM index lifecycle policies can save money by specifying things like:
+
+* The point at which an index can be moved to less performant hardware.
+* The point at which availability is not as critical and the number of replicas can be reduced.
+* When the index can be safely deleted.
+
+See {apm-guide-ref}/ilm-how-to.html[Index lifecycle management] to learn more about customizing
+the default APM index lifecycle policies.
+
+[float]
+==== Service size chart
+
+The service size chart displays the estimated size of each service over time.
+Expand the time filter to visualize data trends and estimate daily data generation.
+
+[float]
+==== Service statistics table
+
+The service statistics table provides detailed information on each service:
+
+* A list of **service environments**.
+* The **sampling rate**. This value is calculated by dividing the number of sampled transactions by total throughput.
+It might differ from the configured sampling rate for two reasons: with head-based sampling,
+the initial service makes the sampling decision, and with tail-based sampling,
+granular policies allow you to set multiple sample rates.
+* The estimated **size on disk**. This storage size includes both primary and replica shards and is
+calculated by prorating the total size of your indices by the service's document count divided by
+the total number of documents.
+* Number of **transactions**, **spans**, **errors**, and **metrics** — doc count and size on disk.
+
+[role="screenshot"]
+image::apm/images/storage-explorer-expanded.png[APM Storage explorer service breakdown]
+
+As you explore your service statistics, you might want to take action to reduce the number of
+documents and therefore storage size of a particular service.
+
+[float]
+===== Reduce the number of transactions
+To reduce the number of transactions a service generates, configure a more aggressive
+{apm-guide-ref}/sampling.html[transaction sampling policy]. Transaction sampling lowers
+the amount of data ingested without negatively impacting the usefulness of your data.
+
+[float]
+===== Reduce the number of spans
+To reduce the number of spans a service generates, enable
+{apm-guide-ref}/span-compression.html[span compression]. Span compression saves on data
+and transfer costs by compressing multiple, similar spans into a single span.
+
+[float]
+===== Reduce the number of metrics
+To reduce the number of system, runtime, and application metrics,
+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.
+
+[float]
+===== Reduce the number of errors
+To reduce the number of errors a service generate,
+work with your developers to change how exceptions are handled in your code.
+
+[float]
+==== Privileges
+
+Storage explorer requires expanded privileges to view.
+See <<apm-app-storage-explorer-user-create>> for more information.
+
+[float]
+==== Limitations
+
+Multi-cluster deployments are not supported.

docs/apm/tab-widgets/storage-explorer-user/content.asciidoc

@@ -0,0 +1,29 @@
+// tag::classic-indices[]
+[options="header"]
+|====
+|Type |Privilege |Purpose
+
+|Index
+|`monitor` on `apm-*`
+|Monitor access to `apm-*` for storage explorer
+|====
+// end::classic-indices[]
+
+// tag::data-streams[]
+[options="header"]
+|====
+|Type |Privilege |Purpose
+
+|Index
+|`monitor` on `logs-apm*`
+|Monitor access to `logs-apm*` for storage explorer
+
+|Index
+|`monitor` on `metrics-apm*`
+|Monitor access to `metrics-apm*` for storage explorer
+
+|Index
+|`monitor` on `traces-apm*`
+|Monitor access to `traces-apm*` for storage explorer
+|====
+// end::data-streams[]

docs/apm/tab-widgets/storage-explorer-user/widget.asciidoc

@@ -0,0 +1,40 @@
+++++
+<div class="tabs" data-tab-group="apm-app-storage-explorer-reader">
+  <div role="tablist" aria-label="APM app storage explorer-reader">
+    <button role="tab"
+          aria-selected="true"
+          aria-controls="data-streams-tab"
+          id="data-streams">
+      Data streams
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="classic-indices-tab"
+            id="classic-indices"
+            tabindex="-1">
+      Classic APM indices
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="data-streams-tab"
+       aria-labelledby="data-streams">
+++++
+
+include::content.asciidoc[tag=data-streams]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="classic-indices-tab"
+       aria-labelledby="classic-indices"
+       hidden="">
+++++
+
+include::content.asciidoc[tag=classic-indices]
+
+++++
+  </div>
+</div>
+++++