This appendix provides an overview of how to use the
cstat utility. It is intended as an introduction for new users and a reference for experienced users.
More advanced (undocumented) options may alter shared memory and should be used with care. These advanced options should be used only at the direction of InterSystems Support personnel; for information, contact the InterSystems Worldwide Response Center (WRC).
This appendix contains the following sections covering
In the event of a system problem, the
cstat report is often the most important tool that InterSystems has to determine the cause of the problem. Use the following guidelines to ensure that the cstat report contains all of the necessary information:
cstat is a separate executable file included with Caché, it is run outside of Caché, at an operating system prompt. Therefore, the details of running it depend on the operating system:
cstat with no options is not a common way to run it, but doing so produces a basic report which is the equivalent of running it with the following default options:
cstat` executable is located in Caché instance’s \bin directory. Starting with a Windows command prompt running as Administrator, you can run it as follows:
C:\>cd install-dir\bin C:\install-dir\bin>cstat
If you run
cstat from a directory other than the instance’s \bin or \mgr, you must include the -s argument to specify the location of the \mgr directory. For example:
cstat` executable is located in the Caché instance’s Bin directory. You can run it from another directory, but unless you are in the instance’s mgr or Bin directory, you must include the -s argument to specify the location of the mgr directory. Starting with a Unix® command prompt, running as root, change to the Bin directory or the mgr directory and run the cstat command as follows:
From the Caché installation directory, the command would be as follows:
bash-3.00$ ./bin/cstat -smgr
You can also invoke
cstat via the ccontrol command, which can be run from any directory as shown in the following example:
bash-3.00$ ccontrol stat Cache_Instance_Name
cstat without options produces a basic report. Generally, you run cstat to obtain specific information. To specify the information you want, add or subtract options, as follows:
To include (turn on) an option, specify a flag followed by a
1(or other level).
To exclude (turn off) an option, specify a flag followed by a
For example, to include the Global File Table (GFILETAB) section in the
cstat report, use the -m1 option:
or, to turn off the default basic options, use the
Many options have more detailed levels than
0 and 1. These additional levels are described as having bits, which are displayed in decimal as powers of two and control specific types of information about the option. For example, the basic -p option, which displays the PID table, is turned on with a 1; however, using a 2 adds a swcheck column, a 4 adds a pstate column. and so on. These bits can be combined; for example, if you want to see the information displayed by both the 2 and 4 bits, specify -p6. To ask for all bits, use -1, as follows:
bash-3.00$ ./cstat -p-1
In addition, multiple flags can be combined in a single
cstat command. For example, the following command turns off the basic options, then turns on all bits for the global module flags and PID table, as well as a detailed level for the GFILETAB:
bash-3.00$ ./cstat -a0 -f-1 -p-1 -m3
It is common for
cstat commands to have many flags when you start diagnosing a complex problem; however, the options that make modifications are typically used alone. For example, the -d option requests a process dump; before using this option, you might run cstat with multiple options to identify the process to dump, but when using -d, typically no other options are selected.
Displays information about global buffer descriptors blocks (BDBs). You can specify a combination of the following bits:
Displays counters, which are statistics on system performance. You can specify a combination of the following bits:
Creates dump of Caché processes. You can specify the following options:
Displays global module flags. You can specify a combination of the following bits:
Displays the journal system master structure, which lists information about journaling status.
|-k||Displays information about prefetch daemons used by the
Displays information about least recently used (LRU) global buffer descriptor block (BDB) queue, but not the contents of the BDBs. You can specify a combination of the following bits:
Displays Global File Table (GFILETAB), which contains information about all databases, listed by SFN, that have been mounted since the instance of Caché started up. You can specify a combination of the following bits:
Displays information about network structures and local/remote SFN translations;
|-o1||Clears the resource statistics displayed by
Displays information about processes that are running in Caché. The information is obtained from the process ID table (PIDTAB). You can specify a combination of the following flags:
Displays information about hibernation semaphores.
|Specifies the directory containing the
Displays information about Caché locks stored in the lock table (see Monitoring Locks in the
|Ensures that the Caché executable associated with the shared memory segment
Displays information about BDBs in write daemon queues.
Displays, in hex, the contents of blocks held in GBFSPECQ.
Displays configuration information for inter-job communication (IJC) devices.
Displays resource statistics over an interval of ‘secs’ seconds. Sample block collisions ever ‘msec’ milliseconds.
Resource information same as
Displays status of cluster on platforms that support clustering. You can specify a combination of the following bits:
Displays, in hex, the contents of the global buffer descriptors and the global buffer for a specific buffer descriptor block (BDB).
Displays, in hex, the contents of the global buffer descriptors and the global buffer for a specific system file number (sfn) and block number (blk) pair.
The block must be in the buffer pool.
Displays the incremental backup data structures.
Displays the license.
Displays the mailbox log.
Disabled by default. A special build is required to capture and log the mailbox messages; additional logging may be required.
Displays ECP network information. You can specify a combination of the following values:
Displays information about routine buffers in use (or changing), class control blocks (CCB), and least recently used (LRU) queues. You can specify a combination of the following values:
Displays information about the cause of a hang based on a self diagnosis of whether or not the system is hung. You can specify a combination of the following bits:
In a cluster, this option should be run all cluster members.
Displays hex values of many in-memory tables, including National Language Settings (NLS) tables.
Displays variables that are part of the process memory structures; of limited value unless you have access to the source code.
Windows only. Run from the directory that contains the
|Performs the same function as the Backup.General.ExternalThaw() classmethod, and may be used to resume the write daemon after Backup.General.ExternalFreeze() has been called in cases in which a new Caché session cannot be started. (See External Backup in the
Displays the contents of the device translation table. It is organized by device number and shows both the numeric and plaintext class identifiers.
When Caché is forcibly shut down,
cstat is run in order to capture the current state of the system. The output is added to the console log as part of the emergency shutdown procedure.
cstat reports can be redirected to a file instead of the terminal, which might be useful if you want to collect a set of
cstat options that are not provided by one of the Caché tools (Diagnostic Report Task, CacheHung Script, ^pButtons Utility) or if you are having trouble running those tools.
The Diagnostic Report task creates an HTML log file containing both basic and advanced information, which can be used by the InterSystems Worldwide Response Center (WRC) to resolve system problems. For information about the Diagnostic Report task, including the
cstat options that it uses, see the Using the Caché Diagnostic Report chapter in this guide.
The Diagnostic Report task cannot be run on a hung system; if your system is hung, see CacheHung Script in this appendix.
CacheHung script is an OS tool used to collect data on the system when a Caché instance is hung. The name of the script, which is located in the install-dir/ Bin directory, is platform-specific, as specified in the following table:
CacheHung script should be run with Administrator privileges. Like the Diagnostic Report Task, the CacheHung script runs cstat twice, 30 seconds apart, in case the status is changing, and bundles the reports into an html file together with the other collected data. The cstat reports taken from CacheHung use the following options:
cstat -e2 -f-1 -m-1 -n3 -j5 -g1 -L1 -u-1 -v1 -p-1 -c-1 -q1 -w2 -E-1 -N65535
CacheHung generates cstat output files that are often very large, in which case they are saved to separate txt files. Remember to check for these files when collecting the output.
^pButtons utility collects detailed performance data about a Caché instance and the platform on which it is running. It runs inside Caché for a configurable amount of time, collects samples over the that interval, and generates a report when it finishes. For information about the ^pButtons utility, including the cstat options that it uses, see the Monitoring Performance Using ^pButtons chapter in this guide.