Documentation update

docs/binaries.rst

@@ -0,0 +1,93 @@
+====================
+Scripts and Binaries
+====================
+
+*******************************
+Embedded Scripts in the TA-nmon
+*******************************
+
+**nmon_helper:**
+
+ * bin/nmon_helper.sh:
+
+This shell script is being used by the application to launch Nmon binaries whenever it is detected as required.
+
+It is as well responsible in launching the fifo_reader scripts. (introduced in version 1.3.x)
+
+**fifo_reader:**
+
+* bin/fifo_reader.pl
+* bin/fifo_reader.py
+* bin/fifo_reader.sh
+
+These scripts are continuously running as back ground processes on server running the technical addons.
+Their purpose is to read the fifo files (named pipe) nmon processes are writing to, and extract the different typologies of data from them nmon data
+
+**fifo_consumer:**
+
+* bin/fifo_consumer.sh
+
+This script is scheduled by default to run every 60 seconds.
+Its purpose to recompose the nmon flaw of data to be parsed by the nmon parser scripts. (see bellow)
+
+**nmon_parser:**
+
+ * bin/nmon2csv.sh | bin/nmon2csv.py | bin/nmon2csv.pl:
+
+Shell / Python / Perl scripts used to manage and process Nmon raw data into multiple csv files being indexed by Splunk
+
+The Shell script is a wrapper script to Python / Perl scripts. (decision is made on local interpreter avaibility with Python as the default choice)
+
+**nmon_cleaner:**
+
+ * bin/nmon_cleaner.sh / bin/nmon_cleaner.py / nmon_cleaner.pl
+
+Shell / Python / Perl scripts used to manage retention and purge of old nmon data.
+
+Alternatively, it will also ensure that no outdated csv data is being left by Splunk in Performance and Configuration repositories
+
+The Shell script is a wrapper script to Python / Perl scripts. (decision is made on local interpreter avaibility with Python as the default choice)
+
+********************************
+Embedded Binaries in the TA-nmon
+********************************
+
+*Since the major release V1.7.4, the core application does bring any data generation releated components*
+
+Scripts and binaries are shared in exactly same versions between the PA-nmon add-on and the TA-nmon add-on.
+
+The Applications brings Nmon binaries for Linux vendors and Solaris OS, on AIX the application will only try to use the version shipped with system
+
+**For Linux OS:**
+
+ * bin/linux: Main directory for Linux specific Nmon binaries
+ * bin/linux/centos: 32/64 bits binaries for Centos
+ * bin/linux/debian: 32/64 bits binaries for Debian GNU/Linux
+ * bin/linux/fedora: 32/64 bits binaries for Fedora project
+ * bin/linux/generic: 32/64/ia64/power/mainframe binaries compiled for generic Linux
+ * bin/linux/mint: 32/64 bits binaries for Linux Mint
+ * bin/linux/opensuse: 32/64 bits binaries for Linux Opensuse
+ * bin/linux/ol: 32/64 bits binaries for Oracle Linux
+ * bin/linux/rhel: 32/64/ia64/mainframe/power binaries for Redhat Entreprise Server
+ * bin/linux/sles: 32/64/ia64/mainframe/power binaries for Suse Linux Entreprise Server
+ * bin/linux/ubuntu: 32/64/power/arm binaries for Ubuntu Linux
+ * bin/linux/arch: 32/64 bits binaries for Archlinux
+ * bin/raspbian: arms binaries for Raspbian Linux
+
+Most of these binaries comes from the official Nmon Linux project site.
+On x86 processor and for Centos / Debian / Ubuntu / Oracle Linux these binaries are being compiled by myself using Vagrant and Ansible automation. (See https://github.com/guilhemmarchand/nmon-binaries)
+
+Associated scripts resource (nmon_helper.sh) will try to use the better version of Nmon available, it will fall back to generic or system embedded if none of specially compiled versions can fit the system.
+
+**For Solaris OS:**
+
+*sarmon binaries for Oracle Solaris x86 and Sparc:*
+
+ * bin/sarmon_bin_i386: sarmon binaries for Solaris running on x86 arch
+ * bin/sarmon_bin_sparc: sarmon binaris for Solaris running on sparc arch
+
+sarmon binaries comes from the official sarmon site project.
+
+**For AIX**:
+
+Nmon is shipped within AIX by default with topas-nmon binary.

docs/deployment.rst

@@ -0,0 +1,13 @@
+##########
+Deployment
+##########
+
+Deploying the TA-nmon is nothing more very simple, basically it is just about extracting the TA-nmon tgz archive and restart Splunk.
+
+**However, Splunk is an highly distributable solution and some good practices have to be respected, please consult the Nmon Performance core documentation:**
+
+* Standalone deployment: http://nmon-for-splunk.readthedocs.io/en/latest/installation_standalone.html
+
+* Distributed deployment: http://nmon-for-splunk.readthedocs.io/en/latest/installation_distributed.html
+
+* Splunk Cloud deployment: http://nmon-for-splunk.readthedocs.io/en/latest/installation_splunkcloud.html

docs/deployment_matrix.rst

@@ -0,0 +1,42 @@
+#################
+Deployment Matrix
+#################
+
+What goes where ?
+-----------------
+
+* The TA-nmon is provided within the resources directory of the core application
+
+* The TA-nmon is also available for download as an independent application in Splunk base: https://splunkbase.splunk.com/app/3248
+
+**Standalone deployment: A single Splunk instance does all**
+
++------------------------+---------------+
+| Splunk Instance        | TA-nmon       |
+| (role)                 |               |
++========================+===============+
+| Standalone             | X (optional)  |
++------------------------+---------------+
+
+*The TA-nmon provides nmon performance and configuration collection for the host than runs the add-on, which is optional*
+
+**Distributed deployment:**
+
++--------------------------------------------+---------------------+
+| Splunk Instance                            | TA-nmon             |
+| (role)                                     |                     |
++============================================+=====================+
+| Search head (single instance or clustered) |    X (optional)     |
++--------------------------------------------+---------------------+
+| Indexer (single instance or clustered)     |                     |
++--------------------------------------------+---------------------+
+| Master node                                |    X (optional)     |
++--------------------------------------------+---------------------+
+| Deployment servers                         |    X (optional)     |
++--------------------------------------------+---------------------+
+| Heavy Forwarder                            |    X                |
++--------------------------------------------+---------------------+
+| Universal Forwarder                        |    X                |
++--------------------------------------------+---------------------+
+
+*The TA-nmon provides nmon performance and configuration collection for the host than runs the add-on, which is optional*

docs/footprint.rst

@@ -1,6 +1,6 @@
-################
-System footprint
-################
+###############################
+System footprint and benchmarks
+###############################
 
 ===========================
 What does cost the TA-nmon?
@@ -42,25 +42,101 @@ To avoid these risks, and limit at the maximum the amount of resources to be use
 IBM AIX BENCHMARKS:
 -------------------
 
-
 **IBM AIX 6.1 ON POWER8 / Entitled 0.2 / VirtualCPUs 1:**
 
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Perl interpreter*
+
+*lpar usage over 24 hours:*
+
+*lpar usage_zoom over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+
 **IBM AIX 7.1 ON POWER8 / Entitled 0.2 / VirtualCPUs 1:**
 
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Perl interpreter*
+
+*lpar usage over 24 hours:*
+
+*lpar usage_zoom over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+
 **IBM AIX 7.2 ON POWER8 / Entitled 0.2 / VirtualCPUs 1:**
 
-*lpar usage:*
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2*
+
+*lpar usage over 24 hours:*
 
 .. image:: img/bench_AIX/AIX_72/lpar_full.png
    :alt: img/bench_AIX/AIX_72/lpar_full.png
    :align: center
 
-*lpar usage_zoom:*
+*lpar usage_zoom over 24 hours:*
 
 .. image:: img/bench_AIX/AIX_72/lpar_zoom.png
    :alt: img/bench_AIX/AIX_72/lpar_zoom.png
    :align: center
 
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+LINUX BENCHMARKS:
+-----------------
+
+**SUSE Linux 11.4 BE (IBM POWER 8)**
+
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Perl interpreter, 1 CPU*
+
+*CPU % usage over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+**SUSE Linux 12.2 LE (IBM POWER 8)**
+
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Python interpreter, 1 CPU*
+
+*CPU % usage over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+**Red Hat Linux 6.9 BE (IBM POWER 8)**
+
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Perl interpreter, 1 CPU*
+
+*CPU % usage over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+**RedHat Linux 7.3 LE (IBM POWER 8)**
+
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Python interpreter, 1 CPU*
+
+*CPU % usage over 24 hours:*
+
+*Average I/O over 24 hours:*
+
+*splunkd core CPU usage / Memory usage over 24 hours:*
+
+**Ubuntu 16.04 LTS (IBM POWER 8)**
+
+*date 27/03/2013, TA-nmon release 1.3.05, Splunk Universal Forwarder 6.5.2, Python interpreter, 1 CPU*
 
+*CPU % usage over 24 hours:*
 
+*Average I/O over 24 hours:*
 
+*splunkd core CPU usage / Memory usage over 24 hours:*

docs/index.rst

@@ -25,7 +25,7 @@ Overview:
 ---------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    about
    releasenotes
@@ -34,3 +34,7 @@ Overview:
    os_compatibility
    processing_overview
    footprint
+   binaries
+   requirements
+   deployment_matrix
+   deployment

docs/os_compatibility.rst

@@ -2,9 +2,9 @@
 Operating Systems compatibility
 ###############################
 
-=============
-Compatible OS
-=============
+================
+OS compatibility
+================
 
 **The TA-nmon is compatible with any version of:**
 
@@ -15,9 +15,9 @@ Compatible OS
 * Linux ARM
 * Solaris 10, Solaris 11 on Sparc and x86
 
-=============
-Qualification
-=============
+================
+OS certification
+================
 
 **Here is a non exhaustive list of systems and version that the TA-nmon is been extensively qualified:**
 

docs/requirements.rst

@@ -0,0 +1,17 @@
+##############
+pre-requisites
+##############
+
+**The pre-requisites to run the TA-nmon are quite simple:**
+
+* Python 2.7.x interpreter
+
+By default, the TA-nmon tries to use the locally available Python 2.7.x interpreter.
+
+Note that Splunk Enterprise embeds its own Python 2.7.x interpreter.
+
+* Perl 5.x or higher with perl-Time-HiRes
+
+If Python 2.7.x is not available in your systems (very likely on AIX, likely on old Linux and Solaris flavours), the TA-nmon will fall back to Perl.
+
+In such a case, the Perl module "perl-Time-HiRes" must be installed, this can be the case on many systems (AIX does) but some may not have it installed by default.