kdavyd / sparta Goto Github PK

README file for SPARTA (System Performance And Reporting Tool Analyser)
=======================================================================

This package contains a number of scripts and utilities that need to
be installed in order to gather performance data from a NexentaStor
appliance.


Installation
------------
In the directory where this package has been unpacked, run the
installer.sh script to install.  This will create a /perflogs directory
and copy the scripts and utilities to that directory.  If there is
insufficient space in the syspool you will not be able to continue
(at the time of writing this is 1GB).

# ./installer.sh

Once installed you'll need to invoke the /perflogs/scripts/sparta.sh
script with arguments (see below) to start collecting data.


Running
-------
The sparta.sh script takes the following arguments but is typically
invoked using 'sparta.sh <command>' where the command may be one
of the following:

   sparta.sh start	 : Starts the data collection
   sparta.sh stop 	 : Stops any active dtrace scripts
   sparta.sh status	 : Displays which dtrace scripts are running
   sparta.sh tarball	 : Generates a tarball of /perflogs (can be quite LARGE)
   sparta.sh version     : Displays the version of SPARTA

There are several optional switches that can be supplied to enable
NFS, CIFS or iSCSI monitoring thus:

   sparta.sh -N	start : Enable NFS scripts
   sparta.sh -C start : Enable CIFS scripts
   sparta.sh -I start : Enable iSCSI scripts
   sparta.sh -S start : Enable STMF (COMSTAR) scripts
        
*** NOTE ***
  These will be in *addition* to any pre-configured protocol that may have been
  selected by the installer utility.

If you don't specify a command using the switch, then nothing will happen, thus 
it's imperitive a command be given. 

[ It also accepts a -h | -help | -? switch to dump out a help page ]


Additional Switches
-------------------
There are additional switches that may be supplied to sparta.sh thus:

  -p <zpool_list>	: Invoke ZFS specific monitoring on the given list
			  of pools.  The zpool_list should be separated by
			  commas, eg:

			# sparta.sh -p vmachines,datstore

  -P <protocol_list>	: Enable explicit protocol tools for the given list
		 	  of protcols (cifs, iscsi, nfs or stmf), separated by
			  commas, eg:

			# sparta.sh -P nfs,cifs

			  Specifying the protocol list this way will disable
			  all non-specified protocols, regardless of whether
		          they have been set by the installation process.


Automatic Updates
-----------------
SPARTA will attempt to connect to an Internet based server in order to check
for and download an updated version of itself.
It does this automatically when invoked, however if you wish to skip the auto
update feature because the appliance is behind a firewall or the auto update
feature failed to work, you should invoke sparta.sh with a -u switch.
This takes either a yes or no keyword, to either enable the automatic update
feature (enabled by default) or bypass the feature.

Thus to bypass the automatic update check, use:

  sparta.sh -u no start



SPARTA progress
---------------
The script runs through numerous dtrace scripts and utilities, collecting
data as it progresses and outputing to the screen the status of the
collection.

You may also monitor the sparta.log file in the /perflogs directory which
contains slightly more detail.

Ideally the script should be run once when the appliance is not
experiencing performance issues, such that a baseline can be established.
If a baseline is to be established, collect between 30 - 60 minutes of
dtrace data before stopping the script and then generating a tarball 
which can then be uploaded to Nexenta for further analysis.

Example:

# cd /perflogs/scripts
# ./sparta.sh start

(wait 30 - 60 minutes)

# ./sparta.sh stop
# ./sparta.sh tarball

The script has been designed to be left running in order to capture data
when a performance problem arises, so start SPARTA and leave it running
however it is presently advisable to monitor the space usage of the /perflogs
directory to ensure this doesn't fill up too rapidly.



Post Run
--------
After the script has been run, you'll be asked whether you wish to generate
a tarball of the collected data *SO FAR*.
Bear in mind this is usually about 3 minutes worth of data, so it is barely
any data to work with and possibly a useable baseline during a quiet period.

If you answer yes a tarball will be created.
Alternatively you can run:

  sparta.sh tarball

and this will generate a tarball.
Once a tarball has been generated that captures a performance problem, please
upload this to the Nexenta FTP server.



Example tarball output
----------------------

# /perflogs/scripts/sparta.sh tarball
Generating a tarball of collected performance data
Creating tarball ... done
Compressing tarball ... done

A snapshot of the currently collected data has been collected.
Please upload /var/tmp/nexenta_perf_data-2013-10-23_16:58:42.tar.gz to ftp.nexenta.com:/upload/<CASE_REF>
where <CASE_REF> should be substituted for the case reference number
of the performance issue is being investigated.

Please update your case reference in http://login.salesforce.com 
or contact [email protected] if there are additional questions.