A technical walk-through of how the PerformanceGuard backend server works.

Anchor
concept366 concept366

Backend Server Telnet Interface

The backend service exposes a Telnet interface. By default the Telnet server runs on port 4005, but the port number may be changed using the telnetPort parameter.
In order to log in to the backend service Telnet interface you need to supply the name and password of the PerformanceGuard administrator. By default this is

1. User name: admin
2. Password: admin

The following is a snapshot of a Telnet session, with the built-in command overview:

PerformanceGuard Backend Server

login: admin
password: *****

>help

Commands:
  conf                 - Shows server configuration
  exit | quit          - Exits this admin session
  help                 - Shows this message
  history              - Shows history of commands
  jobs [cancel|start]  - Lists/cancels/starts database aggregate jobs
  log [level] [regexp] - Shows server log, where level is INFO,FINE or FINEST
                           (level must be at least what is in logging.properties)
  refresh              - Refreshes configuration/filters
  select ...           - Executes database request
  shutdown             - Shuts down the server
  stat [code]          - Shows server statistics
       recv            - Shows receivers
       alarms          - Shows number of alarms
       sent            - Shows number of sent notifications
       fail            - Shows number of failed notifications
       data secs       - Shows data counters
  test                 - Send test notification e-mail to default receiver
  test name            - Send test notification e-mail to named receiver
  status               - Shows database & time status
  version              - Shows server version
  dump [variable]      - Dump internal data
        cache          - Dump internal cache
        server         - Dump server
        connections    - Dump ConnectionPool and the corresponding thread information
  ![number]            - Re-executes the command 'number'
  ee                   - List the Id and filter running in the eventengine.
        list           - List the running filters in the event engine and their id number.
        list [number]  - Dump the state of a specific filter/container with the 'number'
        count          - list the number of events sendt around in the event engine.
        pool           - list the thread pool data.
        dispatch       - list the event receivers subscribing to event types from the dispatcher.
        tick           - list the number of event send from the TimeTickDispatcher and the latest send time.
        info           - list the event statistic from on the event dispatcher.
        info [num]     - list the count of the different events going through event dispatcher.
        dump [number]  - Dump the state of a specific filter/container with the 'number'
        path [number   - Output the information path to a given event receiver/container with the 'number'
        notify [number]- Triggers a event container to send a event notification.
        conf [number]  - Output the configuration of the elements of the event path.
        test           - List the test available to run on the event engine.
        test [number]  - Run the test.
        clean [number] - Removes the stored data in a filter/container.
        diff timestamp - Calculates difference to currenttime.
>

Event Engine Configuration

The configuration of the event engine is used to set up the event engine and create the event paths from the event dispatcher to the event containers. The configuration of the event engine is placed in the db table event_containers_config_param.

The table contains two rows. A Key row and a Value row. Both are String type.

Key Structure

The key is a string to make it easy to read. The key is structured to in levels bisected by ".".

So, a key like this "AllFrontendsOffline.1.SeverityType" should be read:

Information Read Direction
The reading of the configuration information in the database takes place in a fixed direction determined by information need, starting with the 'general' key it traverses the configuration.

'EventparthKey'.'UnitId'Specific.# information needed when initializing a specific event path unit.
Example:
The example is only to show the read direction. Is not a full event path.

For a given read the key name is the last part of the key and is what the code is looking for at that specific point in the configuration read.

List of #

In various places in the configuration it's necessary to define multiple values for the same base key. When this is the case, a "key.number" is used to distinguish between the different keys.
This is used when the code can receive multiple inputs, for example multiple receivers for events.
At present the only usage for the list feature is:

It isn't necessary for the numbers to start from 1 or be incremental or continuous.

Recursive Value Read

The way a key is read is reverse recursive. Starting by looking for the key name in the current key path position.
The last part of the key is the key name, and the first is the key path.

1. If the key name is not percent on a given key path level the code try to find the key name a level higher.
2. If reaching the highest event path level "EventParthName" and still not finding the key name, it tries the key path "General".
3. If still not finding the key the code, it either:
   1. Doesn't enable the feature
   2. Inserts a default value
   3. Throws an exception.

This is done to reduce the need for multiple keys containing the same value for multiple units in a event path, while we still have the option to define the key name directly on a given key path.
Example:

1. FrontendsOnline.1.DBStoreTime
2. FrontendsOnline.DBStoreTime
3. General.DBStoreTime

The key name "DBStoreTime" is used by the event containers as a unit under an event path, but because all the event containers at this point in time use the same store time, there is no need to write the key name other places than in General.

Key Description

Some of the values are very code-specific and not very easy to read without access to the "common.EventTypes.java" file.

General

Default timespan to be used by the elements using a calculation window. value can be milliseconds or \[Report*\]#, delivery*#, or

Event Path
Event path units.

Event Container
The event container receives the events from the filters or directly from the event dispatcher basic input. It stores the current state for a given interval or until changed by new events.
If any changes occurs in the event container, it saves the new state to the database.
When receiving events, the event container keeps the event for a time and thereby keeps a record of the state. If the state changes (not just update) the event container writes its new state to the database.
Event Container Parameters
Event path is removed to save space.

Event Container Optional Parameters

Filters
The event filters are the building blocks of the event containers that shape/calculate on the data flowing into the event engine.
The input parameters vary a lot from filter to filter.
ActivEventFilter
The filter's function is to change single events into a state.
The filter keeps a record of all the events it receives, sending out one event when receiving an unknown event and storing the event in an internal list.
Subsequent events received with the same ID won't trigger an event, but the internal time stamp of the event will be updated.
If the time stamp of an event is older than the allowed time window, the filter deletes the event and sends a remove event with id event.
This has two benefits:

1. It limits the number of events entering the EventContainer and being written into the database
2. it gives a clear definition of No/Off

Parameters:

ActivityCountFilter
The filter counts the incoming events for a given period of time and delivers a value event containing the number of events received.
The filter keeps a record of all the events it receives updating the time stamp for every new event with same ID. If an event becomes to old, it's removed by the filter. Once every TimeWindow period it counts the number of events in the internal list. If the number of distinct events in a specific grouping is over a trigger value, the filter send out one value event per grouping containing the number of events in each grouping.
Used by the "Agents online" filter path.
Parameters:

ChangeEventTypeFilter
The change event filter changes the event type ID from one to another. The event is not affected in any other way.
If the incoming event's type is not in the filters internal type list, the event will be discarded. The filter can be loaded with multiple event type sets to facilitate many changes (there is no destination differentiation).
Parameters:

GroupByFilter
The filter function is to give an event a grouping value based on the ID of the event and the selected grouping type (normally the event ID is the Agent ID) .
The filter has an internal map linking the agent ID to different groupings (location, CPU type, OS type, ...).
So defining the grouping type as OS will give the event the grouping value of the agent OS (for example Win7).
Parameters:

MissingEventFilter
The missing event filter function is to keep a list of the events received sorted by grouping. If a grouping becomes empty all of a sudden it should send a event with all the agents in that group.
Inserting new events into a internal list. Updating the time stamp when receiving events with same ID. Once every time window it cleans the lists. If an event's time stamp is too old, the filter removes the event from the internal list.
If the number of events in a grouping goes from (user defined value) to zero in one time window, the filter sends an event containing all the events that timed out.
Filter sets the grouping as EMPTY internal.
If the filter receives an event matching the (EMPTY) grouping, a grouping online again event is sent and the EMPTY flag is removed.
Parameters:

ValueEventFilter
The value filter received value events and based on the event value and a preset trigger value it sends a value event when the value is surpassed.
When surpassed it can either send an event every time or only once per event if only sending when the state changes.
Parameters:

Complex Parameters
Some of the values in the configuration are complex. They are described in more detail here.
TimeWindow Value Types
TimeWindow can have the following values:

1. Any integer

2. Wiki Markup
   Delivery*\[the number of delivery intervals\]

3. Wiki Markup
   Report*\[the number of delivery intervals\]

4. Description.Parameter.#

A parameter can have the following values

1. a string value
2. key reference to another value on the same level ( Frontend.TrigValue )

Order of Event Path Elements.
When setting up a new event path, it's important to include the elements in the reverse order of the event flow.
To link an event part element as receiver to a event stream, it must already be present in the system.
Grouping Types

1. Changing your event management configuration so that fewer events are generated, for example by changing some of the thresholds used.
2. Using more powerful equipment for running PerformanceGuard.
3. Increasing the number of events that PerformanceGuard is able to queue. If you choose to increase the number, this is how you do it:
   1. Open SQL Server Management Studio and connect to the server that runs the PerformanceGuard backend server
   2. Expand the database pguard, and then open the table pguard.config_params
   3. Increase the value of the parameter maximum.nr.events.in.eventqueue.berfore.busy so that more than the default 100000 events can be queued