This technical note describes how to use Calendar Server (CS) Capture, a Sun Gathering Debug Data (GDD) utility. CS Capture collects data required by the Sun Support Center to debug problems with a Sun JavaTM System Calendar Server system. By collecting this data before you open a Service Request, you can reduce substantially the time needed to analyze and resolve the problem.
This document is intended for anyone who needs to open a Service Request about the Calendar Server with the Sun Support Center and shows how to use CS Capture to provide the required data to enable a quicker resolution.
Using CS Capture is one step in the process of gathering debug data for the Sun Support Center. For complete instructions and guidelines, see Sun Gathering Debug Data for Sun Java System Calendar Server, also available at the following location:
http://docs.sun.com/app/docs/doc/820-0374
This technical note contains the following sections:
Version |
Date |
Description of Changes |
---|---|---|
10 |
June 2007 |
Initial release of this technical note. |
This document covers the following versions of Sun Java System Calendar Server on the SolarisTM Operating System:
Sun Java System Calendar Server 6.3 (Communications Suite 5)
Sun Java System Calendar Server 6.2 (2005Q4)
Sun Java System Calendar Server 6.2 2005Q1
Sun Java System Calendar Server 6.1 2004Q2
Sun Java System Calendar Server 6.0 2003Q4
CS Capture is mainly a Bourne Shell script that autonomously gathers data from your Calendar Server and the OS environment. It was developed as part of the General Data Debug project and designed to speed up resolution time on support calls.
Ideally, the tool should be run during or just after a problem has occurred or been reproduced. If this is not possible, it is still a good idea to run the tool before you open a support call to Sun. In most cases, the data provided by CS Capture, along with a good initial problem description, should help to speed up the support process.
CS Capture gathers the following set of information:
Machine environment information:
Machine statistics (vmstat, iostat, prstat, mpstat, and netstat)
Disk space usage (df)
Details of running processes (ps)
Hardware configuration (prtconf)
Swap information (swap -l)
Patches (showrev -p)
Calendar Server information:
Configuration (contents of SUNWics5/config)
timezones.ics file
Calendar Server production database (optional)
Calendar Server log files
Calendar Server running process information (optional):
3 gcores on each running process every 5 seconds
Uses pkg_app (supplied) to collect debugger environment for gcore analysis
Runs pstack and pmap against all gcores.
Core dump information from crashed processes:
Searches and collects Calendar Server process cores
Uses pkg_app (supplied) to collect debugger environment for core analysis
Runs pstack and pmap against core files
Packages data:
Uses tar and compress to package the data
Figure 1–1 shows a directory-layout diagram illustrating how the captured data is structured and archived:
The data gathered may vary, depending on the Calendar Server's configuration and the way cscapture is executed. (See 1.7 Running CS Capture for further information on different ways to run cscapture.) Also, certain directories will only exist if cores files are found.
Supported platforms:
Solaris SPARC, release 8 and above
Solaris x86, release 8 and above
For other platforms, continue to use the capture_environment.pl script. In the future, CS Capture will support other platforms. For now, the capture_environment.pl script can be found at:
http://www.sun.com/bigadmin/scripts/indexSjs.html
Supported Calendar Server versions:
Sun Java System Calendar Server 6.3 (Communications Suite 5)
Sun Java System Calendar Server 6.2 (2005Q4)
Sun Java System Calendar Server 6.2 2005Q1
Sun Java System Calendar Server 6.1 2004Q2
Sun Java System Calendar Server 6.0 2003Q4
For earlier versions of Calendar Server, continue to use the capture_environment.pl script, which can be found at:
http://www.sun.com/bigadmin/scripts/indexSjs.html
Other requirements:
pkg_app
CS Capture uses pkg_app to archive all the binary files associated with a core file for debugging purposes. See 1.11 Using CS Capture with pkg_app for further information about this facility.
Earlier versions of pkg_app are not compatible with CS Capture. pkg_app is distributed with CS Capture, and we recommend that you use only this supplied version with the CS Capture tool.
awk and nawk
CS Capture requires awk to be installed. It also uses nawk, if it is present. nawk is optional, but when installed on the same machine as CS Capture, it allows CS Capture to provide more information in the Summary file. For more information about this facility, see 1.12 Summary File.
Coreadm file patterns
CS Capture does not support the use of '%' embedded variables in the file path. However, '%' patterns can be used for the actual core filename itself. For example:
Table 1–1 Acceptable and unacceptable coreadm file patterns
/var/cores/host-%m/core |
Not acceptable. The '%' is within the core path to the file. |
/var/cores/core-%p |
Acceptable. The '%' is the filename for the core file itself. |
Core files must also be stored on a local file system and not over NFS. If these rules are not followed, CS Capture will not be able to find any core files that the Calendar Server processes may have dumped.
CS Capture can be run from a shell/terminal and must be run as root:
# ./cscapture
By default, CS Capture creates a capture directory in the path where you ran the cscapture command. All the files and information that cscapture gathers are stored in the capture directory. By default, (when run as shown above), cscapture gathers:
Machine environment information
Calendar Server information and database*
Core dump information from crashed processes
Package data
*By default, the Calendar Server database is only gathered if the production database is less the 500 MB. To override the default, use the -db option. For more information on cscapture options, see 1.8 Command Line Options.
For details on the data that CS Capture gathers, see 1.4 What Data Does CS Capture Gather?.
You can specify a different location for the capture directory by running CS Capture as follows:
# ./cscapturepath to where to store capture directory
For example, to store the capture directory in /var/opt, you would run CS Capture as follows:
# ./cscapture /var/opt
The directory path must exist. If it does not, CS Capture issues an error message.
CS Capture supports several command-line options that can be used to change the default behavior. Use the -? option to list the options and show the command-line usage and built-in help guide:
-? (Command Line Help)
./cscapture [-i] [-db|nodb] [-?] [capture path] |
Option |
Definition |
---|---|
-db | -nodb |
Database options. |
-i |
Invasive mode. |
-? |
Command-line built-in help. |
Entering an invalid option also displays the built-in help and usage information. For more information about the options, see 1.9 Database Options and 1.10 Running cscapture in Invasive Mode.
By default, CS Capture automatically captures Calendar Server's production database if its size is below 500 MB. CS Capture will not automatically capture a database over 500 MB, as the capture archive can become very large to upload and move. If you want to capture a larger database, you must use the -db option. For example:
./cscapture -db
If you never want CS Capture to capture Calendar Server's production database, use the -nodb option. This may be desired if you do not want to send Sun your database. However, in some cases, having a copy of your database can significantly speed up resolution time and can save Sun Support staff from requesting the database in the future. For example:
./cscapture -nodb
This option causes the script to perform actions that are invasive to running processes such as running gcore, pfiles, pstack, and pmap commands. The -i option can only be used if the calendar processes are not under cluster control. Sometimes invasive actions can disrupt a process and may cause it to crash. But they can provide useful information, particularly if the process has hung. For example:
./cscapture -i
When executed this way, CS Capture checks for running Calendar Server processes and simultaneously runs a gcore, pstack, and pmap on the running processes 3 times, once every 5 seconds. This data is gathered in the following location in the capture directory:
coredata/process name/gcores
For further information, see 1.4 What Data Does CS Capture Gather?
CS Capture also gathers the pfiles from each process. It gathers pkg_app data for the core files if pkg_app is executable and in the cscapture command's working directory. For information about running pkg_app with cscapture, see 1.11 Using CS Capture with pkg_app.
By default, CS Capture does not perform any invasive operations.
The GDD pkg_app script is included with CS Capture. Only this version is supported with CS Capture. Therefore, we recommend that you use the copy of the pkg_app script distributed with CS Capture.
In brief, pkg_app gathers a program binary and its associated library files to build a debug environment so that a Sun engineer can debug a process crash or hang. For more details about the pkg_app script, see:
http://docs.sun.com/app/docs/doc/820-0374/6nc4ajmd4?a=view
For CS Capture to use pkg_app, the script (or a link to the script) must be present in the directory where pkg_app is run from. It must also be called pkg_app and be executable. Otherwise CS Capture will fail to find the script. By default, with CS Capture, the pkg_app script sits in the same directory as the cscapture script.
cscapture/cscapture cscapture/pkg_app |
Thus, running cscapture from the cscapture directory will cause pkg_app to be used. For example:
# cd cscapture # ./cscapture |
If you do not want to have CS Capture run pkg_app, you can remove or rename the pkg_app script. For example:
# mv pkg_app pkg_app-disabled |
As CS Capture gathers data about your Calendar Server environment, it also creates a Summary file. The Summary file is included in the capture archive that you send to Sun. It allows an engineer to assess your server setup and quickly obtain a picture of your server environment. The following information is included in the Summary file:
Version Detected:
Shows the Calendar Server version and version of JES installed.
Installation Path:
Shows where the Calendar server is installed.
Platform:
Shows the platform the Calendar Server has been installed on, including the OS version and the hardware it is running on.
Capture started at:
Shows when the capture was started.
Host Memory Size:
Displays the amount of physical memory in the machine.
Total Online Processors:
Displays the number of online processors in the machine.
Machine Last Reboot:
Shows when the machine was last booted.
Installed Calendar Patches:
Shows the Calendar Server patches installed on the machine.
Installed or last patched on:
Shows when the Calendar Server has last had a patch applied.
Server Setup:
Informs you of any processes that are not running but should be. For example:
CSHTTPD running 1 out of 2 processes! CSADMIND process not running! |
This section also displays information on how the server is configured. Configurations are as follows:
This is a Standalone server. This is a Frontend server. This is a Backend server. This is a Frontend and Backend server. |
This section also tells you if CLD or LDAP Caching is enabled and if the server has been configured to support hosted domains.
Production Database Size:
Shows the physical size of the Calendar Server's production database on disk. This section also has information about the database capture. It indicates whether the -db or -nodb options were used. (For more information, see 1.9 Database Options.) It also displays the following message if the Calendar Server processes were running when CS Capture grabbed the database:
Comments: Calendar Server Services running during capture! The may cause CS Capture to capture and inaccurate copy of the db |
If you would like Sun to diagnose a database problem, it can be better to run CS Capture with the Calendar Server shut down. This is more relevant if you have a database over 500 MB. With a large database, the data is more likely to change while CS Capture is copying the database to the capture directory. This could result in a corrupt (or more corrupt) database being sent to Sun.
However, if you are more concerned with a crashing, hanging, or performance problems, shutting down the processes before running CS Capture may prevent the problem from being detected or gathered by the CS Capture program.
Core file/files found from <proc> at:
The above line may be displayed in the Summary file if pkg_app has found a core file from one of the Calendar Server's processes; where proc will be the name of the process. The Summary file indicates the time the process core was dumped, the full path name of the core file, and whether pkg_app was run against the core file. For example:
Core file/files found from cshttpd at: Dumped at: 14 May 13:01 : /opt/SUNWics5/cal/lib/core (Ran pkg_app on: cshttpd) |
Ran INVASIVE operations on: <proc> [PID <pid>]!
If you run CS Capture in invasive mode (see 1.10 Running cscapture in Invasive Mode), the Summary file displays the processes on which invasive information was captured.
Capture Finished at:
Shows when the capture finished.
If you have any problems with CS Capture, would like to report a bug, or would like an enhancement (RFE) made, send email to:
For all other questions and feedback on the script, email: