test

Using Calendar Server Capture (cscapture) to Collect Debug Data for Sun Java System Calendar Server

Chapter 1 Using Calendar Server Capture (cscapture) to Collect Debug Data for Sun Java System Calendar Server

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:

1.1 Technical Note Revision History

Version 

Date 

Description of Changes 

10 

June 2007 

Initial release of this technical note. 

1.2 About This Technical Note

This document covers the following versions of Sun Java System Calendar Server on the SolarisTM Operating System:

1.3 What Is CS Capture?

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.

1.4 What Data Does CS Capture Gather?

CS Capture gathers the following set of information:

Machine environment information:

Calendar Server information:

Calendar Server running process information (optional):

Core dump information from crashed processes:

Packages data:

Figure 1–1 shows a directory-layout diagram illustrating how the captured data is structured and archived:

Figure 1–1 Directory Layout of Captured Data

Directory layout of captured data.

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.

1.5 Supported Platforms, Calendar Server Versions, and Other Requirements.

Supported platforms:

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:

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.

Note –

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.

1.6 Known Problems and Limitations

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.

1.7 Running CS Capture

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:

  1. Machine environment information

  2. Calendar Server information and database*

  3. Core dump information from crashed processes

  4. 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.

Note –

For details on the data that CS Capture gathers, see 1.4 What Data Does CS Capture Gather?.

1.7.1 Specifying A Location for the Capture Directory

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

Note –

The directory path must exist. If it does not, CS Capture issues an error message.

1.8 Command Line Options

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)

1.8.1 Syntax


./cscapture [-i] [-db|nodb] [-?] [capture path]
Table 1–2 cscapture command line options:

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.

1.9 Database Options

1.9.1 -db (Force Database Capture)

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

1.9.2 -nodb (Never Capture the Database)

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

1.10 Running cscapture in Invasive Mode

1.10.1 -i (Invasive Mode)

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.

Note –

By default, CS Capture does not perform any invasive operations.

1.11 Using CS Capture with pkg_app

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

1.11.1 How to Disable pkg_app

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

1.12 Summary File

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.

1.13 Reporting Problems

If you have any problems with CS Capture, would like to report a bug, or would like an enhancement (RFE) made, send email to:

gdd-issue-tracker@sun.com

For all other questions and feedback on the script, email:

gdd-feedback@sun.com