Supporting the PATROL Configuration Manager and the PATROL KM for Event Management

PATROL Configuration Manager support within PATROL KMs is required to provide users with the ability to perform the following actions by using the PATROL KM for Event Management:

• Adjust thresholds and poll-times
• Activate and inactivate objects
• Manage events

These actions can be performed for all PATROL KMs and are the minimum level of centralized configuration functionality that users expect for the KMs in the PATROL Configuration Manager. 

The externalization of configuration required for these tasks also provides customers with an easier path to KM migration. Since configuration settings are stored as PATROL Configuration Manager rules and agent configuration variables, customers can migrate the KM code and simply re-apply their configuration settings.

The following topics are discussed in this section:

Store user configurable KM data in pconfig database

You must store user configurable KM data in the pconfig database, which allows your KM configuration data to be directly accessed and, when appropriate, managed by the PATROL Configuration Manager.

In this context, "User configurable data" is defined as any data that is used to perform one of the following actions:

• Configure the KM
  For example, this might include information required for Oracle DB monitoring, such as username, password, instance name, exclusion lists, etc.
• Modify behavior of a KM
  For example, this might include inclusion lists, exclusion lists, and activation and deactivation flags to control subsets of management.
  Do not use external files or registry type management to store user configurable KM data. If an external file were to dictate KM configuration, the PATROL Configuration Manager would not be able to modify KM configuration because the PATROL Configuration Manager can only access pconfig. The PATROL Configuration Manager cannot access any external configuration files.
  Do not use any non printable characters in the names or values of entries in the pconfig database.

Do not use the change_state function instead of a threshold on a parameter

Do not use the change_state function to alter the initial state of the application instances. Instead, provide a corresponding parameter-level status indicator, which allows the user to create events and adjust thresholds through the PATROL KM for Event Management. 

In general, the state management of an instance must be controlled though a parameter-level object, such as a status parameter. Event propagation automatically reflects the desired instance state for which you are looking. Having a status-type object at the parameter level allows users to manage the event details and whether the state change is propagated upward without the need of altering the delivered KM code. 

However, you can use change_state to activate and deactivate features if going from online to offline. 

The following list is a guide on when to use the change_state function in PATROL and when to use a status parameter. The team must decide which is the best way to depict the current status of the product, either through change_state or the use of a status parameter, such as boolean, stoplight, or graph.

• Initial configuration--discovered application/server is not configured; can use change_state to OFFLINE <> OK
• Feature not installed--can use change_state to OFFLINE <> OK
• Feature never licensed--can use change_state to OFFLINE <> OK
• Application discovered but not configured - Can use change_state to OFFLINE <> OK
• Feature license removed/revoked (manual operation, deliberate)-- can use change_state to OFFLINE <> OK
• Discovered application/entity has been excluded(included) from(for) being monitored (deliberate action)--can use change_state to OFFLINE <> OK
• Feature not working (serious issue)--use a status parameter
• Feature no longer licensed (expired, but was working before; serious issue)--use a status indicator, such as a parameter
• Server down--use a status parameter
• Server having problems--use a status parameter
• Application down--use a status parameter
• Application failed over--use a status parameter
• Application not responding (but alive)--use a status parameter

Use a pconfig rule to alter parameter polling intervals

Do not alter parameter polling intervals internally or dynamically in the code. When a KM is loaded for the first time and the initial values are set, use a pconfig rule to make any subsequent changes to the parameter intervals (poll times). You must use the same pconfig rule that is accessible to the user through the PATROL Configuration Manager. 
The pconfig() function call must be used in lieu of the set() function call to memory. 
If a collector's poll time is changed in the KM's code programmatically, and if the customer using the PATROL Configuration Manager also modifies the same Collector's poll time, the customer's values will be overwritten.

Use a pconfig rule to alter the initial value of a parameter's built-in variable

Do not alter the status of a parameter's built-in variable programatically or dynamically in the code. When a KM is loaded for the first time and the initial status is set, use a pconfig rule to make any subsequent changes to the parameter status. You must use the same pconfig rule that is accessible to the user through the PATROL Configuration Manager. The pconfig() function call must be used in lieu of the set() function call to memory. 

For example, if a parameter's active flag is changed in the KM's code programmatically, and if the same parameter's active flag is also modified using the PATROL Configuration Manager, there will be inconsistencies in the way the parameter turns active and inactive.

Do not use the event_trigger function for event messages

The KM must not use the event_trigger or event_trigger2 functions to generate events that are implicitly generated by PATROL. The KM must rely on the PATROL Agent to generate events when alarm ranges are exceeded.

Use only alphanumeric characters when naming objects

The KM must use only alphanumeric characters when naming objects such as application names, instances, and parameters, within the KM. Begin the object name with an alphabetic character. Do not start an object name with a numeric character. 

The characters a through z, A through Z, 0 through 9, and _ (underscore) are the only characters known to be acceptable to be used in object names. 

The following characters are known to cause problems when used in object names: 

dot(.), comma(,), space( ), tab, carriage return, line feed, colon, and slash 

Ship all default KM configuration settings as standard RuleSets

You must ship all default KM configuration settings as a standard RuleSet for the KM. The RuleSet must include any configuration that is unique to the KM, not just thresholds and alarm ranges. 

Doing so provides the customer with out-of-the-box RuleSets in the PATROL Configuration Manager and with a convenient starting point to modify the KM configuration.

Handle an incorrect pconfig value

Your KM must be able to handle an out-of-range pconfig value by substituting a value that is within range. Your KM must notify the user of the value that was substituted for the out-of-range value. 

To handle the incorrect pconfig value, your KM must update pconfig with the value that is within range and log the variable name, the original bad value, and the substituted value.

Do not use sleep periods if annotating data points

If annotating data points, do not put in a sleep period between when the parameter is set and when the annotation is made unless absolutely necessary. 

One method of avoiding sleep periods is to have the parameter collect the data value and then if the data value would require annotation, collect the annotation before setting the parameter's value. 

For example, a parameter goes into alarm and is to be annotated; however, there is a sleep period separating the setting of the parameter value and its annotation. If a recovery action which involves retrieving the annotated value is defined for that parameter, the recovery action will execute immediately upon the alarm condition of the parameter but might not be able to retrieve the annotated text because of the built-in sleep condition. This affects the way the PATROL KM for Event Management's recovery actions work if they use of the annotate_get function.