From 815b5b0be9678562b5be0999b295dbd787c98a83 Mon Sep 17 00:00:00 2001
From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com>
Date: Mon, 9 Sep 2024 17:20:38 -0400
Subject: [PATCH] [Docs] Clarify how/when metrics are collected (#40715)

---
 metricbeat/docs/modules/system.asciidoc      | 15 +++++++++++++++
 metricbeat/module/system/_meta/docs.asciidoc | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/metricbeat/docs/modules/system.asciidoc b/metricbeat/docs/modules/system.asciidoc
index a5da08c4fff..2fc3930d844 100644
--- a/metricbeat/docs/modules/system.asciidoc
+++ b/metricbeat/docs/modules/system.asciidoc
@@ -29,6 +29,21 @@ https://gitlab.com/apparmor/apparmor/wikis/TechnicalDoc_Proc_and_ptrace[AppArmor
 and other LSM software], even though the System module doesn't use `ptrace`
 directly.
 
+[TIP] 
+.How and when metrics are collected
+==== 
+Certain metrics monitored by the System module require multiple values to be 
+collected.
+For example, the `system.process.cpu.total.norm.pct` field reports the percentage
+of CPU time spent by the process since the last event. For this percentage to be
+determined, the process needs to appear at least twice so that a performance delta
+can be calculated. 
+
+Note that in some cases a field like this may be missing from the System module
+metricset if the process has not been available long enough to be included in 
+two periods of metric collection.
+====
+
 [float]
 === Dashboard
 
diff --git a/metricbeat/module/system/_meta/docs.asciidoc b/metricbeat/module/system/_meta/docs.asciidoc
index 8a106240d78..3b3dc461ebe 100644
--- a/metricbeat/module/system/_meta/docs.asciidoc
+++ b/metricbeat/module/system/_meta/docs.asciidoc
@@ -18,6 +18,21 @@ https://gitlab.com/apparmor/apparmor/wikis/TechnicalDoc_Proc_and_ptrace[AppArmor
 and other LSM software], even though the System module doesn't use `ptrace`
 directly.
 
+[TIP] 
+.How and when metrics are collected
+==== 
+Certain metrics monitored by the System module require multiple values to be 
+collected.
+For example, the `system.process.cpu.total.norm.pct` field reports the percentage
+of CPU time spent by the process since the last event. For this percentage to be
+determined, the process needs to appear at least twice so that a performance delta
+can be calculated. 
+
+Note that in some cases a field like this may be missing from the System module
+metricset if the process has not been available long enough to be included in 
+two periods of metric collection.
+====
+
 [float]
 === Dashboard