|
SnapShot
Declaration
NINT SnapShot(NINT opcode, pTEXT rqstdesc, pVOID snapbufr, VRLEN buflen);
Description
The c-tree Server (as of V8.14) tracks and reports a wealth of performance-oriented statistics. The server's Performance Snapshot capability enables the capture of performance monitoring data using a combination of configuration file options and the SnapShot c-tree Plus API function. The performance data can be captured automatically at specified intervals or on demand in the following ways:
- The ctstat utility provides a command-line interface to the SNAPSHOT API function, supporting output of c-tree Server statistics at the c-tree Server system, user, file, and function levels.
- Configuration file options support automatic performance snapshots by specifying the interval between automatic snapshots and the contents of the snapshots. The performance data captured by automatic snapshots are written to the c-tree Server system event log (SYSLOG) files.
- Use DIAGNOSTICS options to capture the automatic system snapshot data to the human-readable SNAPSHOT.FCS file.
- The SnapShot() API function can control automatic snapshots, overriding configuration options (if any), and can capture on-demand performance data:
- to either the SYSLOG files or to the human-readable SNAPSHOT.FCS file, or
- as a return to the calling program.
Parameters
- opcode specifies the action to be taken by the snapshot function.
- rqstdesc points to an ASCII string containing the input information.
- snapbufr points to an output buffer of length buflen.
Different opcode's require different combinations of input and output parameters ranging from using neither of them to both of them.
Snapshot Contents
Each snapshot is comprised of a structure (ctGSMS for system info, ctGUMS for user info and ctGFMS for file info) followed optionally by a variable region. Each of the three snapshot structures contains information about the size of the structure and the amount of variable information, if any, following the structure. Further, if the output buffer is too small to hold all the variable information, the contents member of the main structure will have the ctSNAPSHOTtruncated bit turned on if information had to be truncated.
Note: These structure definitions may vary depending on the version of the c-tree Server and c-tree Plus SDK you are using. Please consult the c-tree headers for the actual structure definition that is in use. Differences in definitions between a given ctstat client and c-tree Server may make ctstat incompatible with that server, in which case the ctstat utility displays an error message indicating structure incompatibility.
The only variable information consists of an array of function timing results for the overall system or for a user. The array is composed of ctWRKSTT structures. Function timings are described below, but these timings are only for direct calls from c-tree clients.
Most of the elapsed times accumulated in the snapshots are based on high-resolution timers that report in numbers of ticks and are stored in eight-byte integers. The description following each structure member contains a ‘^’ to indicate results based on high-resolution timers. To convert such times to seconds, divide by the ticks per second, a system dependent value stored in the scthrbastim member of each snapshot structure.
Snapshot Structures
 System Snapshot Structure
System snapshots may include an optional function-timing array of ctWRKSTT structures as described in the Function Timing section below.
typedef struct ctgsms {
ULONG client_ver; /* client version of structure */
ULONG server_ver; /* server version of structure */
ULONG fixlen; /* length of fixed portion of snapshot */
ULONG varlen; /* length of variable region (if any) */
ULONG contents; /* bit map of var len contents */
ULONG unused; /* available for use */
LONG8 snapshottm; /* snapshot time stamp: seconds since 70*/
LONG8 sctdnd_red; /* delete node thread queue reads */
LONG8 sctdnd_wrt; /* delete node thread queue writes */
LONG8 sctdnd_rwt; /* delete node thread queue rewrites */
LONG8 sctdnd_abn; /* delete node thread queue abandons */
LONG8 sctdnd_rmv; /* delete node thread queue removals */
LONG8 sctdnd_non; /* delete node thread queue no action */
LONG8 sctloktry; /* count of lock attempts */
LONG8 sctlokhlk; /* subcount of hdr lock attempts */
LONG8 sctlokdny; /* count of locks denied */
LONG8 sctlokblk; /* count of locks blocked */
LONG8 sctlokhbk; /* subcount of header blocks */
LONG8 sctlokdlk; /* count of dead locks */
LONG8 sctlokfre; /* count of locks freed */
LONG8 sctlokrel; /* count of blocks released */
LONG8 sctlokcur; /* current count of locks held */
LONG8 sctblkcur; /* current count of blocked requests */
LONG8 scttrntim; /* cumulative transaction time^ */
LONG8 scttrncnt; /* cumulative transaction count */
LONG8 scttrnmax; /* maximum elapsed tran time^ */
ULONG sct_compflg3; /* compatibility config flags */
LONG sctrqtmonint /* request time monitor value */
LONG8 scttot_call; /* system-wide c-tree calls */
LONG8 scttot_recv; /* system-wide time waiting for request^*/
LONG8 scttot_work; /* system-wide time performing requests^*/
LONG8 scttot_send; /* system-wide time to send request^ */
LONG8 sctmemhgh; /* system memory highwater mark */
LONG8 sctmemsum; /* current aggregate sum */
LONG8 sct_dbrqs; /* data buffer requests */
LONG8 sct_dbhit; /* data buffer hits */
LONG8 sct_ibrqs; /* index buffer requests */
LONG8 sct_ibhit; /* index buffer hits */
LONG8 sct_rdops; /* number of read operations */
LONG8 sct_rdbyt; /* bytes read */
LONG8 sct_wrops; /* number of write operations */
LONG8 sct_wrbyt; /* bytes written */
LONG8 sct_rcops; /* number of comm read operations */
LONG8 sct_rcbyt; /* comm bytes read */
LONG8 sct_wcops; /* number of comm write operations */
LONG8 sct_wcbyt; /* comm bytes written */
LONG8 sctwlgops; /* number of log write operations */
LONG8 sctwlgbyt; /* bytes written to log file */
LONG8 sctrlgops; /* number of log read operations */
LONG8 sctrlgbyt; /* bytes read from log file */
LONG8 sctxlgops; /* number of log extension operations */
LONG8 sctxlgbyt; /* log file extension bytes */
LONG8 sct_trbeg; /* # transaction begins */
LONG8 sct_trend; /* # transaction ends */
LONG8 sct_trabt; /* # transaction aborts */
LONG8 sct_trsav; /* # transaction savepoints */
LONG8 sct_trrst; /* # transaction restores */
LONG8 sct_trfls; /* # transaction log flush writes */
LONG8 sctsync_dosfls; /* DOSFLUSH sync calls */
LONG8 sctsync_logfil; /* transaction log sync calls */
LONG8 sctsync_regfil; /* c-tree file sync calls */
LONG8 scthrtimbas; /* high res timer ticks per sec^ */
LONG8 sctchkpnttim; /* cumulative checkpoint time^ */
LONG8 sctchkpntsiz; /* cumulative checkpoint size */
LONG8 sctcmtdlytry; /* cmtdly eligible count */
LONG8 sctcmtdlycnt; /* cmtdly concurrent trans exist */
LONG8 sctcmtdlycoh; /* cmtdly cohorts exist (success) */
LONG8 sctcmtcohmax; /* cmtdly max cohort count */
LONG8 sctcmtdlyclr; /* cmtdly cohort appeared (success) */
LONG8 sctcmtlopclr; /* cmtdly appeared loop count */
LONG8 sctcmtdlyfls; /* cmtdly log flushed anyway (success) */
LONG8 sctcmtlopfls; /* cmtdly log flush loop count */
LONG8 sctcmtdlydfr; /* cmtdly loop defer count */
LONG8 sctcmtdlyfls2; /* dmtdly log flushed anyway2 (success) */
LONG8 sctcmtlopfls2; /* cmtdly log flush2 loop count */
LONG8 sctcmtdlynot; /* cmtdly direct flush count */
LONG8 stimchk[8]; /* diagnostic time ct_udefer check */
LONG8 selapwrktim; /* elapsed time func timings turned on */
LONG8 selapsrvtim; /* elapsed server operation time */
LONG8 sctcmtblktim; /* accum time for cmtdly blocks */
LONG8 sctcmtclrtim; /* accum time for cmtdly clears */
LONG8 stimchktarget; /* ct_udefer expected result */
LONG8 stimchkconsec; /* time between consecutive hrt in usec */
LONG8 stimchkavg; /* avg time ofr hrtimer call in usec */
LONG8 available8[17]; /* available for future use */
LONG sctactfil; /* # open physical files */
LONG scttotfil; /* # open logical files */
LONG scttotblk; /* # c-tree FCBs in use */
LONG sctactfilx; /* max physical files opened */
LONG scttotfilx; /* max logical files opened */
LONG scttotblkx; /* max c-tree FCBs in use */
LONG sctnusers; /* number of users */
LONG sctnusersx; /* max number of users */
LONG sctloknm; /* net locks over unlocks */
LONG sctloknmx; /* max net locks over unlocks */
ULONG sct_mxbuf; /* number of index buffer pages */
ULONG sctbufcnt; /* index buffer pages in use */
ULONG sctbufhgh; /* max index buffers in use */
ULONG sct_dxbuf; /* available data cache pages */
ULONG sctdatcnt; /* data cache pages in use */
ULONG sctdathgh; /* max data cache pages in use */
ULONG scmtblkseq; /* not flow through cmtdly block */
ULONG sct_compflg; /* compatibility flag */
ULONG sct_compflg2;
ULONG sct_diagflg; /* diagnostic flag */
ULONG sct_diagflg2;
LONG sct_cmtdly; /* commit delay */
LONG sct_chkdly; /* checkpoint tranac_cnt delay */
ULONG sct_cmtscl; /* cmtdlytim block to clear ratio */
ULONG sct_cmtbas; /* cmtdlytim cohort size measure */
ULONG stimchkusec; /* ct_udefer test interval in usec's */
ULONG stimchkiter; /* ct_udefer test iterations */
ULONG sct_udefer_thld;/* ct_udefer usec threshold */
ULONG sct_udefer_64yd;/* sleep duration for 64 yields (usec) */
ULONG available4u[11];/* available for use */
ULONG sct_dxspllmt; /* avail data file special cache pages */
ULONG sct_dxsplcnt; /* actual data file special cache pages */
ULONG sct_dxsplhgh; /* maximum data file special cache pages*/
ULONG sctcpcnt; /* check point count */
LONG sct_numvfil; /* number of virtual files open */
LONG sct_avlfil; /* # available file control blocks */
LONG sctactusr; /* number of threads active in foregrnd */
LONG sct_nutcnt; /* # of index buffers on upd list (tran)*/
LONG sct_nupcnt; /* # of index buffers on upd list */
LONG sct_dutcnt; /* # of data caches on upd list (tran) */
LONG sct_dupcnt; /* # of data caches on upd list */
LONG available4[13]; /* available for future use */
COUNT sct_mxfil; /* total number of c-tree FCBs */
COUNT sct_ndsec; /* # of sectors per node */
UTEXT sflvr; /* server byte order */
UTEXT salgn; /* server alignment */
UTEXT spntr; /* server pointer size */
TEXT availt[25];
TEXT description[128];/* optional text description */
} ctGSMS, ctMEM * pctGSMS;
File Snapshot Structure
typedef struct ctgfms {
ULONG client_ver; /* client version of structure */
ULONG server_ver; /* server version of structure */
ULONG fixlen; /* length of fixed portion of snapshot */
ULONG varlen; /* length of variable region (if any) */
LONG8 snapshottm; /* snapshot time stamp: seconds since 70*/
LONG8 phyrec; /* physical file size */
LONG8 numrec; /* logical file size */
LONG8 sernum; /* serial number */
LONG8 nument; /* active entries */
LONG8 hghtrn; /* tran# high water mark for idx */
LONG8 tstamp; /* update time stamp */
LONG8 mxfilz; /* max file size high word */
LONG8 fredops; /* file specific # of read ops */
LONG8 fredbyt; /* file specific # of bytes read */
LONG8 fwrtops; /* file specific # of write ops */
LONG8 fwrtbyt; /* file specific # of bytes written */
LONG8 scthrtimbas; /* high res timer ticks per sec^ */
LONG8 avail8[9];
ULONG idxhgt; /* index height */
ULONG fileid; /* unique file id */
ULONG servid; /* unique server id */
ULONG timeid; /* time id# */
ULONG nodsiz; /* node size */
ULONG reclen; /* fixed data record length */
ULONG logtyp; /* permanent components of file mode */
ULONG maxkbl; /* maximum key bytes leaf-var */
ULONG maxkbn; /* maximum key bytes non leaf-var */
ULONG filtyp; /* flag for file type */
ULONG keylen; /* key length */
ULONG kmem; /* key member # */
ULONG nmem; /* number of members */
ULONG suptyp; /* super file type */
ULONG maxmrk; /* maximum exc mark entries per leaf */
ULONG hdrseq; /* wrthdr sequence # */
ULONG floktry; /* total lock attempts */
ULONG flokhlk; /* header lock attempts */
ULONG flokblk; /* total lock wait count */
ULONG flokhbk; /* header lock wait count */
ULONG flokdlk; /* deadlocks */
ULONG flokdny; /* total locks denied */
ULONG flokfre; /* total locks freed */
ULONG flokrel; /* total blocks released */
ULONG flokcur; /* current count of locks held */
ULONG fblkcur; /* current count of blocked requests */
ULONG datlmt; /* max number of special cache pages */
ULONG datspl; /* actual number of special cache pages */
ULONG bufcnt; /* number of buffer pages */
ULONG datcnt; /* number of data cache pages */
ULONG numchn; /* number of channels */
ULONG usrcnt; /* number of users with file open */
ULONG avail4[8];
ULONG contents; /* bit map of var len contents */
LONG segmax; /* maximum # of segments */
LONG seglst; /* # activated segments */
UTEXT updflg; /* update (corrupt) flag */
UTEXT ktype; /* file type flag */
UTEXT autodup; /* duplicate flag */
UTEXT deltyp; /* flag for type of idx delete */
UTEXT keypad; /* padding byte */
UTEXT flflvr; /* file flavor */
UTEXT flalgn; /* file alignment */
UTEXT flpntr; /* file pointer size */
UTEXT sflvr; /* server byte order */
UTEXT salgn; /* server alignment */
UTEXT spntr; /* server pointer size */
TEXT availt[9];
TEXT filename[256]; /* file name */
} ctGFMS, ctMEM * pctGFMS;
User Snapshot Structure
Users may define up to 8 different timing baskets. A begin mark call establishes a high resolution starting time for the specified basket. An end mark call increments the specified basket counter, adds the elapsed time to the timing basket, and clears the starting time. Attempting to begin a mark that is not clear or end a mark that has not begun results in an error. The baskets are numbered from 0 to 7. Their results appear in the user snapshot structure in the smarkcnt and smarktim arrays.
User snapshots may include an optional function-timing array of ctWRKSTT structures as described in the Function Timing section below.
typedef struct ctgums {
ULONG client_ver; /* client version of structure */
ULONG server_ver; /* server version of structure */
ULONG fixlen; /* length of fixed portion of snapshot */
ULONG varlen; /* length of variable region (if any) */
ULONG contents; /* bit map of var len contents */
ULONG unused; /* available for use */
LONG8 snapshottm; /* snapshot time stamp: seconds since 70*/
LONG8 strntsum; /* user trntime sum^ */
LONG8 strntmax; /* user trntime max^ */
LONG8 scthrtimbas; /* high res timer ticks per sec^ */
LONG8 avail8[9]; /* available for use */
LONG8 smarktim[8]; /* user mark elapsed times^ */
ULONG smarkcnt[8]; /* user mark counts */
ULONG slOWNR; /* thread handle (OWNER) */
ULONG sisolev; /* transaction isolation level */
ULONG sctops; /* set operation state bit mask */
ULONG sctstate; /* internal state bit mask */
ULONG sabnlog; /* begtran log for abandoned tran */
ULONG strntcnt; /* user trntime count */
ULONG sctutrbeg; /* user tran begin count */
ULONG sctutrend; /* user tran end count */
ULONG sctutrabt; /* user tran abort count */
ULONG snbrfile; /* number of files in use */
ULONG slogtime; /* logon time */
ULONG srqstime; /* last request time */
ULONG srqsfunc; /* last request function # */
ULONG srqssubf; /* last request sub-function # */
ULONG sactflag; /* active / inactive flag */
ULONG sct_trdflg; /* thread operation flag */
ULONG sabnflg; /* stage of abandon tran processing */
ULONG sctusrprf; /* user profile word */
ULONG sctumxfil; /* max files for user */
ULONG scthghfil; /* highest file number limit */
ULONG sloktry; /* total lock attempts */
ULONG slokhlk; /* header lock attempts */
ULONG slokblk; /* total lock wait count */
ULONG slokhbk; /* header lock wait count */
ULONG slokdlk; /* deadlocks */
ULONG slokdny; /* total locks denied */
ULONG slokfre; /* total locks freed */
ULONG slokrel; /* total blocks released */
ULONG slokcur; /* current count of locks held */
ULONG sblkcur; /* current count of blocked requests */
ULONG avail4[10];
UTEXT clflvr; /* user flavor */
UTEXT clalgn; /* user alignment */
UTEXT clpntr; /* user pointer size */
UTEXT sflvr; /* server byte order */
UTEXT salgn; /* server alignment */
UTEXT spntr; /* server pointer size */
UTEXT availt[26];
TEXT snodname[32]; /* node name */
TEXT sct_userid[32]; /* user id */
} ctGUMS, ctMEM * pctGUMS;
System Snapshot Support
The SnapShot API function supports logging c-tree Server system statistics. For a listing of the system statistics the c-tree Server collects, refer to the ctGSMS structure in the Snapshot Contents section below. The supported operations include:
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
On demand system snapshot returned directly in the output buffer. No entry is made in SYSLOG.
|
ctPSSsystem
|
NULL
|
Address of output buffer large enough to hold at least a ctGSMS structure
|
On demand system snapshot written to the SNAPSHOT.FCS text file.
|
ctPSStext
|
An optional text description, or NULL
|
NULL
|
File Snapshot Support
The SnapShot API function supports logging c-tree Server file statistics. For a listing of the file statistics the c-tree Server collects, refer to the ctGFMS structure in the Snapshot Contents section below. The supported operations include:
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
Activate the file with the specified file name. Use a pattern of ‘*’ to activate all files.
|
ctPSSaddFileName
|
File name (e.g., “cust*.*”)
|
NULL
|
Activate the file with the specified file number.
|
ctPSSaddFileNo
|
Small integer file number (e.g., ‘0’)
|
NULL
|
On demand file snapshot returned directly in the output buffer for the file with file number specified by rqstdesc. No entry is made in SYSLOG.
|
ctPSSfile
|
Small integer file number (e.g., ‘3’)
|
Address of output buffer large enough to hold a ctGFMS structure
|
Undo all file activations.
|
ctPSSclearFiles
|
NULL
|
NULL
|
User Snapshot Support
The SnapShot API function supports logging c-tree Server user statistics. For a listing of the user statistics the c-tree Server collects, refer to the ctGUMS structure in the Snapshot Contents section below. The supported operations include:
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
Activate the user with the specified User ID. Use a pattern of ‘*’ to activate all users.
|
ctPSSaddUserID
|
User ID
(e.g., “admin”)
|
NULL
|
Activate the user with the specified thread handle.
|
ctPSSaddUserHandle
|
Small integer thread handle (e.g., “12”)
|
NULL
|
On demand user snapshot returned directly in the output buffer. No entry is made in SYSLOG. The snapshot is for the user calling ctSNAPSHOT().
|
ctPSSuser
|
NULL
|
Address of output buffer large enough to hold at least a ctGUMS structure
|
On demand user snapshot returned directly in the output buffer.
|
ctPSSuserHandle
|
Small integer thread handle (e.g., “12”)
|
Address of output buffer large enough to hold at least a ctGSMS structure
|
Undo all user activations.
|
ctPSSclearUsers
|
NULL
|
NULL
|
Automatic Snapshot Support
The SnapShot API function supports starting, stopping, and resuming automatic snapshots. The following table shows the parameters to pass to SnapShot to perform these operations.
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
Start automatic snapshots, or change time interval if automatic snapshots are already enabled.
|
ctPSSstartAuto
|
Interval in minutes
(e.g., “60”)
|
NULL
|
Stop automatic snapshots.
|
ctPSSstopAuto
|
NULL
|
NULL
|
Resume automatic snapshots with the same interval last used.
|
ctPSSresumeAuto
|
NULL
|
NULL
|
Combined Snapshot Support
The SnapShot API function supports logging combined snapshots containing c-tree Server system statistics and user and file statistics for the specified activated users and files. This ability is supported by the following operation:
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
On demand snapshot of system and activated users and files written to SYSLOG. All entries to SYSLOG share the instance ID, a 4-byte integer, returned in the output buffer.
|
ctPSSnow
|
An optional text description up to 128 bytes, or NULL
|
Address of a 4-byte integer to hold instance ID
|
Function Timing Snapshot Support
The SnapShot API function supports profiling of c-tree API function calls (function timing) and timing of user-defined operations. The supported operations include:
- Starting and stopping the collection of c-tree API function timing statistics.
- Resetting the function timing statistics.
- Accumulating timings in user-defined timing baskets. Users may define up to 8 different timing baskets. A begin mark call establishes a high resolution starting time for the specified basket. An end mark call causes the specified basket counter to be incremented, and the elapsed time is added to the timing basket. The baskets are numbered from 0 to 7.
Note: Function timings require a significant number of calls to the high-resolution timer, and are more consistent with diagnostic or testing modes of operation.
The following table shows the parameters to pass to SnapShot() to perform these operations.
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
Start collecting function-timing statistics. This can be called whether or not automatic snapshots are currently active. It affects the contents of snapshots written to SYSLOG, not when or if they occur.
|
ctPSStimeWorkOn
|
NULL
|
NULL
|
Turn off function timings.
|
ctPSStimeWorkOff
|
NULL
|
NULL
|
Mark beginning time for one of 8 user specified timing baskets.
|
ctPSSbegMark
|
Small integer between 0 and 7 (e.g., ‘3’)
|
NULL
|
Mark ending time for user specified timing basket.
|
ctPSSendMark
|
Small integer between 0 and 7 (e.g., ‘3’)
|
NULL
|
Clear all function-timing statistics.
|
ctPSStimeWorkClear
|
NULL
|
NULL
|
SQL Snapshot Support
The SnapShot API function has a mode for retrieving c-treeACE SQL specific statistics.
Snapshot action
|
opcode
|
rqstdesc
|
snapbufr
|
Not completely implemented at this time.
|
ctPSSsqlSystem
|
NULL
|
NULL
|
Return Values
SnapShot returns NO_ERROR (0) on success, or an error code on failure.
0
|
NO_ERROR
|
Successful operation.
|
See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.
Example
...
ctGSMS* my_sysSnap;
NINT rc = 0;
my_sysSnap = (ctGSMS*) malloc(sizeof(ctGSMS));
memset(my_sysSnap, 0, sizeof(ctGSMS));
rc = InitISAMXtd(10, 10, 8192/128, 10, 0, "ADMIN", "ADMIN", "FAIRCOMS");
if (rc) {
printf("InitISAMXtd Error: %d\n", rc);
return (rc);
}
/* Take a System SnapShot */
rc = SnapShot(ctPSSsystem, NULL, my_sysSnap, sizeof(ctGSMS));
if (rc) {
printf("SnapShot Error: %d\n", rc);
return (rc);
}
rc = CloseISAM();
if (rc)
printf("CloseISAM Error: %d\n", rc);
/* Print Memory statistics */
printf("High Mem: %d\n", my_sysSnap->sctmemhgh);
printf("Current Mem: %d\n", my_sysSnap->sctmemsum);
/* Print Disk I/O statistics */
printf("Read ops: %d\n", my_sysSnap->sct_rdops);
printf("Read bytes: %d\n", my_sysSnap->sct_rdbyt);
printf("Write ops: %d\n", my_sysSnap->sct_wrops);
printf("Write bytes: %d\n", my_sysSnap->sct_wrbyt);
/* Print Platform Specific Server information */
printf("Server flavor: %d\n", my_sysSnap->sflvr);
printf("Alignment: %d\n", my_sysSnap->salgn);
printf("Pointer size: %d\n", my_sysSnap->spntr);
free(my_sysSnap);
...
See Also
|
