From 0d8f942c423927586691e0d3f78d78a72801d4f8 Mon Sep 17 00:00:00 2001
From: Michel Laterman <82832767+michel-laterman@users.noreply.github.com>
Date: Fri, 4 Mar 2022 10:15:31 -0800
Subject: [PATCH] Add metrics buffer documentation (#1627)

* Add metrics buffer documentation

* Apply suggestions from code review

Co-authored-by: DeDe Morton <dede.morton@elastic.co>

Co-authored-by: DeDe Morton <dede.morton@elastic.co>
---
 commands.asciidoc                                        | 2 +-
 .../configuration/elastic-agent-monitoring.asciidoc      | 9 +++++++++
 troubleshooting/troubleshooting.asciidoc                 | 2 ++
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/commands.asciidoc b/commands.asciidoc
index b13eeb8885..d015d210eb 100644
--- a/commands.asciidoc
+++ b/commands.asciidoc
@@ -36,7 +36,7 @@ Gather diagnostics information from the {agent} and applications it's running.
 
 If no options are specified, this command displays version numbers and application metadata.
 
-If `collect` is specified, it produces an archive containing application metadata, configuration information, the policy, and any local logs.
+If `collect` is specified, it produces an archive containing application metadata, configuration information, the policy, local logs, and metics data (if the buffer is enabled).
 
 Note that *credentials are not redacted* in the archive; they may appear in plain text in the configuration or policy files inside the archive.
 
diff --git a/elastic-agent/configuration/elastic-agent-monitoring.asciidoc b/elastic-agent/configuration/elastic-agent-monitoring.asciidoc
index b6a353429c..0d95104b34 100644
--- a/elastic-agent/configuration/elastic-agent-monitoring.asciidoc
+++ b/elastic-agent/configuration/elastic-agent-monitoring.asciidoc
@@ -26,6 +26,9 @@ agent.monitoring:
   pprof.enabled: false
   # specifies output to be used
   use_output: monitoring
+  http:
+    # exposes a /buffer endpoint that holds a history of recent metrics
+    buffer.enabled: false
 ----
 
 To turn off monitoring, set `agent.monitoring.enabled` to `false`. When set to
@@ -42,3 +45,9 @@ The `agent.monitoring.pprof.enabled` option controls whether the {agent} and {be
 by default. Data produced by these endpoints can be useful for debugging but present a
 security risk. It is recommended that this option remains `false` if the monitoring endpoint
 is accessible over a network.
+
+The `agent.monitoring.http.buffer.enabled` option controls whether the {agent} and {beats}
+collect metrics into an in-memory buffer and expose these through a `/buffer` endpoint.
+It is set to `false` by default. This data can be useful for debugging or if the {agent}
+has issues communicating with {es}. Enabling this option may slightly increase process
+memory usage.
diff --git a/troubleshooting/troubleshooting.asciidoc b/troubleshooting/troubleshooting.asciidoc
index 7f0b5e2543..b5e3f9a5e5 100644
--- a/troubleshooting/troubleshooting.asciidoc
+++ b/troubleshooting/troubleshooting.asciidoc
@@ -338,6 +338,8 @@ These will need to be manually redacted before the archive is shared.
 
 The diagnostics command is also able to collect `pprof` data in the archive if the `--pprof` flag is passed:
 
+If `agent.monitoring.http.buffer.enabled` is set to `true`, the archive will also contain recent metrics from the {agent} and {beats} processes.
+
 [source,shell]
 ----
 elastic-agent diagnostics collect --pprof