CacheKit
--------

CacheKit is a collection of perl and shell programs to report on cache 
activity on a Solaris 8 sparc server. Tools for older Solaris and Solaris x86 
are also included in the kit. SE Toolkit programs are also provided. 
The caches the kit reports on are: I$, D$, E$, DNLC, inode cache, 
ufs buffer cache and segmap cache. This kit assists performance tuning.


QuickStart
----------

The tools are ready to run, no compilation required. See the EXAMPLES
file for their usage, or read the scripts themselves. Below is a summary.


Contents
--------

dnlcstat     DNLC (Dircectory Name Lookup Cache) hit statistics. 
	     This cache contains the pathname for a file and the
	     associated vnode.

inodestat    inode cache hit statistics. inodes contain the metadata 
	     for files ("ls -lis" info), and are used heavily during UFS 
	     activity (eg, permission checks).

ufsbufstat   old UFS buffer cache hit statistics. This cache contains 
	     UFS structure blocks - cylinder group blocks, blocks of inodes
	     and their indirects.

segmapstat   segmap cache hit statistics. This cache contains pages of 
	     a file's contents, accessed by system calls read() and write().

segvnstat    segvn page cache hit statistics. This cache contains pages of
             a file's contents, accessed by the system call mmap().
             NOTE: This value is a crude approximation. Check for updates.

fcachestat   statistics for DNLC, inode, ufsbuf, segmap and segvn caches.

gcachestat   GUI version of fcachestat (SE Toolkit only).

showsize     prints maximum cache sizes for several caches; I$/D$, E$, DNLC,
             inode, ufsbuf, segvn.

ccahestat    measures I$, D$, E$ hit statistics one by one and prints out
             summaries. For more accurate measurements of these caches,
             use: icache, dcache, ecache.

icache       I$, Instruction cache hit statistics (L1 cache).

dcache       D$, Data cache hit statistics (L1 cache).

ecache       E$, External cache hit statistics (L2 cache).

kstat_walk   Prints out a tree or list view of the Kstat structure using 
	     the Sun::Solaris::Kstat library (Solaris 8).

dnlcsnoop.d  Watch DNLC events as they happen, including PID details.

dnlcps.d     DNLC statistics per process.


Operating Systems
-----------------

These programs have been written for a Solaris 8 (or newer) sparc server. 
Also included in the kit are programs for older Solaris, and also Solaris x86.
Solaris 10 offers DTrace. Future versions of this kit may include 
DTrace programs.


Install
-------

These scripts do not require compiling, they are ready to run. Copying them 
into your system locations is left as an excercise for the user.


Manifest
--------
./Sol7/fcachestat7	Solaris <= 7 version. Uses "netstat -k"
./Sol7/inodestat7	Solaris <= 7 version. Uses "netstat -k"
./Sol7/dnlcstat7	Solaris <= 7 version. Uses "netstat -k"
./Sol7/ufsbufstat7	Solaris <= 7 version. Uses "netstat -k"
./Sol7/segmapstat7	Solaris <= 7 version. Uses "netstat -k"
./ccachestat		Solaris 8+ version. Uses cpustat
./fcachestat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./dnlcstat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./inodestat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./kstat_walk		Solaris 8+ version. Uses Sun::Solaris::Kstat
./segmapstat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./segvnstat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./showsize		Solaris 8+ version. Uses Sun::Solaris::Kstat
./ufsbufstat		Solaris 8+ version. Uses Sun::Solaris::Kstat
./sparc/dcache		Solaris 8+ sparc. Uses cpustat
./sparc/ecache		Solaris 8+ sparc. Uses cpustat
./sparc/icache		Solaris 8+ sparc. Uses cpustat
./x86/dcache_x86	Solaris 8+ x86. Uses cpustat (see script)
./x86/ecache_x86	Solaris 8+ x86. Uses cpustat (see script)
./x86/icache_x86	Solaris 8+ x86. Uses cpustat (see script)
./EXAMPLES		Examples of using the tools
./README		This file
./SEToolkit/fcachestat.se	SE Toolkit version.
./SEToolkit/dnlcstat.se		SE Toolkit version.
./SEToolkit/gcachestat.se	SE Toolkit version.
./SEToolkit/inodestat.se	SE Toolkit version.
./SEToolkit/segmapstat.se	SE Toolkit version.
./SEToolkit/segvnstat.se	SE Toolkit version.
./SEToolkit/ufsbufstat.se	SE Toolkit version.
./Sol10/dnlcsnoop.d	Solaris 10+ only, uses DTrace.
./Sol10/dnlcps.d	Solaris 10+ only, uses DTrace.
./Sol10/dnlcstat	Solaris 10+ version, DTrace.


Version
-------
Although this kit has an overall version, each program has an individual
version number (see the programs, or check for newer versions).


Website
-------
http://www.brendangregg.com/cachekit.html
(or use a search engine)


See Also
--------
more /usr/bin/kstat				# Solaris 8
cpustat -h					# Solaris 8
man cpustat					# Solaris 8
netstat -k					# unsupported
http://www.sun.com/sun-on-net/performance	# Sun's performance website
http://www.setoolkit.com			# SE Toolkit
http://www.solarisinternals.com			# Sun Internals (see "har")


Copyright
--------
Copyright (c) 2003, 2004, 2005 Brendan Gregg.

 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 2
 of the License, or (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software Foundation,
 Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

 (http://www.gnu.org/copyleft/gpl.html)

