From 3af2a35174ff5fa3a078be19020892952bf1fd53 Mon Sep 17 00:00:00 2001
From: Jeff Huss <jeffhuss@amazon.com>
Date: Tue, 23 Aug 2022 15:11:13 -0700
Subject: [PATCH] Relocated perf analyzer installation steps to the appropriate
 page (#963)

Signed-off-by: JeffH-AWS <jeffhuss@amazon.com>

Signed-off-by: JeffH-AWS <jeffhuss@amazon.com>
(cherry picked from commit 3ac63b596cda88d190924ccdf082f391bfd8e793)
---
 _monitoring-plugins/pa/index.md | 91 +++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/_monitoring-plugins/pa/index.md b/_monitoring-plugins/pa/index.md
index 7c5b37aede..14548bdd38 100644
--- a/_monitoring-plugins/pa/index.md
+++ b/_monitoring-plugins/pa/index.md
@@ -21,6 +21,7 @@ npm install -g @aws/opensearch-perftop
 
 ![PerfTop screenshot]({{site.url}}{{site.baseurl}}/images/perftop.png)
 
+For enabling Performance Analyzer with tarball installations of OpenSearch, see [Configure Performance Analyzer for Tarball Installation](#configure-performance-analyzer-for-tarball-installation).
 
 ## Get started with PerfTop
 
@@ -101,3 +102,93 @@ certificate-file-path = specify_path
 
 private-key-file-path = specify_path
 ```
+
+## Configure Performance Analyzer for Tarball Installation
+
+In a tarball installation, Performance Analyzer collects data when it is enabled. But in order to read that data using the REST API on port 9600, you must first manually launch the associated reader agent process:
+
+1. Make Performance Analyzer accessible outside of the host machine
+
+   ```bash
+   cd /usr/share/opensearch # navigate to the OpenSearch home directory
+   cd config/opensearch-performance-analyzer/
+   vi performance-analyzer.properties
+   ```
+
+   Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`:
+
+   ```
+   # ======================== OpenSearch performance analyzer plugin config =========================
+
+   # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
+
+   # WebService bind host; default to all interfaces
+   webservice-bind-host = 0.0.0.0
+
+   # Metrics data location
+   metrics-location = /dev/shm/performanceanalyzer/
+
+   # Metrics deletion interval (minutes) for metrics data.
+   # Interval should be between 1 to 60.
+   metrics-deletion-interval = 1
+
+   # If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
+   # metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This can be useful, if you are archiving
+   # the files and wouldn't like for them to be cleaned up.
+   cleanup-metrics-db-files = true
+
+   # WebService exposed by App's port
+   webservice-listener-port = 9600
+
+   # Metric DB File Prefix Path location
+   metrics-db-file-prefix-path = /tmp/metricsdb_
+
+   https-enabled = false
+
+   #Setup the correct path for certificates
+   certificate-file-path = specify_path
+
+   private-key-file-path = specify_path
+
+   # Plugin Stats Metadata file name, expected to be in the same location
+   plugin-stats-metadata = plugin-stats-metadata
+
+   # Agent Stats Metadata file name, expected to be in the same location
+   agent-stats-metadata = agent-stats-metadata
+   ```
+
+1. Make the CLI executable:
+
+   ```bash
+   sudo chmod +x ./bin/performance-analyzer-agent-cli
+   ```
+
+1. Launch the agent CLI:
+
+   ```bash
+   OPENSEARCH_HOME="$PWD" OPENSEARCH_PATH_CONF="$PWD/config" ./bin/performance-analyzer-agent-cli
+   ```
+
+1. In a separate window, enable the Performance Analyzer plugin:
+
+   ```bash
+   curl -XPOST localhost:9200/_plugins/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'
+   ```
+
+   If you receive the `curl: (52) Empty reply from server` error, you are likely protecting your cluster with the security plugin and you need to provide credentials. Modify the following command to use your username and password:
+
+   ```bash
+   curl -XPOST https://localhost:9200/_plugins/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k
+   ```
+
+1. Finally, enable the Root Cause Analyzer (RCA) framework
+
+   ```bash
+   curl -XPOST localhost:9200/_plugins/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'
+   ```
+
+   Similar to step 4, if you run into `curl: (52) Empty reply from server`, run the command below to enable RCA
+
+   ```bash
+   curl -XPOST https://localhost:9200/_plugins/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k
+   ```
\ No newline at end of file