« Back to Product

Documentation

Send feedback!

UC_GetKernelStatistics

 array UC_GetKernelStatistics (int $InstanceID)

Parameters

InstanceID

ID for the Util Control

Returns

An array with the following key => value pairs:

Index Type Description
MessageCounter integer Number of messages put into the message queue of the kernel since the start of IP-Symcon
MessageQueueDelay integer Waiting time of the oldest message not yet distributed in milliseconds (0 if the queue is empty)
MessageQueueSize integer Number of messages currently waiting in the message queue of the kernel to be distributed
MessageSlowCounter integer Number of messages whose processing in a kernel component took longer than "MessageQueueWatchLimit". Only with "MessageQueueWatch" enabled, otherwise always 0
RequestQueueSize integer Number of script executions currently waiting for a free PHP thread

Description

The function returns key figures that allow to assess the load of the kernel. All events in the system (variable updates, status changes, log messages, ...) are put into a queue as messages and distributed from there to all receivers. If MessageQueueSize and MessageQueueDelay keep rising, more messages are created than can be processed. The cause can be narrowed down with UC_GetMessageTypeList (which messages) and UC_GetMessageSenderIDList (which objects). A permanently high value of RequestQueueSize means that more scripts are started than PHP threads are available.

MessageCounter counts since the start of IP-Symcon, the rate results from the difference of two queries. MessageSlowCounter is only increased if the special switch "MessageQueueWatch" is enabled (e.g. with IPS_SetOption); the limit is defined by "MessageQueueWatchLimit" (default 50 milliseconds). The processing by the individual instances is recorded by IPS_GetInstanceMessageStatistics, their queues are returned by IPS_GetInstanceMessageQueueSize.

The ID of the Util Control instance can be determined e.g. with IPS_GetInstanceListByModuleID and the module GUID {B69010EA-96D5-46DF-B885-24821B8C8DBD}. If InstanceID does not exist, the function fails with "Instance #... does not exist", if the instance belongs to another module, with "Instance does not implement this function".

Example

// Determine the ID of the Util Control instance
$id = IPS_GetInstanceListByModuleID('{B69010EA-96D5-46DF-B885-24821B8C8DBD}')[0];

print_r(UC_GetKernelStatistics($id));

/* e.g. returns:
Array
(
    [MessageCounter] => 184
    [MessageQueueDelay] => 0
    [MessageQueueSize] => 0
    [MessageSlowCounter] => 0
    [RequestQueueSize] => 0
)
*/

// Determine messages per second
$before = UC_GetKernelStatistics($id)['MessageCounter'];
sleep(10);
$after = UC_GetKernelStatistics($id)['MessageCounter'];
echo 'Messages per second: ' . (($after - $before) / 10);
Any questions?