8. GemStone C Statistics Interface

Previous chapter

This chapter describes the GemStone C Statistics Interface (GCSI), a library of functions that allow your C application to collect GemStone statistics directly from the shared page cache without starting a database session.

8.1  Developing a GCSI Application

The command lines in this chapter assume that you have set the $GEMSTONE environment variable to your GemStone installation directory.

Required Header Files

Your GCSI program must include the following header files:

  • $GEMSTONE/include/shrpcstats.ht — Defines all cache statistics. (For a list of cache statistics, refer to the “Monitoring GemStone” chapter of the System Administration Guide for GemStone/S 64 Bit.)
  • $GEMSTONE/include/gcsi.hf — Prototypes for all GCSI functions.
  • $GEMSTONE/include/gcsierr.ht — GCSI error numbers.

Your program must define a main() function somewhere.

The GCSI Shared Library

GemStone provides a shared library, $GEMSTONE/lib/libgcsi-3.6.0-64.so, that your program will load at runtime.

  • Make sure that $GEMSTONE/lib is included in your LD_LIBRARY_PATH environment variable, so that the runtime loader can find the GCSI library. For example:
export LD_LIBRARY_PATH=$GEMSTONE/lib:$LD_LIBRARY_PATH
  • $GEMSTONE/lib/libgcsi-3.6.0-64.so is a multi-threaded library, so your program must also be compiled and linked as a multi-threaded program.

Compiling and Linking

The $GEMSTONE/examples directory includes the sample GCSI program gsstat.cc, along with a set of sample makefiles that show how to compile the sample GCSI program, using the compilers that are used to build the GemStone product.

NOTE
It may still be possible to build your program with another compiler, as long as you specify the appropriate flags to enable multi-threading.

Whenever you upgrade to a new GemStone version, you must re-compile and re-link all your GCSI programs. This is because the internal structure of the shared cache may change from version to version. Assuming you’ve created a makefile, all you should need to do is change $GEMSTONE and rebuild.

Connecting to the Shared Page Cache

The GCSI library allows your program to connect to a single GemStone shared page cache. Once the connection is made, a thread is started to monitor the cache and disconnect from it if the cache monitor process dies. This thread is needed to prevent your program from "holding on" to the shared cache after all other processes have detached from it. In this way, your program can safely sleep for a long time without preventing the operating system from freeing and recycling shared memory should the Stone be unexpectedly shut down.

The Sample Program

The sample program gsstat.cc (in $GEMSTONE/examples) monitors a running GemStone repository by printing out a set of statistics at a regular interval that you specify. The program prints the following statistics:

  • Sess — TotalSessionsCount; the total number of sessions currently logged in to the system.
  • CR — CommitRecordCount; the number of outstanding commit records that are currently being maintained by the system.
  • PNR — PagesNeedReclaimSize; the amount of reclamation work that is pending, that is, the backlog waiting for the GcGem reclaim task.
  • PD — PossibleDeadSize; the number of objects previously marked as dereferenced in the repository, but for which sessions currently in a transaction might have created a reference in their object space.
  • DNR — DeadNotReclaimedSize; the number of objects that have been determined to be dead (current sessions have indicated they do not have a reference to these objects) but have not yet been reclaimed.
  • FP — The number of free pages in the Stone.
  • OCS — OldestCrSession; the session ID of the session referencing the oldest commit record. Prints 0 if the oldest commit record is not referenced by any session, or if there is only one commit record.
  • FF — FreeFrameCount; the number of unused page frames in the shared page cache.

To invoke gsstat, supply the name of a running Stone (or shared page cache, if running on a Gem server) and a time interval in seconds. For example:

% gsstat myStone 2

To stop the gsstat program and detach from the cache, issue a CTRL-C.

8.2  GCSI Data Types

The following C types are used by GCSI functions. The file shrpcstats.ht defines each of the GCSI types (shown in capital letters below). That file is in the $GEMSTONE/include directory.

ShrPcMonStatSType    

Shared page cache monitor statistics.

ShrPcStnStatSType    

Stone statistics.

ShrPcPgsvrStatSType   

Page server statistics.

ShrPcGemStatSType    

Gem session statistics.

ShrPcStatUnion    

The union of all four statistics structured types: shared page cache monitor, page server, Stone, and Gem.

ShrPcCommonStatSType

Common statistics collected for all processes attached to the shared cache.

The Structure for Representing the GCSI Function Result

The structured type GcsiResultSType provides a C representation of the result of executing a GCSI function. This structure contains the following fields:

typedef struct {
 signed int processId;
  signed int sessionId;
  ShrPcCommonStatSType cmn;
  union ShrPcStatUnion u;
}  ShrPcStatsSType;
 
class GcsiResultSType {
public:
  char              vsdName[SHRPC_PROC_NAME_SIZE + 1];
  unsigned int      statType;
  ShrPcStatsSType   stats;
};

In addition, a set of C mnemonics support representation of the count of each process-specific structured type:

#define COMMON_STAT_COUNT 
(sizeof(ShrPcCommonStatSType)/sizeof(int)) 
 
#define SHRPC_STAT_COUNT 
(sizeof(ShrPcMonStatSType)/sizeof(int) + COMMON_STAT_COUNT) 
 
#define GEM_STAT_COUNT 
(sizeof(ShrPcGemStatSType)/sizeof(int) + COMMON_STAT_COUNT)
 
#define PGSVR_STAT_COUNT 
(sizeof(ShrPcPgsvrStatSType)/sizeof(int) + COMMON_STAT_COUNT)
 
#define STN_STAT_COUNT 
(sizeof(ShrPcStnStatSType)/sizeof(int) + COMMON_STAT_COUNT)

GcsiAllGemStatsForGemKindRange

Get all cache statistics for a Gems with GemKinds in the specifed range.

This function is only available on Linx.

Syntax

int GcsiAllGemStatsForGemKindRange(
int gemKindMin,
int gemKindMax,
GcsiResultSType*result,
int *resultSize
);

Arguments

gemKindMin    

Minimum value of gemKind to match to.

gemKindMax    

Maximum value of gemKind to match to; must be equal or greater than gemKindMin.

result

Address of an array of kind GcsiResultSType where statistics will be stored. NULL means return only a count of how many gems match.

resultSize    

Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of gems whose gemKind was in this range, inclusive. If result is not NULL, this is also the number of valid elements in the result array..

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

GcsiAllStatsForMask

Get all cache statistics for a specified set of processes types.

Syntax

int GcsiAllStatsForMask(
unsigned int mask;
GcsiResultSType * result;
int * resultSize);

Arguments

mask    

Indicates what types of processes to collect statistics for.

result    

Address of an array of kind GcsiResultSType where statistics will be stored.

resultSize    

Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of that were stored into result. Indicates the maximum number of processes for which statistics can be returned.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

Example

Mask bits should be set by a bitwise OR of the desired process types. For example, to get statistics for the stone and Shared Page Cache Monitor:

	unsigned int mask = SHRPC_MONITOR | SHRPC_STONE;

GcsiAllGemStatsForRegexName

Get all cache statistics for a Gems with cache names that match a regular expression.

This function is only available on Linux.

Syntax

int GcsiAllGemStatsForRegExName(
const char *regexString,
BoolType ignoreCase,
GcsiResultSType*result,
int *resultSize
char *errBuf,
size_t errBufSize
);

Arguments

regexString    

A valid regular expression string. This string will be used to match against the cache name of every gem attached to the shared page cache.

ignoreCase    

TRUE causes the regex search to ignore case.

result

Address of an array of kind GcsiResultSType where statistics will be stored. NULL means return only a count of how many gems match.

resultSize    

Pointer to an integer that indicates the size of the result in elements (not bytes). On return, indicates the number of gems whose cache name match. If result is not NULL, this is also the number of valid elements in the result array.

errBuf    

A buffer that will contain a string describing an error.

errBufSize    

Size (in bytes) of errBuf.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors. Examine errBuf for an error message.

GcsiAttachSharedCache

Attach to the specified shared page cache.

Syntax

int GcsiAttachSharedCache(
const char * fullCacheName;
char * errBuf;
size_t errBufSize);

Arguments

fullCacheName    

Full name of the shared page cache, in the format stoneName@stoneHostIpAddress. To determine the full name of the shared cache, use the gslist -x utility.

errBuf    

A buffer that will contain a string describing an error.

errBufSize    

Size (in bytes) of errBuf.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiAttachSharedCacheForStone
GcsiCacheIsAlive

GcsiAttachSharedCacheForStone

Attaches this process to the specified shared page cache.

Syntax

int GcsiAttachSharedCacheForStone(
const char * stoneName,
char * errBuf,
size_t errBufSize);

Arguments

stoneName    

Name of the Stone process.

errBuf    

A buffer that will contain a string describing an error.

errBufSize    

Size (in bytes) of errBuf.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

Description

This function assumes that the cache name is <stoneName>@<thisIpAddress> where thisIpAddress is the IP address of the local machine. This function may fail if the host is multi-homed (has more than one network interface). In that case, use GcsiAttachSharedCache to specify the full name of the shared cache.

See Also

GcsiAttachSharedCache
GcsiCacheIsAlive

GcsiCacheIsAlive

Check the status of the cache.

Syntax

int GcsiCacheIsAlive (void);

Return Value

Returns 1 if the cache is alive and we are attached; return 0 if the cache has died, or we are not or no longer attached.

GcsiDetachSharedCache

Detach from the shared page cache.

Syntax

int GcsiDetachSharedCache (void);

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiAttachSharedCache
GcsiAttachSharedCacheForStone

GcsiFetchMaxProcessesInCache

Return the maximum number of processes that can be attached to this shared cache at any instant. The result may be used to allocate memory for a calls to the GcsiFetchStatsForAll* family of functions.

Syntax

int GcsiFetchMaxProcessesInCache(
int * maxProcesses);

Arguments

maxProcesses    

The maximum number of processes that can be attached to this shared cache at any instant.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

GcsiInit

Initialize the library. This function must be called before all other GCSI functions.

Syntax

void GcsiInit(void);

 

GcsiStatsForGemSessionId

Get the cache statistics for the given Gem session id.

Syntax

int GcsiStatsForGemSessionId(
int sessionId;
GcsiResultSType * result);

Arguments

sessionId    

Session ID of the Gem for which statistics are requested.

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

GcsiStatsForGemSessionWithName

Get the cache statistics for the first Gem in the cache with the given cache name.

Syntax

int GcsiStatsForGemSessionWithName(
char * gemName;
GcsiResultSType * result);

Arguments

gemName    

The case-sensitive name of the Gem for which statistics are requested.

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

GcsiStatsForPgsvrSessionId

Get the cache statistics for the given page server with the given session id. Remote Gems have page servers on the Stone’s cache that assume the same session ID as the remote Gem.

Syntax

int GcsiStatsForPgsvrSessionId(
int sessionId;
GcsiResultSType * result);

Arguments

sessionId    

Session ID of the page server for which statistics are requested.

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForProcessId
GcsiStatsForShrPcMon
GcsiStatsForStone

GcsiStatsForProcessId

Get the cache statistics for the given process ID.

Syntax

int GcsiStatsForProcessId(
int pid;
GcsiResultSType * result;

Arguments

pid    

Process ID for which statistics are requested.

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForShrPcMon
GcsiStatsForStone

GcsiStatsForShrPcMon

Get the cache statistics for the shared page cache monitor process for this shared page cache.

Syntax

int GcsiStatsForShrPcMon(
GcsiResultSType * result);

Arguments

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForStone

GcsiStatsForStone

Get the cache statistics for the Stone if there is a Stone attached to this shared page cache.

Syntax

int GcsiStatsForStone(
GcsiResultSType * result);

Arguments

result    

Pointer to a GcsiResultSType structure.

Return Value

Returns 0 if successful; otherwise returns an error code, as defined in gcsierr.ht; see GCSI Errors.

See Also

GcsiStatsForGemSessionId
GcsiStatsForGemSessionWithName
GcsiStatsForPgsvrSessionId
GcsiStatsForProcessId
GcsiStatsForShrPcMon

GCSI Errors

The following errors are defined for the GemStone C Statistics Interface.

Table 1 GCSI Errors 

Error Name

Definition

GCSI_SUCCESS

The requested operation was successful.  

GCSI_ERR_NO_INIT

GcsiInit() must be called before any other Gcsi functions.

GCSI_ERR_CACHE_ALREADY_ATTACHED

The requested shared cache is already attached.

GCSI_ERR_NOT_FOUND

The requested session or process was not found.

GCSI_ERR_BAD_ARG

An invalid argument was passed to a Gcsi function.

GCSI_ERR_CACHE_CONNECTION_SEVERED

The connection to the shared cache was lost.

GCSI_ERR_NO_STONE

Stone statistics were requested on a cache with no stone process.

GCSI_ERR_CACHE_NOT_ATTACHED

No shared page cache is currently attached.

GCSI_ERR_NO_MORE_HANDLES

The maximum number of shared caches are attached.

GCSI_ERR_CACHE_ATTACH_FAILED

The attempt to attach the shared cache has failed.

GCSI_ERR_WATCHER_THREAD_FAILED

The cache watcher thread could not be started.

GCSI_ERR_CACHE_WRONG_VERSION

The shared cache version does not match that of the libgcsixx.so library.

 

Previous chapter