Getting command performance statistics (lkt_svrcmdstats)

This command is used to retrieve summary reports on performance statistics for one or more commands. It is also used to reset the statistics back to a zero state, that is, delete all existing statistics history for one or more commands.

dvkerr_t lkt_svrcmdstats( lpar_t host, lpar_t iargs, 
                          lpar_t *cmdstats );

Summary reports might be requested for a particular time interval by specifying an end time (most recent) and a duration. However the actual time covered is based on when previous reports were generated. Summary reports are created by merging previous summary reports. Currently the server maintains a history of all summary reports requested over the last 17 minutes plus a final summary report that covers the rest of the time back to the start of the server or the last reset issued on the command. When you request a report starting from "now" a new summary report is generated and stored into this "history" of reports. This new report covers the time from "now" back to when the last report was issued. The returned report is then generated by merging those "history" reports that most closely cover the requested time period as defined by the duration. This has a number of implications:

•

The first report generated is always for the entire time period since the server was started.

•

Durations greater than 17 minutes covers the last 17 minutes or the entire time period since the server was started, or the last reset.

•

Actual durations for summary reports are based on when previous summary reports were requested.

In practice if reports over specific time periods are wanted summary reports should be requested at regular intervals representing the shortest time period. For example if you want reports for the last 1 minute, 5 minutes and 15 minutes you should request a report every 1 minute. The system has a history of reports at one minute intervals available and is able to generate summary reports for 5 minute and 15 minute intervals.

Note that new summary reports are generated into the "history" only if you request an end time of "now" for your report (this is the default). This essentially creates a time tic-mark. Requesting a specific end time does not create a new tic-mark, it uses only existing "history" reports to generate the output report. So in the example used above where reports for the last 1, 5 and 15 minutes are desired, the recommended procedure is to first request a report from "now" with a duration of 1 minute. Then for the 5 and 15 minute reports the end time should be taken from the returned end time of the 1 minute report. In this way you create a tic-mark every one minute, which can be used to generate the 5 and 15 minute reports over the desired time period. The following example shows how this could be done:

 

lpar_t iargs ;       /* arguments to define report */
lpar_t tlpar ;       /* temp lpar */
lpar_t host;  /*  identify server */
lpar_t cmdstats ;    /* the report is placed in here */
double end_time ;    /* end time for 5 & 15 minute report */
/* create the one minute report */
iargs = lpar_create_list(LPAR_LST_GENERIC) ;
/* for this exampled we retrieve search command stats */
lpar_append_list(iargs,
                 lpar_create_str(LPAR_STR_CMDNAME,DVK_CMD_SEARCH));
/* duration is 1 minute - 60 seconds */
lpar_append_list(iargs, lpar_create_dbl(LPAR_DBL_SUM_END, 60.0));
/* end time of now is the default */
/* get the report */
dvkerr = lkt_svrcmdstats(host, iargs, &cmdstats);
if (DVKERR(dvkerr)) {
        /* handle error here */
}
/* output report */
...
/* save our end time */
tlpar = lpar_find_lst_lpar_recursive(cmdstats, LPAR_DBL_SUM_END);
if (tlpar == LPAR_NULL) {
       /* this would be an error, end time should be returned */
       ....
}
end_time = lpar_get_dbl(tlpar) ;
/* clean up */
lpar_destroy(iargs) ;
lpar_destroy(cmdstats) ;
/* get 5 minute report */
iargs = lpar_create_list(LPAR_LST_GENERIC) ;
/* set command name */
lpar_append_list(iargs,
                 lpar_create_str(LPAR_STR_CMDNAME,DVK_CMD_SEARCH));
/* duration is 5 minutes - 5 * 60 seconds */
lpar_append_list(iargs, lpar_create_dbl(LPAR_DBL_SUM_DURATION, 5 * 60.0));
/* end time is end time of previous report, i.e. "now" */
lpar_append_list(iargs, lpar_create_dbl(LPAR_DBL_SUM_END, end_time));
/* get the report */
dvkerr = lkt_svrcmdstats(host, iargs, &cmdstats);
if (DVKERR(dvkerr)) {
        /* handle error here */
}
/* output report */
...
/* clean up */
lpar_destroy(iargs) ;
lpar_destroy(cmdstats) ;
/* 15 minute report, similar to the 5 minute report */
...

 

An alternative approach is to have a process or thread that requests a report starting at "now" every N seconds, and records the end time of the latest such report. Reports for any desired duration (up to 17 minutes) can then be generated with a resolution of N seconds by requesting the desired duration using the end time from the latest tic-mark request.

Input

host (required)

For more information, see Communicating with TIBCO Patterns Servers.

iargs (required)

is a generic list of the following parameters.

•

LPAR_STR_CMDNAME the name of a command for which statistics should be returned. This must appear at least once, and might appear multiple times. The command names are defined in the devkit.h include file. There is a special command name: DVK_CMD_ALL that can be used to indicate that statistics on all commands should be returned.

•

LPAR_DBL_SUM_DURATION sets the time span to be covered by this report. The time is given in seconds. If this is not given, or a value less than 0.0 is given the report covers the entire time span from the "end time" back to the start of the server or the last time the statistics for this command were last reset.

The actual duration covered by the report depends on when previous reports were generated as described above.

This parameter might be given at most once. It is not valid to give both this parameter and LKT_DBL_SUM_START.

•

LPAR_DBL_SUM_END sets the ending time of the report (most recent time included in the report). If this is not given or is less than 0.0 the end time is considered to be "now", the present moment, and this request creates a new tic-mark (see discussion above).

The end time is given in milliseconds from an arbitrary epoch point. Therefore the only valid way to get a specific end time is from the returned end time of a previous report.

This parameter might be given at most once. It is not valid to give both this parameter and LKT_DBL_SUM_START.

•

LPAR_DBL_SUM_START If specified this is a reset request and not a summary report request. All statistics for times at or before the given start time is deleted for the indicated commands. If the indicated time is less than zero all statistics are deleted (i.e. revert to zero).

The start time is given in milliseconds from an arbitrary epoch point. Therefore the only valid way to get a specific start time is from the returned start time of a previous report.

This parameter might be given at most once. It is not valid to give this parameter in combination with either LKT_DBL_SUM_END or LKT_DBL_SUM_DURATION.

Output

cmdstats (required)

if a reset was requested (LKT_DBL_SUM_START was given) this is set to LPAR_NULL. Otherwise a list of lists is returned, one list for each command requested. Each list contains the following lpars. Note that all times given are elapsed time in milliseconds, not CPU time.

•

LPAR_STR_CMDNAME The name of the command this report is for.

•

LPAR_DBL_SUM_START The actual start time for the report. This is given in milliseconds from an arbitrary epoch point.

•

LPAR_DBL_SUM_END The actual end time for the report. This is given in milliseconds from an arbitrary epoch point. Note that the actual duration of the report in seconds can be calculated as:

"( LKT_DBL_SUM_END - LKT_DBL_SUM_START ) / 1000.0".

•

LPAR_INT_NUMCOMMANDS gives the number of commands that were completed in the time covered by this report.

•

LPAR_DBL_SUM_MINPROC gives the minimum time in milliseconds taken to process one of the commands completed during the report time period. Processing time does not include time spent reading or sending data nor time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_MAXPROC gives the maximum time in milliseconds taken to process one of the commands completed during the report time period. Processing time does not include time spent reading or sending data nor time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_TOTPROC gives the sum of the processing times in milliseconds for all of the commands that were completed during the report time period. Processing time does not include time spent reading or sending data nor time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_MINOVERHEAD gives the minimum time in milliseconds spent on overhead for one of the commands completed during the report time period. Overhead time includes time spent reading or sending data and time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_MAXOVERHEAD gives the maximum time in milliseconds spent on overhead for one of the commands completed during the report time period. Overhead time includes time spent reading or sending data and time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_TOTOVERHEAD gives the sum of the overhead times in milliseconds for all of the commands that were completed during the report time period. Overhead time includes time spent reading or sending data and time spent waiting for a command processing thread to become available.

•

LPAR_DBL_SUM_MINFULL gives the minimum time in milliseconds taken to handle one of the commands completed during the report time period. Full time includes both processing and overhead time.

•

LPAR_DBL_SUM_MAXFULL gives the maximum time in milliseconds taken to handle one of the commands completed during the report time period. Full time includes both processing and overhead time.

•

LPAR_DBL_SUM_TOTFULL gives the sum of the full times in milliseconds for all of the commands that were completed during the report time period. Full time includes both processing and overhead time.

•

LPAR_DBL_SUM_MAXTHRU gives the highest average throughput seen, in commands per second, during any one minute time period covered by this report. Note that the one minute time period is subject to the same duration adjustments as for the reports as a whole. Thus if reports are requested only every 5 minutes this is actually over a five minute time period.

Error codes and items returned by lkt_svrcmdstats

EXPECTLIST	iargs (iargs was not a list)
PARAMVAL	LPAR_STR_CMDNAME (unknown command name given)
PARAMCONFLICT	Value in conflict. (start time with end time or duration.)
DBPARAM	The unrecognized parameter.
INTERNAL	None. (unexpected internal error)