Download FirstLook tool for gathering performance related information.

NAME
FirstLook - collect time correlated performance information using standard tools

SYNOPSIS

start_look [-a] [-c {minutes}] [-s] [-l] [-v] [-t] [-i seconds] -O
snap_look
stop_look

WARNING

FirstLook options must not be used unless specifically requested by the support engineer. Without options, watcher should have no impact on a production environment. FirstLook has been run in
at least 2500 customer systems. Using options without careful consideration could cause a severe impact to the system under observation.

DESCRIPTION

FirstLook is a suite of scripts used to collect serveral system metrics in a time correlated manner. FirstLook uses standard tools such as iostat, vmstat, vxstat, etc. It can be extended to include any arbitrary script or program in it's execution enviroment. By default, Firstlook will collect data at one
minute intervals. It will, by default, keep the last 60 minutes of data and runs continuously. The information collected is stored in a directory in a format that includes the data collected, the command used to get the data, and the time that data was collected. The main body of the watcher script runs
at a higher priority to give it a better chance of maintaining a stable time base.

To install FirstLook, simply untar the tarball and run start_look with any option requested by the engineer that will do the analysis. There may be additional files if the investigating engineer needs to make modifications to FirstLook's environment. Start_look is the only way to start FirstLook. To terminate FirstLook, use stop_look.

FirstLook will automatically create a tar file of the log directory in the install dircectory when it terminates. It could take up to 60 seconds for watcher to terminater nicely.

Snap_look should be used when a snapshot of the log is desired without stopping FirstLook. It will create a tarball in the install directory with a file name the includes the snapshot time.

WHAT IT DOES

FirstLook attempts to create a data collection environment where the proximity of the data collected is better defined in the time domain. It does this by maintaining a regular time base from which standard (and non-standard, if desired) commands are executed. It also defines a way of storing the data such that data from different sources can be correlated to an event in time. It ain't rocket science, just a combining of existing tools.

FirstLook executes in 5 phases:

1. Startup
2. Phase 1 data collection - parallel execution
3. Phase 2 data collection - Serial execution
4. Phase 3 data collection - Fire and forget
5. Shutdown

FirstLook executes phases 1 thru 3 until it receives the termination signal. FirstLook writes the last log cycle count to $LOCATION/logs/system/last.log.written every cycle.

It will then execute the shutdown executable and terminate.

OPTIONS

The following command line options are supported by FirstLook:

-a	Causes FirstLook to dump a threadlist at the every minute. Since this could take longer than 60 seconds, a lock in put around it to prevent more than one thread dump to run at any given time
-c <MINUTES>	By default, FirstLook keeps 60 minutes of data. This option is used to change that time period. There is no reason to use this option under most conditions.
-i <SECONDS>	This is used to change the amount of time that Phase 1 commands are allowed to collect data before FirstLook begins executing Phase 2 and 3 commands. This will, in effect, changes the number of seconds that iostat, vmstat, and mpstat commands will run. Phase 1 commands execute in parallel. See below for details of watcher operation. The default is 5 seconds.
-l (solaris only)	Enable collection of lockstat data.
-L (solaris only)	Use old lockstat style
-O	Overlap phase 1 and phase 2
-p	Force use of ucb/att ps even if system has prstat
-s	Create a tarball of the log directory at the end of each cycle (-c time).A tar file will be created in the watcher home directory every time it is about to wrap (overwrite) the files in the log directory.
-t	Run FirstLook with a normal priority. By default, FirstLook runs in a higher than normal priority class. Even though the script may run in higher class, not all of its children do.
-v	Disable collection of the VxVM volume stats.

STARTUP

At startup, watcher creates the necessary log directory structure and saves information regarding the platform on which it is running. This includes, but is not limited to:

1. FirstLook configuration information
2. uname
3. prtdiag
4. patches
5. Mount information
6. Loaded modules
7. vxprint -ht
8. vxdisk list

It also makes some determination of the availablity of some tools it might need and sets up the execution environment.

If the file Vstartup.cmd exists in the watcher directory and is executable, it will be executed just before the main data collection script is started. It can be any executable type.

PHASE 1 - Parallel execution

Commands are exectuted in parallel. FirstLook will delay -i seconds to allow the commands to complete. The following commands are executed by FirstLook 3.0, if applicable to the platform.

1. vmstat 1 {-i seconds}
2. iostat -Cnxe 1 {-i seconds}
3. mpstat 1 {-i seconds}
4. kstat -p
5. ipcs -A
6. swap -l
7. phase1.cmd, if exists and executable

PHASE 2 - Serial execution

Commands are executed serially. FirstLook waits until each commmand finishes before proceeding to the next. The following commands are executed during this phase.

1. A profiling and/or lock contention lockstat
2. both ucb and att ps's or prstat
3. phase3.cmd, if exists and executable

The actual commands vary dependent upon what is supported by the Unix/Linux version. If the -O switch is specified, phase 2 commands execute without waiting for phase 1 to complete.

PHASE 3 - Fire and forget

Commands in this phase are executed in background. These are also executed at normal system priority. These command usually have a lock mechanism to prevent more than on from running at a time because some may
take longer that the 60 second cycle time of watcher. They also usually require some extra setup. The Veritas vxstat is run if VxVM is installed and there are disk groups. The Sun ACT command is executed if CTEact installed and the -a flag is on the command line.

There is also logic to get Veritas' odmstat, qiostat, and vxfsstat.

If phase3.cmd exists and is exectutable, it will be executed.

EXPORTED SHELL VARIABLES

To make life easier on subshells, watcher exports some internal variables.

1. adt - date string
2. LOCATION - path to watcher directory
3. PWATCH - current cycle count for file extension
4. WATCH - current cycle
5. VP1_SECONDS - number of seconds watcher will pause for
phase1 commands. Used as count for mpstat, iostat,
vmstat.

PHASE COMMAND FILES

While phase command files can be any exectuable type, they are expected to behave within the expected behavior for the phase they run in. The phase1.cmd script is expected to completed within VP1_SECONDS (default 5).The phase2.cmd script should complete quick enough so that the 60 second cycle time isn't violated. The phase3.cmd script should make sure that no more than one is running at a time. It can exceed the 60 second cycle time.

WATCHER OUTPUT

FirstLook data is stored in $LOCATION/logs. Each file is named from the command that generated the data and with a zero filled 3 digit cycle number as the extension. All files with the same extention can be assumed to have executed withing the same minute. Usually overlapping or within a few second of each other.

The first line of the data file must contain a data/time stamp and the command that generated the data. The data follows immediately after the ident line.

Download: After downloading the file unzip using winzip and then use any SFTP client like FileZilla, WinSCP etc to tranfer the content to desired box and then run it. Please take a look at the WARNING message before running this tool