docs: Tail-based sampling

docs/apm-input-settings.asciidoc

@@ -434,3 +434,111 @@ Anonymous Event rate limit (event limit)
 // end::anonymous_rate_limit_event_limit-setting[]
 
 // =============================================================================
+
+// tag::tail_sampling_enabled-setting[]
+|
+[id="input-{input-type}-tail_sampling_enabled"]
+Enable Tail-based sampling
+
+| (bool) Enable and disable tail-based sampling.
+
+*Default:* `false`
+// end::tail_sampling_enabled-setting[]
+
+// =============================================================================
+
+// tag::tail_sampling_interval-setting[]
+|
+[id="input-{input-type}-tail_sampling_interval"]
+Interval
+
+| (duration) Synchronization interval for multiple APM Servers.
+Should be in the order of tens of seconds or low minutes.
+
+*Default:* `1m`
+// end::tail_sampling_interval-setting[]
+
+// =============================================================================
+
+// tag::tail_sampling_policies-setting[]
+|
+[id="input-{input-type}-tail_sampling_policies"]
+Policies
+
+| (`[]policy`) Criteria used to match a root transaction to a sample rate.
+Order is important; the first policy on the list that an event matches is the winner.
+Each policy list must conclude with a default policy that only specifies a sample rate.
+The default policy is used to catch remaining trace events that don’t match a stricter policy.
+
+Required when tail-based sampling is enabled.
+
+// end::tail_sampling_policies-setting[]
+
+// =============================================================================
+
+// tag::sample_rate-setting[]
+|
+[id="input-{input-type}-sample_rate"]
+Sample rate
+
+`sample_rate`
+
+| (int) The sample rate to apply to trace events matching this policy.
+Required in each policy.
+
+// end::sample_rate-setting[]
+
+// =============================================================================
+
+// tag::trace_name-setting[]
+|
+[id="input-{input-type}-trace_name"]
+Trace name
+
+`trace.name`
+
+| (string) The trace name for events to match a policy.
+
+// end::trace_name-setting[]
+
+// =============================================================================
+
+// tag::trace_outcome-setting[]
+|
+[id="input-{input-type}-trace_outcome"]
+Trace outcome
+
+`trace.outcome`
+
+| (string) The trace outcome for events to match a policy.
+Trace outcome can be `success`, `failure`, or `unknown`.
+
+// end::trace_outcome-setting[]
+
+// =============================================================================
+
+// tag::service_name-setting[]
+|
+[id="input-{input-type}-service_name"]
+Service name
+
+`service.name`
+
+| (string) The service name for events to match a policy.
+
+// end::service_name-setting[]
+
+// =============================================================================
+
+// tag::service_env-setting[]
+|
+[id="input-{input-type}-service_env"]
+Service Environment
+
+`service.environment`
+
+| (string) The service environment for events to match a policy.
+
+// end::service_env-setting[]
+
+// =============================================================================

docs/input-apm.asciidoc

@@ -79,4 +79,28 @@ include::./apm-input-settings.asciidoc[tag=anonymous_rate_limit_ip_limit-setting
 include::./apm-input-settings.asciidoc[tag=anonymous_rate_limit_event_limit-setting]
 |===
 
+[float]
+[[apm-input-tail-sampling-settings]]
+=== Tail-based sampling
+
+**Top-level tail-based sampling settings:**
+
+[cols="2*<a"]
+|===
+include::./apm-input-settings.asciidoc[tag=tail_sampling_enabled-setting]
+include::./apm-input-settings.asciidoc[tag=tail_sampling_interval-setting]
+include::./apm-input-settings.asciidoc[tag=tail_sampling_policies-setting]
+|===
+
+**Policy settings:**
+
+[cols="2*<a"]
+|===
+include::./apm-input-settings.asciidoc[tag=sample_rate-setting]
+include::./apm-input-settings.asciidoc[tag=trace_name-setting]
+include::./apm-input-settings.asciidoc[tag=trace_outcome-setting]
+include::./apm-input-settings.asciidoc[tag=service_name-setting]
+include::./apm-input-settings.asciidoc[tag=service_env-setting]
+|===
+
 :input-type!:

docs/legacy/guide/trace-sampling.asciidoc

@@ -12,6 +12,9 @@ For example, a sampling value of `.2` indicates a transaction sample rate of `20
 This means that only `20%` of traces will send and retain all of their associated information.
 The remaining traces will drop contextual information to reduce the transfer and storage size of the trace.
 
+TIP: The APM integration supports both head-based and tail-based sampling.
+Learn more <<sampling,here>>.
+
 [float]
 ==== Why sample?