docs: Transaction metrics reference (#4345)

Co-authored-by: Andrew Wilkins <[email protected]>

Author: bmorelli25

docs/configure-kibana-endpoint.asciidoc

@@ -1,6 +1,10 @@
 [[setup-kibana-endpoint]]
 == Configure the Kibana endpoint
 
+++++
+<titleabbrev>Kibana endpoint</titleabbrev>
+++++
+
 Configuring the Kibana endpoint is required for
 {kibana-ref}/agent-configuration.html[APM Agent configuration in Kibana].
 You configure the endpoint in the `apm-server.kibana` section of the

docs/configuring.asciidoc

@@ -10,25 +10,48 @@
 include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 
 * <<configuration-process>>
-* <<configuring-output>>
-* <<configuration-ssl-landing>>
 * <<configuration-template>>
 * <<ilm-reference>>
+* <<configuration-instrumentation>>
 * <<jaeger-reference>>
-* <<configuration-logging>>
+* <<configuration-kerberos>>
 * <<setup-kibana-endpoint>>
-* <<configuration-rum>>
-* <<configuration-instrumentation>>
+* <<configuration-logging>>
+* <<configuring-output>>
 * <<configuration-path>>
+* <<configuration-rum>>
+* <<configuration-ssl-landing>>
+* <<transaction-metrics>>
 * <<using-environ-vars>>
 
 --
 
 include::./configuration-process.asciidoc[]
 
+include::{libbeat-dir}/template-config.asciidoc[]
+
+include::./ilm-reference.asciidoc[]
+
+include::{libbeat-dir}/shared-instrumentation.asciidoc[]
+
+include::./jaeger-reference.asciidoc[]
+
+ifndef::no_kerberos[]
+include::{libbeat-dir}/shared-kerberos-config.asciidoc[]
+endif::[]
+
+include::./configure-kibana-endpoint.asciidoc[]
+
+include::{libbeat-dir}/loggingconfig.asciidoc[]
+
 :no-redis-output:
 include::{libbeat-dir}/outputconfig.asciidoc[]
 
+include::{libbeat-dir}/shared-path-config.asciidoc[]
+
+include::./configuration-rum.asciidoc[]
+
+// BEGIN SSL SECTION --------------------------------------------
 [[configuration-ssl-landing]]
 == SSL/TLS settings
 
@@ -49,24 +72,9 @@ include::{libbeat-dir}/shared-ssl-config.asciidoc[]
 :leveloffset: -1
 
 include::ssl-input-settings.asciidoc[]
+// END SSL SECTION --------------------------------------------
 
-See <<securing-apm-server,Securing APM Server>> for more information.
-
-include::{libbeat-dir}/template-config.asciidoc[]
-
-include::./ilm-reference.asciidoc[]
-
-include::./jaeger-reference.asciidoc[]
-
-include::{libbeat-dir}/loggingconfig.asciidoc[]
-
-include::./configure-kibana-endpoint.asciidoc[]
-
-include::./configuration-rum.asciidoc[]
-
-include::{libbeat-dir}/shared-instrumentation.asciidoc[]
-
-include::{libbeat-dir}/shared-path-config.asciidoc[]
+include::./transaction-metrics.asciidoc[]
 
 :standalone:
 include::{libbeat-dir}/shared-env-vars.asciidoc[]

docs/copied-from-beats/docs/outputs-list.asciidoc

@@ -83,9 +83,5 @@ ifdef::requires_xpack[]
 endif::[]
 include::{libbeat-outputs-dir}/codec/docs/codec.asciidoc[]
 endif::[]
-ifndef::no_kerberos[]
-include::{libbeat-dir}/shared-kerberos-config.asciidoc[]
-endif::[]
-
 
 //# end::outputs-include[]

docs/transaction-metrics.asciidoc

@@ -0,0 +1,98 @@
+[x-pack]
+[[transaction-metrics]]
+== Configure transaction metrics
+
+experimental[]
+
+++++
+<titleabbrev>Transaction metrics</titleabbrev>
+++++
+
+When enabled, {beatname_uc} produces transaction histogram metrics that are used to power the APM app.
+Shifting this responsibility from APM app to APM Server results in improved query performance and removes the need to store unsampled transactions.
+
+Example config file:
+
+["source","yaml"]
+----
+apm-server:
+  aggregation:
+    transactions:
+      enabled: true
+      interval: 1m
+  sampling:
+    keep_unsampled: false
+----
+
+[float]
+[[configuration-aggregation]]
+=== Configuration options: `apm-server.aggregation.transactions.*`
+
+[[transactions-enabled]]
+[float]
+==== `enabled`
+
+Enables the collection and publishing of transaction metrics.
+This setting improves query performance in the APM app.
+
+Default: `false`.
+
+IMPORTANT: To prevent inaccuracies in the APM app, transaction metrics must also be enabled in
+Kibana with `xpack.apm.searchAggregatedTransactions`.
+See {kibana-ref}/apm-settings-in-kibana.html[APM app settings] for more information.
+
+[[transactions-interval]]
+[float]
+==== `interval`
+
+Controls the frequency of metrics publication.
+
+Default: `1m`.
+
+[[transactions-max_groups]]
+[float]
+==== `max_groups`
+
+Maximum number of transaction groups to keep track of.
+Once exceeded, APM Server devolves into recording a metrics document for each transaction that is not in one
+of the transaction groups being tracked.
+
+Default: `1000`.
+
+[[transactions-hdrhistogram_significant_figures]]
+[float]
+==== `hdrhistogram_significant_figures`
+
+The fixed, worst-case percentage error (specified as a number of significant digits)
+to maintain for recorded metrics.
+Supported values are `1` through `5`.
+See {ref}/search-aggregations-metrics-percentile-aggregation.html#_hdr_histogram_2[HDR histogram] for more information.
+
+Default: `2`.
+
+[[transactions-lru_size]]
+[float]
+==== `rum.user_agent.lru_size`
+
+This option controls the cache size of RUM user-agent strings.
+
+RUM "page-load" transactions are aggregated on the user-agent name, which requires user-agent parsing.
+To avoid parsing every user-agent, a cache of user-agent strings is maintained.
+
+Default: `5000`.
+
+[float]
+[[configuration-sampling]]
+=== Configuration options: `apm-server.sampling.*`
+
+[[sampling-keep_unsampled]]
+[float]
+==== `keep_unsampled`
+
+Controls the recording of unsampled transaction documents.
+Dropping unsampled documents (`keep_unsampled: false`) reduces APM's storage consumption.
+
+Default: `true`.
+
+IMPORTANT: Unsampled transactions should only be dropped when `apm-server.aggregation.transactions.enabled` is `true`,
+otherwise, the APM app will report inaccurate metrics.