The ININ.IceLib.Statistics namespace contains classes that provide access to IC system statistics and alerts. The statistics API allows developers to view the statistics catalog, parameters for statistics, and watch specific statistic values. The alerts API allows developers to view the alert catalog, create alerts, and respond to triggered alerts.

Watching Statistics

The StatisticCatalog uses watches to track changes to the catalog of statistics. This watch will track if a statistic is added, removed, or a property on the statistic has changed. This watch is only tracking the definition of the statistic, not the value that the statistic has. Once a statistic watch is in place, using StartWatching()()()(), the definition of every statistic in the system can be retrieved with GetStatisticDefinitions()()()(). If a single known statistic is needed, GetStatisticDefinition will retrieve a statistic based on a supplied StatisticIdentifier. To obtain an instance of the StatisticIdentifier class, using a source URI string, the StatisticKeyTemplate can be used along with the StatisticIdentifier property.

The ININ.IceLib.Statistics namespace does not include an API element for each available statistic. Instead, it is "metadata based", where the catalog of available statistics can be retrieved from the IC server through IceLib's statistics API. For for the list of available statistics see Statistics Catalog.

Listening to Statistics

The StatisticListener will listen for changes to a statistic value. StartWatching will start listening for changes to the statistic value for the supplied StatisticKey list. The StatisticValueUpdated event is raised when the value of the statistic of interest has changed.

Forming a Valid Statistic Key

Note

For a statistic key to be valid, all of the parameter types for a statistic key must be used, and they must be presented in the same order they are given in the statistic catalog. The second example of Watching a Statistic Value shows code that creates a proper statistic key that is also resilient to changes in required parameters.

Watching Alerts

The AlertCatalog uses watches to track changes to the catalog of alerts. This watch will track if an alert is added, removed, or a property on the alert has changed. This watch is only tracking the definition of the alert, not if the alert has triggered or not. Once an alert watch is in place, using StartWatching, alert sets can be retrieved with GetAlertSet. All of the AlertDefinition objects for a given statistic can be retrieved with GetAlertDefinitions. The AlertCatalogChanged event will be triggered whenever there is a change to the portion of the alert catalog that is currently being watched.

Listening to Alerts

The AlertListener will watch for changes to an alert state. StartWatching will start listening for alert trigger events for the supplied AlertFilterKey list. The AlertReceived is raised when an alert has been triggered and when that state is cleared. Although AlertChanged is on the AlertListener, it triggered in response to an alert catalog change event, indicating that some property on the alert has changed, not the state of the alert. This is provided only as a convenience, providing the same information that the AlertCatalog provides.

Handling Memos

The MemoList will watch for changes to lists of memos. There are three types of memo lists, lists of alert memos created with CreateAlertMemoList, lists of memos sent to the current user created with CreateMyMemoList and CreateGeneralMemoList for general, non-alerting memos. To create a new memo, the Memo class provides several factory methods to create a new Memo. After a memo is created, it must be commited with CommitMemo.

Note

The following are some examples of using the statistics namespace classes. It is assumed that an active session is present, a StatisticsManager instance has been created with the session, and saved in a variable named "_statisticsManager".

Jump to a code example:

Retrieving All Statistics

The following example illustrates how use the StatisticCatalog to retrieve a list of all statistics in the system.

CopyC#
StatisticCatalog catalog = new StatisticCatalog(_statisticsManager);
catalog.StartWatching();
ReadOnlyCollection<StatisticDefinition> statistics = catalog.GetStatisticDefinitions();

foreach (StatisticDefinition statistic in statistics)
{
    StatisticIdentifier id = statistic.Id;

    // Work with the statistic...
}

Back to Introduction

Retrieving a Statistic Value

The following example illustrates how to use the StatisticListener to retrieve the StatisticValue for a known statistic.

CopyC#
StatisticListener listener = new StatisticListener(_statisticsManager);
StatisticKey watchedKey = new StatisticKey(statistic.Id);
StatisticValue statValue;

listener.StartWatching(new[] { watchedKey });

statValue = listener[watchedKey];

if (!statValue.IsError && !statValue.IsNull)
{
    if (statistic.ValueType == StatisticValueType.Bool)
    {
        StatisticBoolValue boolStatValue = (StatisticBoolValue)statValue;
        bool value = boolStatValue.Value;

        // Work with the value...
    }
}

listener.StopWatching();

Back to Introduction

Watching a Statistic Value

The following example illustrates how to use the StatisticListener to watch the StatisticValue for a known statistic.

CopyC#
StatisticListener listener = new StatisticListener(_statisticsManager);
StatisticKey watchedKey = new StatisticKey(statistic.Id);

listener.StatisticValueUpdated += ListenerStatisticValueUpdated;

listener.StartWatching(new[] { watchedKey });

The following example illustrates how to use the StatisticListener to watch the StatisticValue for a known statistic with required parameters.

CopyC#
StatisticListener listener = new StatisticListener(_statisticsManager);
ParameterValuesDepot parameterValuesDepot = new ParameterValuesDepot(_statisticsManager);

listener.StatisticValueUpdated += ListenerStatisticValueUpdated;

ParameterValueKeyedCollection parameterValues = null;

// This way of watching a Statistic Value is resilient to changes in the number of required parameters
if (statistic.RequiredParameters.Count > 0)
{
    foreach (AssociatedParameterSetDefinition requiredParameter in statistic.RequiredParameters)
    {
        // Each AssociatedParameterSetDefinition will have its own set of RequiredParameters
        parameterValues = new ParameterValueKeyedCollection();
        foreach (ParameterTypeId type in requiredParameter)
        {
            ParameterQuery query = null;
            ParameterQueryResult parameterQueryResult = null;
            // The first parameter will be sent without any associated parameter values
            if (parameterValues.Count == 0)
            {
                // Create Parameter Query
                query = new ParameterQuery(type);
                // Get Possible Parameter values
                parameterQueryResult = parameterValuesDepot.ExecuteQuery(query);

                // Provide a way to select a specific parameter value
                foreach (var parameterValue in parameterQueryResult.Values)
                {
                    // Expose to the user or select a value programmatically
                    // For this example we will just select the first possible parameter value
                    parameterValues.Add(parameterValue);
                    break;
                }
                continue;
            }

            // The possible parameter values for the remaining associated parameters will change based upon the previously selected values
            // This is why the FilteredParameterQuery is used to retrieve the possible values for the rest of the parameters
            var associatedParameterValues = new List<ParameterValue>();
            foreach (var entry in parameterValues)
            {
                var pv = new ParameterValue(entry.Type, entry.Value);
                associatedParameterValues.Add(pv);
            }
            query = new FilteredParameterQuery(type, associatedParameterValues);
            parameterQueryResult = parameterValuesDepot.ExecuteQuery(query);

            // Provide a way to select a specific parameter value
            foreach (var parameterValue in parameterQueryResult.Values)
            {
                // Expose to the user or select a value programmatically
                // For this example we will just select the first possible parameter value
                parameterValues.Add(parameterValue);
                break;
            }
        }
    }

    // Start the watch for that AssociatedParameterSetDefinition
    StatisticKey key = new StatisticKey(statistic.Id, parameterValues);
    listener.StartWatching(new[] { key });
}
// No required parameters for the StatisticDefinition
else
{
    StatisticKey key = new StatisticKey(statistic.Id);
    listener.StartWatching(new[] { key });
}

The following code shows the event handler that will process the statistic change event.

CopyC#
void ListenerStatisticValueUpdated(object sender, StatisticValueUpdatedEventArgs e)
{
    StatisticValue statValue = e.StatisticValues[0];

    if (!statValue.IsError && !statValue.IsNull)
    {
        if (statValue.Definition.ValueType == StatisticValueType.Bool)
        {
            StatisticBoolValue boolStatValue = (StatisticBoolValue)statValue;
            bool value = boolStatValue.Value;

            // Work with the value...
        }
    }
}

Ensure that all watches are properly cleaned up when they are no longer needed.

CopyC#
listener.StatisticValueUpdated -= ListenerStatisticValueUpdated;
listener.StopWatching();

Back to Introduction

Retrieving All Alerts

The following example illustrates how use the AlertCatalog to retrieve a list of all alerts in the system.

CopyC#
AlertCatalog catalog = new AlertCatalog(_statisticsManager);
catalog.StartWatching();
ReadOnlyCollection<AlertSet> alerts = catalog.GetWatchedAlertSets();

foreach (AlertSet alert in alerts)
{
    foreach (AlertDefinition definition in alert.AlertDefinitions)
    {
        StatisticKey sourceStatistic = definition.StatisticKey;

        // Work with the alert...
    }
}

Back to Introduction

Watching for an Alert Trigger

The following example illustrates how to use the AlertListener to watch for an AlertRule to trigger or clear.

CopyC#
AlertListener listener = new AlertListener(_statisticsManager);
AlertFilterKey filterKey = new AlertFilterKey(alertSet, alertAction.TargetId);

listener.AlertReceived += ListenerAlertReceived;

listener.StartWatching(new[] { filterKey }, AlertListenerFilter.None);

The following code shows the event handler that will process the alert trigger event.

CopyC#
void ListenerAlertReceived(object sender, AlertNotificationEventArgs e)
{
    foreach (AlertNotification notification in e.AlertNotifications)
    {
        bool isTriggered = !notification.Cleared;
        AlertRule triggeredRule = notification.Rule;
        StatisticValue currentValue = notification.Value;

        // Work with the alert...
    }
}

Ensure that all watches are properly cleaned up when they are no longer needed.

CopyC#
listener.AlertReceived -= ListenerAlertReceived;
listener.StopWatching();

Back to Introduction

Watching Memos

The following example illustrates how to use the MemoList to watch for a non-alerting memo to be added.

CopyC#
MemoList list = MemoList.CreateGeneralMemoList(_statisticsManager);

list.MemoAdded += MemoAdded;

list.StartWatching();

The following code shows the event handler that will process the memo added event.

CopyC#
void MemoAdded(object sender, MemoEventArgs e)
{
    Memo newMemo = e.Memo;

    string text = newMemo.MessageText;

    // Work with the memo
}

Ensure that all watches are properly cleaned up when they are no longer needed.

CopyC#
list.MemoAdded -= MemoAdded;
list.StopWatching();

Back to Introduction

Creating a new Memo

The following example illustrates how to use the MemoList to create a new memo.

CopyC#
MemoList list = MemoList.CreateGeneralMemoList(_statisticsManager);

Memo newMemo = Memo.CreateMemo(_statisticsManager.Session, "A memo occurred",
    "Example Memo", null, false, null , false, DateTime.Now, null);

list.CommitMemo(listOfUserRecipients, listOfWorkgroupRecipients, newMemo);

Back to Introduction