Some tips for IBM Business Monitor modeling and versioning

This article describes new modeling features since IBM® Business Monitor V7.5 and some best practices for a successful production monitoring environment.

Yan Fang (fangyyan@cn.ibm.com), Advisory Software Engineer, IBM

Yan Fang photoYan Fang is an Advisory Software Engineer on the Asia Pacific customer technical support team. She provides worldwide Level 2 technical support for WebSphere Business Modeler, WebSphere Business Monitor, WebSphere Business Compass, and Business Space.



Qing Zou (qingzou@cn.ibm.com), Staff Software Engineer, IBM

Qing Zou photoQing Zou is a Staff Software Engineer on the Asia Pacific customer technical support team. She provides worldwide Level 2 technical support for WebSphere Business Modeler, WebSphere Business Monitor, WebSphere Business Compass, and Business Space.



30 January 2013

Introduction

IBM Business Monitor (hereafter called Business Monitor) is a comprehensive business activity monitoring (BAM) software that provides an up-to-date view of your business performance and also provides predictions so that you can take action before problems occur. There are many things you need to consider when planning for a successful production monitoring environment. For some high-throughput environments, except tuning the monitor server and database, it is important to design a high-efficient monitor model. This article will provide some best practices for monitor modeling and versioning and will focus on a common developmental and administrative concept of Business Monitor referred to as "monitor model versioning".


Basic concepts of modeling and versioning

You can use the Business Monitor development toolkit to create monitor models for use with Business Monitor. The toolkit provides a mechanism to create and edit monitor models that can be transformed into executable code for Business Monitor. This section introduces some basic concepts and steps of modeling and versioning.

What is monitor modeling?

The IBM Business Monitor (formerly V7.0.0.* and earlier version of IBM WebSphere® Business Monitor) development toolkit provides the tools to create monitor models that can be transformed into executable code for Business Monitor. The toolkit runs on IBM Integration Designer or Rational® Application Developer, and includes the Monitor Model editor and the Business Monitor test environment.

Monitor models are XML documents that specify how information should be extracted from events at runtime and collected, combined, and stored for representation on a dashboard. The completed monitor model contains a monitor details model, key performance indicator (KPI) model, dimensional model, visual model, and event model. There are three ways to start creating a monitor model.

What is versioning?

The life cycle of a process application begins with the creation of the process application and continues through a cycle of updating, deploying, co-deploying, undeploying, and archiving the process application. Versioning is a mechanism used to manage the life cycle of the process application by uniquely identifying the individual versions of the process application.

In Business Monitor (V7.5.1 or V8.0), you can install multiple versions of a monitor model. Versioning refers to the situation where you modify aspects of a monitor model to fix problems or make enhancements (add a metric, monitoring context, and so on) and you want to install this new version of the model for future event processing and dashboard reporting, while preserving the data collected from previous monitor model versions.

You create new monitor model versions using the Monitor Model editor in the Business Monitor development toolkit. To version a model, update the model version time stamp, but leave the model ID as it is. The model version time stamp is in the format of YYYY-MM-DDTHH:MM:SS, for example, 2012-08-05T06:30:29. Using the development toolkit, you can produce an enterprise archive (EAR) file for each model version that is created. Each version of the EAR can be installed on the Business Monitor server independently, as long as the version time stamp on the model that is installed later than all previously installed model versions.

Once you have installed multiple monitor model versions, you can configure the dashboard views for a specific version of the monitor model or for a cross-version view of the monitor model. The cross-version view will display a "union" of the objects from each version. For example, if a second version of a monitoring context has removed a metric and added another metric, both metrics can be seen in the cross-version Instance View. All instances from both versions are displayed. However, null values are displayed for any metrics that were not defined in the monitor model version that processed the instance.

You can refer to the following Information Center links to understand key concepts about creating monitor model versions:

Modeling and versioning a monitor model

To create a monitor model in Monitor Model Editor, refer to Creating monitor models.

To version a Monitor Model, perform the following steps:

  1. The time stamp of a Monitor Details Model shown in Figure 1 differentiates one version of a Monitor Model with the other.
    Figure 1. Time stamp of a Monitor Details Model
    Time stamp of a Monitor Details Model
  2. In the Monitor Model editor in the Business Monitor development toolkit, change to the Business Monitoring perspective (see Figure 2). Click on the top-level MM, and look for the "Monitor Details" on the right. Click on the Edit button at the end of the Time Stamp (UTC) row. Select a time stamp that is suitable and of a later date than the previously existing one.
    Figure 2. Time stamp of a monitor details model for a new version
    Time stamp of a monitor details model for a new version
  3. We recommend that you specify the version number while generating the monitor models for the next version. Right-click on the Monitor Model from the Project Explorer page, and select Generate Monitor J2EE Projects. This displays a pop up with pre-filled values for the two J2EE projects to be generated, as shown in Figure 3. Add a suffix to these names to reflect the correct version of the monitor model being generated.
    Figure 3. Generate Monitor J2EE projects
    Generate Monitor J2EE projects

Deploying a new monitor model version

If you have an existing monitor model that monitors an existing application and business process, you can create a new version of the monitor model to monitor the application, regardless of whether the application and business process are currently versioned. This section describes how to deploy a new monitor model version.

Preparing the environment for deployment

Before a new version of a monitor model is deployed, you need to validate some existing monitor model version's setting to help the deployment go more smoothly:

  1. Stop the existing monitor model.
  2. Ensure the CEI Distribution Mode for the base version is active by clicking on the version link for the monitor model from the Monitor Models panel of the Admin Console (see Figure 4).

    Note: Since IBM Business Monitor V7.5, the queue bypass event delivery was renamed to "table-based event delivery".

    Figure 4. CEI distribution mode of monitor model
    CEI distribution mode of monitor model
  3. Review the permissions for the Monitor User in creating schema on the database. If the schema create permissions are not available, allow your database administrator (DBA) to create schema by exporting the CreateSchema ddl from the Admin Console.
  4. Export the V2 EAR file from the JEE perspective of IBM Integration Designer by right-clicking on the monitor model application for the V2 project (see Figure 5).
    Figure 5. Export the monitor model EAR file
    Export the monitor model EAR file

Deploying in a runtime environment

To deploy the new monitor model version, follow the standard procedure of deploying any monitor model.

Be sure to check for the changes in the CEI Distribution Mode as shown in Figure 6, while the new version tries to startup.

Figure 6. CEI Distribution mode for the new version
CEI Distribution mode for the new version

The older version for this monitor model will change the CEI Distribution Mode to "Active (No New MC)" as seen in Figure 7.

Figure 7. CEI distribution mode for older version
CEI distribution mode for older version

CEI distribution modes and their significance

The CEI distribution mode is a combination of the state of the monitor model and the transport type.

  • The possible states of a monitor model are:
    • Active
    • Active (no new MC instances)
    • Inactive (event queue recoverable)
    • Inactive
  • The transport types are:
    • Queue-based event delivery: This method uses Java Messaging Service (JMS) to deliver events from CEI to the monitor model.
    • Table-based event delivery: (In V7.0.0.* and earlier, it is known as queue bypass). This method uses a database table to deliver events from CEI to the monitor model. With table-based event delivery, the work can be distributed among multiple cluster members. For most environments, this method improves performance and simplifies the system configuration.

Note: The Inactive distribution mode is the same for both transport types.

A monitor model can have multiple versions deployed, but only the most recent version can have a common event infrastructure (CEI) distribution mode of "Active." Any number of previous versions, however, can have a CEI distribution mode of "Active (no new MC instances)". This means that events related to new monitoring context instances will go to the new version, while events related to existing monitoring context instances will go to the old version.

Alternatively, if you want active instances from the previous versions to be processed by the new model version, you would perform the following tasks:

  1. Before deploying the new model version, switch the CEI distribution mode of the previous version to "Inactive (event queue recoverable)".
  2. After deploying the new model version, transfer instances from the old version to the new version, and then change the CEI distribution mode of the new version to "Active".

Events that queue up for the old model version during this process will be recovered by the new model version when its CEI distribution mode is changed to "Active".

For your reference, the possible states of a monitor model version are listed below:

  1. Active: The new monitor model version is ready to consume events and the new monitoring context instances can be created as a result.
  2. Active (no new MC instances): Events for existing monitoring context instances are processed, but events that create new root monitoring context instances are ignored after the new monitor model version is active.
  3. Inactive: The model is not ready to consume events and events are not distributed to this monitor model version.
  4. Inactive (event queue recoverable): The older monitor model version is to be set to this mode, before the Active MCs are moved over to the newer monitor model version. Events are saved for a newer monitor model version to process. The events are not processed by the older monitor model version.
  5. Inactive To Active: The CEI distribution is in transition mode. The new monitor model version is not yet ready to consume events.

Verifying the new deployment

In the logs, be sure to check for this particular message shown below, which identifies that the new version is ready to consume new messages from the event source.

--------------------
[6/6/12 7:56:01:927 EDT] 0000004d MMRoutingConf I 
com.ibm.wbimonitor.lifecycle.routing.MMRoutingConfigFlow performNextStep 
CWMLC0804I: ***** 'GENERAL' integration sequence is COMPLETE. modelID: 'QPMon'

[6/6/12 7:56:02:792 EDT] 00000004 MTDaemonHandl I 
com.ibm.wbimonitor.mm.QPMon.20120530134016.server.moderator.serialmt.
MTDaemonHandlerImpl startDaemon() CWMRT3005I: The Monitor Model 
"QPMon 20120530134016" (codegen:BPM80 [20120503-2202.0], library:BPM80 
[20120503-2202.0]) is activating on this application server or cluster 
member in SERIAL_MT mode with reordering=true from JMS:20120530134016.
---------------------

Notes:

  • CWMLC0804I: This means the CEI distribution mode integration sequence for the specified model has completed successfully.
  • CWMRT3005I: This informational message indicates that an MM is ready to receive events on a particular target.

Once the new monitor model version is started successfully, you see that the CEI distribution mode changed to "Active" as shown in Figure 8.

Figure 8. CEI distribution mode for started a new monitor model version
CEI distribution mode for started a new monitor model version

Configuration changes in a cross-cell environment

In a cross-cell environment, there is one important configuration change that needs to be done when deploying or undeploying a new version of a monitor model.

When deploying a new version, a new event group profile is created on the remote CEI server. The details of the New Event Group Profile need to be copied over to the local CEI instance (on the Business Monitor server). Inversely, when undeploying a version of the monitor model, the event group profile for this version in the Business Monitor local CEI instance should be removed.

This is essential because any outbound event processing that needs to take place from the Monitor server needs a corresponding local event group profile and an event selector String to match these outbound events.

An absence of a local event selector string causes a failure of the outbound event processing and ultimately a loss in essential Business Monitor data.

The following set of steps helps you create the Event Group Profile to configure Business Monitor's local CEI instance for a new monitor model version's outbound event processing by using the queue-based or table-based event delivery (formerly known as queue bypass):

  1. In the navigation panel, select Service integration > Common Event Infrastructure > Event service.
  2. Under Additional Properties, click Event services.
  3. Click Default Common Event Infrastructure event server in the list of event services.
  4. Under Additional Properties, click Event groups.
  5. Click event_group.
  6. Click New.
  7. Enter wbm_model_version_Group for the Event group name.
  8. Enter value for the Event group selector string. The value must match the value of the event group created on the initial CEI server that was configured during the initial model deployment.
  9. Click OK.
  10. Click group_name for the event group you created.
  11. Table-based only: Under Additional Properties, click Custom Properties and add the following property.
    • name: customEventSelectorFilterClass
    • value: com.ibm.wbimonitor.xsp.cei.extensions.EventSelectorFilter
  12. Queue-based only: Under Additional Properties, click Distribution queues. Click New. Enter one of the following values for the Queue JNDI Name. The value must match the value of the distribution queue created on the initial CEI server that was configured during the initial model deployment.
    • model_id/valid from date as YYYYMMddHHmmss/Q
    • model_id/valid from date as YYYYMMddHHmmss/Q_A
  13. Queue-based only: Enter one of the following values for the Queue Connection Factory JNDI Name. The value must correspond to the Queue JNDI Name and must match the value of the distribution queue connection factory created on the initial CEI server that was configured during the initial model deployment.
    • jms/wbm/model_id/valid from date as YYYYMMddHHmmss/QF
    • jms/wbm/model_id/valid from date as YYYYMMddHHmmss/QF_A
  14. Click OK.
  15. Queue-based and table-based: Restart the CEI Server for the configuration changes to take effect.

New features for developing monitor models since V7.5

This section introduces new features of modeling and versioning in V7.5 and V8.

Multi-module monitoring with multi-key correlation wizard

Since Integration Designer V7.5, you can more easily generate monitoring models to process applications, BPEL, and other modules. Since Business Monitor V7.5, a wizard creates the module for you using the correlation that you specify. Model generators take care of correlation for you when monitoring a single source. With multiple sources, the toolkit user must do correlation manually.

For V7.5, the Global Monitoring Context wizard helps in the simple case where there is a common key used in every source.

For V8.0, the enhanced Global Monitoring Context wizard handles different keys per event source as follows:

  1. The wizard requires specification of the mapping of the key used from one monitor context to the key used in the next monitor context in the flow.
  2. A generated "global" key will be added to each low-level monitor context:
    • User-defined functions will be used in the generated map expression to determine the "global" key for a given "local" key.
    • The global monitor context will use this generated value as its key.
    • New tables <mm-schema>.globalmc_map_<timestamp> and mct_<global-mc-name>_glblmc_<timestamp> will be used.
  3. Start the wizard for the model as shown in Figure 9. If you have generated for this project previously, then this option is disabled.
    Figure 9. New Global Monitoring Context
    New Global Monitoring Context
  4. Name the new global monitoring context as shown in Figure 10.
    Figure 10. Name the global monitoring context
    Name the global monitoring context
  5. Create milestones to group the monitoring contexts. Here are three milestones for the example (Figure 11):
    1. Milestone "m1" contains Application and Analysis.
    2. Milestone "m2" contains Automated Approval and Manual Approval.
    3. Milestone "m3" contains Disbursement.
    Figure 11. Create milestones to group monitoring contexts
    Create milestones to group monitoring contexts
  6. Map the metrics for correlation as shown in Figure 12. There are two flows through the process:
    • The first contains Application, Analysis, Automated Approval and Disbursement.
    • The second contains Application, Analysis, Manual Approval and Disbursement.

    Each activity needs to know the key of the previous activity in the flow. For each mapping, specify the source context, source metric, target context, target metric, and mapping key. The mapping key is the metric in the target context that contains the correlation key for the source context.

    Figure 12. Map metrics for correlation
    Map metrics for correlation
  7. Add the metrics as shown in Figure 13.
    Figure 13. Add metrics to be viewed in the dashboard
    Add metrics to be viewed in the dashboard
  8. View the generated global monitoring context "glob" in the editor as shown in Figure 14.
    Figure 14. Generated global monitoring context
    Generated global monitoring context

For more information, see the Global Monitoring Context wizard topic in the Information Center.

Hiding metrics and monitoring contexts on the dashboard

This section describes how to hide from the dashboards when monitoring contexts, metrics, and KPIs. The default is visible. When hidden, you should not include monitoring contexts, metrics, and KPIs in the values returned from the REST services.

If a monitoring context is hidden, its cube is also hidden. If a metric is hidden:

  1. A KPI based on it is also hidden.
  2. Another metric based on it is not hidden.
  3. Dimensions and measures based on it are not hidden.

Expression KPIs are hidden if any referenced KPI is hidden.

For example, "Hide from dashboard" is unchecked for the metric "Loan Number" as shown in Figure 15, and for sub Monitoring Context "Automated Loan Setup BAM MC" as shown in Figure 16.

Figure 15. “Loan Number” with “Hide from dashboard” unchecked
“Loan Number” with “Hide from dashboard” unchecked
Figure 16. “Automated Loan Setup BAM MC” with “Hide from dashboard” unchecked
“Automated Loan Setup BAM MC” with “Hide from dashboard” unchecked

After generating the Monitor J2EE project and deploying to the runtime Monitor server, you can check the instance values in Business Space. When configuring the Instances widget settings, add both the metric "Loan Number" and sub monitoring context "'Automated Loan Setup BAM MC" to display them, as shown in Figure 17.

Figure 17. Configure Instances widget settings with the metric and sub MC
Configure Instances widget settings with the metric and sub MC

The instance widget displays as shown in Figure 18. Now the metric "Loan Number" and the sub monitoring context "'Automated Loan Setup BAM MC" display their values in the instance widget.

Figure 18. Instances widget with the metric and sub MC
Instances widget with the metric and sub MC

Now go back to Integration Designer to edit the monitor model as the second version with a new time stamp. Check "Hide from dashboard" for the metric "Loan Number" as shown in Figure 19, and the sub Monitoring Context "Automated Loan Setup BAM MC" as shown in Figure 20.

Figure 19. “Loan Number’” with “Hide from dashboard” checked
“Loan Number’” with “Hide from dashboard” checked
Figure 20. “Automated Loan Setup BAM MC” with “Hide from dashboard” checked

Save the changes, generate the new Monitor J2EE project, and deploy the second version of the application to the runtime Monitor server. Now you can check the instance values in Business Space again after checking "Hide from dashboard" for the metric and sub monitoring context. In the same Instances widget, after refreshing the page, you can see that the metric "Loan Number" and the sub monitoring context "Automated Loan Setup BAM MC" are not displayed as shown in Figure 21.

Figure 21. Instances widget after checked "Hide from dashboard"
Instances widget after checked

The metric "Loan Number" and the sub monitoring context "Automated Loan Setup BAM MC" have also disappeared from the Available and Selected lists of Instances widget setting, as shown in Figure 22.

Figure 22. Instances widget setting after checked "Hide from dashboard"
Instances widget setting after checked

Administering Monitor Model versions

You may encounter errors when you install or configure multiple versions or their properties. This section provides some common issues and suggestions when administering multiple monitor model versions.

Installing a new version of an existing model

If you find a problem in a deployed version of the model, you can use the distribution mode to facilitate its recovery. Change the CEI distribution mode to Inactive (event queue recoverable) for the problem version, and then repackage a new version to deploy. When you deploy a new version with the same filters and correlation keys, the new version will process the events that are queued up for the problem version. After the events are processed, you can remove the problem version.

When a new version of an existing monitor model is installed on a production mode server, all active monitoring context (MC) instances from the recoverable event queue versions must be moved to the new version. The CEI distribution mode of the new version can be set to "Active" if any previous versions have a CEI distribution mode set to "Inactive (event queue recoverable)."

The number of active MC instances for the previous version can be checked on the Version Details page for the previous version in the WebSphere Application Server administrative console. If the number is greater than 0, then the following LifecycleServices MBean method must be invoked before the CEI distribution mode of the new version can be set to "Active":

LifecycleResultsBean moveMCInstances( modelIDversionDatetoVersionDateactiveInstancesOnly )

Where:

  • modelID is a string type.
  • versionDate is a long integer type.
  • toVersionDate is a long integer type.
  • activeInstancesOnly is a boolean type.

This method can be invoked using the wsadmin utility:

set ls [$AdminControl completeObjectName type=LifecycleServices,*]

$AdminControl invoke $ls moveMCInstances { "modelID"  versionDatetoVersionDate true }

Where:

  • modelID is the ID of the model.
  • versionDate is the previous version with a CEI distribution mode set to "Inactive (event queue recoverable)".
  • toVersionDate is the new version.

Once the command has run to completion on the command line, check for the CWMDS2014I message in the profile's SystemOut.log (similar to the example below):

[10/29/10 16:17:47:961 EDT] 00000038 LifecycleAcce I 
com.ibm.wbimonitor.repository.LifecycleAccess processErrorQueueRecovery(byte[] 
oldVersion, Properties oldVersionNameMapper, byte[] newVersion, Properties 
newVersionNameMapper, Connection connection) 
CWMDS2014I: Queue recovery is completed without any error or warning. 
The number of successfully moved top-level instance records is 198.

To ensure this command has successfully completed for each previous version with active MC instances, you can now change the CEI distribution mode of the new version to "Active" using the "Change CEI Distribution Mode" link on the Version Details page for the new version in the WebSphere Application Server administrative console. If the moveMCInstances command fails and you can manually move the active MC instances via other means, or you decide to ignore the active MC instances, you can invoke the following LifecycleServices MBean method:

LifecycleResultsBean confirmMoveMCInstances( modelIDversionDatetoVersionDate )

You can then change the CEI distribution mode of the new version to "Active" as described.

Changing CEI distribution mode of multiple versions model

If the following conditions are met and you attempt to change the CEI distribution mode of a newly installed or previous version of a monitor model and specify new credentials, the authentication with the remote cell or server will fail and will result in failure of the CEI distribution mode change:

  1. Multiple versions of a monitor model are installed.
  2. The CEI target is remote.
  3. The CEI distribution mode of at least one version is not inactive.
  4. The credentials (user name and/or password) for the administrative user on the cell or server hosting the remote CEI instance have changed since the last version of the model was installed.

The error messages that are displayed in the administrative console vary based on the following scenarios:

  1. If you change the CEI distribution mode for a new monitor model version (in the Select Monitor model CEI options panel) during its installation, messages similar to the following are displayed. This is visible when you click Error displayed in the Deployment column in the Monitor Models panel, after the installation is complete:
    000009d1 LTPAServerObj E  SECJ0369E: Authentication failed when using LTPA. 
    The exception is <null>. 
    000009d1 ServletWrappe E  SRVE0068E: Uncaught exception thrown in one of the service 
    methods of the servlet: action. Exception thrown : java.lang.NullPointerException at 
    com.ibm.wbimonitor.admin.lifecycle.LifeCycleAdmin.addRoutingLayerReasonsMessages
    (LifeCycleAdmin.java:1029)
  2. If you change the CEI distribution mode for an existing monitor model version (in the Change CEI Configuration panel), you see messages similar to the following:
    0000002a LTPAServerObj E  SECJ0369E: Authentication failed when using LTPA. 
    The exception is <null>.
    0000002a LifecycleServ E com.ibm.wbimonitor.lifecycle.LifecycleServices 
    listTargetStates( String, long ) CWMLC0107E: Model [ClaimProcessingTracker] 
    version [2011-05-05T12:00:00] integration invalid. Cause: 
    [com.ibm.wbimonitor.observationmgr.spi.MMManagementException: 
    com.ibm.websphere.management.exception.ConnectorException: 
    ADMC0017E: Could not create an RMI connector to connect to host 9.37.100.100 at port 
    9810].

Although the administrative console allows you to change the CEI configuration information on the Select Monitor model CEI options panel when a new model version is being installed, Business Monitor will ignore that information unless all previous versions of the model have a CEI distribution mode of inactive. In the administrative console model install wizard, after you click Finish, but before you click Save, you see a warning message similar to the following:

CWMLC0257W: Model [ClaimProcessingTracker] CEI server configuration ignored.

In conjunction, a message similar to the following appears in the SystemOut.log file for the deployment manager (or standalone) profile:

LifecycleServ E com.ibm.wbimonitor.lifecycle.LifecycleServices 
applyCEIConfig( LifecycleCEIConfigBean ) CWMLC0112E: Model [ClaimProcessingTracker] 
version [*] step [applyCEIConfig] not allowed. Reason: [isActive=true].

Note that these messages do not indicate that the installation of the model is blocked. They simply mean that the existing CEI configuration for the model will be used instead of the new information provided in the wizard.

To solve this problem: If any version of the model has a CEI distribution mode other than inactive, the only way to change the CEI user ID or password (for all versions of the model) is to use the applyCEICredentials() method of the LifecycleServices MBean.

In Listing 1, updateCEICredentials.py is a sample Jython script illustrating the use of this method.

Note the following:

  1. The modelID, newCEIUserID, and newCEIPassword variables near the beginning of the script need to be modified to the desired values.
  2. Setting the CEI user name or password to an empty string ("") using the script will effectively "disable" security in the CEI configuration. Security is only considered "enabled" if there is a non-empty value for both user name and password. If either value is empty, no credentials will be submitted by Business Monitor when the RMI connection to CEI is established.
  3. The script should be executed from the "bin" directory of the appropriate profile. In a standalone environment, this is the Business Monitor server profile. In a network deployment environment, this is the deployment manager profile for the cell hosting Business Monitor. Use the appropriate command for your version of Business Monitor:
    • For Business Monitor V6.1.x:
      wsadmin -wsadmin_classpath "../../../plugins/com.ibm.wbimonitor.lifecycle.
      spi_6.1.0.jar" -lang jython -f updateCEICredentials.jy
    • For Business Monitor V6.2.x:
      wsadmin -wsadmin_classpath "../../../plugins/com.ibm.wbimonitor.lifecycle.
      spi_6.2.0.jar" -lang jython -f updateCEICredentials.jy
    • For Business Monitor V7.0.x or later:
      wsadmin -wsadmin_classpath "../../../plugins/com.ibm.wbimonitor.lifecycle.spi.
      jar" -lang jython -f updateCEICredentials.jy
    Listing 1. Sample code of updateCEICredentials.py
    from com.ibm.wbimonitor.lifecycle.spi.beans import LifecycleCEIConfigBean
    from com.ibm.wbimonitor.lifecycle.spi.mbeans import LifecycleServicesMBeanFactory
    
    # *** Change these values ***
    modelID = 'ClaimProcessingTracker'
    newCEIUserID = 'myUserID'
    newCEIPassword = 'myPassword'
    
    # get the MBean which will do the work
    ls_mbean = LifecycleServicesMBeanFactory.getMBean( AdminControl.getAdminClient() )
    
    # create a LifecycleCEIConfigBean that will contain the userid and password
    ceiConfig2 = LifecycleCEIConfigBean(modelID)
    ceiConfig2.setUserID(newCEIUserID)
    ceiConfig2.setPassword(newCEIPassword)
    
    # set the userid and password
    ls_mbean.applyCEICredentials( ceiConfig2 )
    
    # read the userid and password after the change
    ceiConfig3 = ls_mbean.readCEIConfig( modelID )
    if ceiConfig3 == None:
    		 print 'no CEI config'
    else:
    	print 'user='
    	print ceiConfig3.getUserID()
    	print 'pw='
    	print ceiConfig3.getPassword()

Setting a monitor model lifecycle step to a consistent state

You might encounter an error condition when trying to uninstall a monitor model. The error occurs when the META_MODEL_STEP_T table does not match the current state of the model. For example, you try to run the delete schema script, but the script cannot run because the step table indicates that the schema has not been created, even though the schema does exist. To resolve the error condition (for Business Monitor V7.0 and later), you can invoke an MBean method that forces the lifecycle step into a consistent state. Use the setModelStep method with the parameters modelID, versionDate, stepName, and isComplete to set the state of the step.

The setModelStep method has four parameters:

  • modelID: This is the model name
  • versionDate: This is the model version timestamp
  • stepName: This is the name of the lifecycle step that will be updated in the META_MODEL_STEP_T table. Note: The stepName parameter is case-sensitive.
  • isComplete: This sets the value of the IS_COMPLETE column in the META_MODEL_STEP_T table to one (1) or zero (0), where 1 is equivalent to true and 0 is equivalent to false.

The value of the stepName parameter indicates which lifecycle step will be updated. The most frequently used stepNames are:

  • configureCEIDistribution
  • confirmInstall
  • confirmUninstall
  • createAlphabloxCubes
  • disableDashboards
  • enableDashboards
  • rebootCEI
  • removeAlphabloxCubes
  • runCreateDMSScript
  • runCreateSchemaScript
  • runDeleteSchemaScript

Note: Before invoking the setModelStep method, make sure that the monitor model has been stopped.

In the following example, we deleted the schema for a model version. However, the monitor models version page reports that the schema still exists. This is indicated by a green check mark next to the Schema Created deployment step on the monitor models page in the administrative console. To force the Schema Created lifecycle step into the correct state, use wsadmin and the setModelStep MBean method as shown in the example code.

To start wsadmin, use this command:

wsadmin -lang <lang_type> -wsadmin_classpath <WAS_home>/plugins/
 com.ibm.wbimonitor.lifecycle.spi.jar

Where lang_type is either jython or jacl. The path specified for wsadmin_classpath uses forward slashes for all operating systems.

Here's the Jacl example for invoking the setModelStep method:

set lcMbean [$AdminControl queryNames type=LifecycleServices,*]
$AdminControl invoke $lcMbean setModelStep {MyModelID 20100629113451 
runCreateSchemaScript 0 }

Here's the Jython example for invoking the setModelStep method:

lcMbean=AdminControl.queryNames('WebSphere:type=LifecycleServices,*')
AdminControl.invoke(lcMbean, 'setModelStep', '[MyModelID 20100629113451 
runCreateSchemaScript 0]')

Tips for monitor modeling

This section provides some tips for monitor modeling.

Turn on only necessary event emission

The most important thing to keep in mind is that Business Monitor is intended for business monitoring, not for IT monitoring. Monitor models should be designed with relatively few inbound event definitions, which contain only relevant business payload. With this in mind, the following generally holds for most customers:

  • Customers are concerned about the state of their business and their processes. Therefore, events that signify changes in state are important. For long-running and human task activities, this is fairly natural; that is, use events to track when long-running activities complete, when human tasks change the state, and so on.
  • For short running flows that complete within seconds, it is usually sufficient to know that a flow completed, perhaps with the associated data. It usually makes no sense to distinguish events within a microflow that are only milliseconds or seconds apart. Therefore, two events (start and end) are usually sufficient for a microflow.

This approach is less of a strain on the environment being monitored, since it does not have to take as much time emitting events.

Model granularity

In Business Activity Monitoring scenarios, where you have a large number of events emitted from multiple flows from different source emitters, we recommend considering the approach of adopting a multilevel monitoring model hierarchy, where low level models tightly coupled to either flow-specific or event source-specific events aggregate measures and summarize them in generic outbound events to a higher level of monitoring models. This approach has the following benefits:

  • Dashboards are created based on high level monitoring models and not on low level monitoring models. Therefore, it gives developers the flexibility to modify, delete, and version low level models without having to disrupt the dashboard reporting operation on the higher level models.
  • Because low level models are not reported on, there is no need to generate Alphablox cubes for those models. Furthermore, these models can be transient in the sense that you can configure the scheduled data services to archive or prune old completed instances more frequently than the higher level monitor model, therefore improving data access performance. From a performance perspective, low level models can be more easily distributed across multiple server or cluster members to achieve better workload balancing.

This approach is not without a cost. More monitor models result in more resources (for example, JMS destinations) being created, resulting in a higher memory footprint. In addition, the large number of monitor models may result in a maintenance and administration overhead, and could make detecting and debugging errors more difficult. Care should be taken when designing the monitor models' granularity and hierarchy.

Namespace in event schema

Use namespaces in any customer-defined events and corresponding schemas. More specifically:

  • In XML schemas, always define a targetNamespace.
  • In XML schemas, always specify elementFormDefault="qualified" and attributeFormDefault="qualified".
  • In XML documents, such as events, avoid using the empty prefix. That is, ensure that all element and attribute names have a namespace prefix and declare those prefixes.

Set proper action for each event

By default, all the activity entry or human task created event will create a new instance when no instances are found, even when they are located in the same monitoring context as process start event. It is better to change the action of those events to "Retry". If the "other" event arrives first, route it to the retry queue until the first event has come through and created the required instance. Otherwise, if the events did not arrive in sequence, for example, a human task created event arrived before the process start event and the first process state will be "human task start" and then "process start", Business Monitor consumes the human task created event first. This may result in some errors in the monitoring result.

Use event groups instead of monitoring contexts

When generating a monitor model from BPEL, choose to monitor BPEL activities as "Event Groups" within the process monitoring context, instead of monitoring BPEL activities as "Monitoring Contexts". Monitoring Contexts are expensive. This will reduce the number of Monitor Contexts tables, and subsequently the number of cubes. Only use separate monitoring contexts when the activity has multiple instances for each process instance.

Multithreading

The Business Monitor runtimes have two event processing strategies:

  • V6.0.2 emulation, also known as serial consumption single-threaded processing.
  • Scalable processing (formerly known as "V6.1 multi-threaded" in V7 and earlier), also known as serial consumption multi-threaded processing.

The Scalable processing strategy is recommended because it supports event reordering and supports the failed event queue and partitions events according to an event partition path and processes multiple event streams in parallel. In addition, this strategy can increase performance throughput in cases where Business Monitor is deployed on a clustered multi-member environment. However, for this mode to be available during monitor model deployment, the monitor model needs to have an event unique instance ID (also called root-instance correlation predicate) for every inbound event definition. That is, all events need to have the same set of keys; otherwise, scalable processing strategy will not be allowed.

The event unique instance ID is a value carried in the event that ties related events together. It is the key for the root monitoring context derived from the correlation expressions (also called correlation predicates) of each event type. To have an event unique instance ID (also called root-instance correlation predicate) for every inbound event definition, the following rules on the correlation predicate expressions should be met:

  • Each top level monitoring context must have a key metric that is of type string. For example, call this metric "TLKM".
  • Every inbound event in that top level monitoring context and every inbound event in any descendent monitoring context must have a correlation expression defined with a comparison of the form "TLKM = <some expression which does not reference other metrics>" or "TLKM eq <some expression which does not reference other metrics>".
  • The correlation expression comparison must not have a subject "or." You can use "or" in the expression, but this comparison (or the subexpression that it is in) must never be "or" with another subexpression.
  • The correlation expression comparison (see Figure 23) must not have a subject "and" with another subexpression, which has the form "TLKM2 = <some expression which does not reference other metrics>", or "TLKM2 eq <some expression which does not reference other metrics>", where TLKM2 is a key metric in a top level monitoring context. Note that there must be only one candidate for the top level key metric.
Figure 23. Correlation expression
Correlation expression

The key "ClipsAndTacks Key" is associated with the top level monitoring context, "ClipsAndTacks MC." The key "ClipsAndTacksKey" is also of type string. In the key definition, the A value is required when this key check box is selected.

  • The inbound event "New Order Event" has a correlation expression that does not reference metrics other than the key.
  • The correlation expression for "New Order Event" does not contain an "or".
  • The correlation expression for "New Order Event" does not contain an "and". Only one key is used in the expression.

Figure 24 shows an example of a correlation expression that does not meet the criteria and allows the "6.1 multi-threaded" event processing strategy to be selected.

Figure 24. Example of a correlation expression
Example of a correlation expression

Use recurring wait-time trigger with care

In Business Monitor V7 or earlier, it is important to use recurring wait time triggers with care. There are two cases, which can compound each other, where such triggers can be dangerous:

  • If the interval between evaluation of the trigger is short.
  • If there are many active instances against which the trigger needs to be evaluated.

For example, if an ATM environment handles an average of one customer per minute in each of 100 ATMs and each customer produces an instance that stays active until a monthly bank statement closes (some customers make multiple withdrawals in a month, all handled by the single instance for that customer for that month), this means that at any given time there are over 1,000,000 active instances. If an instance level trigger is defined to be evaluated every 15 minutes, that could be an average of more than 1,000 trigger evaluations per second, keeping the server so busy it could potentially impact its ability to keep up with the inbound events arriving on its queue.

You can refer to the following IBM technotes on tuning time-based triggers in Business Monitor V7 or earlier:

Since Business Monitor V7.5, full model scalability (moderator and model logic EJBs from previous versions combined into a single EJB that can actively run on multiple nodes in a cluster) was added, and with that, it was felt that the need to modify the recurring wait time check interval for time based triggers was diminished. So there is no "Recurring wait time check interval" property in the monitor model runtime configuration in Business Monitor V7.5 or later.

Judicious use of the deliver-to-all capability

Another Business Monitor model construct to use with care is the deliver-to-all capability on inbound events. There are many valid scenarios for using this function, such as a special kind of (rare) event that causes evaluation of a trigger in all active instances, matching a certain correlation expression (an event driven, rather than polling-based approach to detect business situations). However, there are also cases where this can lead to overloading a server. In the preceding ATM example with 1,000,000 active instances, if an event that correlates to a third of those instances arrives once every 5 minutes, this also results in an average of more than 1,000 event deliveries per second. In response to that one occasional inbound event, the server could potentially be taxed to the point that it cannot keep up with its other inbound events.

Define proper filters for each event

Pay attention to the filter when you define the inbound event by yourself. The filter can distinguish events from each other. Otherwise, Business Monitor may treat the events as two events and handle it for multiple times. This causes unexpected errors. For example, if the context starting and terminating events have the same filter string, the monitoring context will be terminated when the context starting event arrives. When the terminating event occurs, it creates another instance with the same key. This results in duplicate instances.

Do not use empty string as a default value for a metric

We do not recommend to use an empty string of "" as a default value for a metric. Instead, use " " or "None" in the metric default value. Otherwise, when the database is using Oracle®, Oracle will take the empty strings as null. But, a value is required for the metric when an instance is created. As a result, there will be some exceptions when you insert the record into the database.

Judicious use of triggers

Some monitor models have too many triggers. A pattern that is seen frequently is "event > trigger > metric", where the trigger fires unconditionally when the event arrives. However, metrics that depend on inbound events (via a map) are automatically updated when those events arrive, and so there is no need for the trigger. The model can be simplified to "event > metric".

If the metric is only updated under certain conditions, for example, if the event is "urgent" or contains other special indicators, then the map can use an "if-then-else" expression. A pattern that is often useful is if "condition indicating that myMetric should be updated", then "new value expression" else myMetric, which will update the metric only under the condition in the if-clause. Otherwise, leave it unchanged. There are some situations that do require triggers, especially when an update sequence must be enforced that does not naturally follow from the data-dependency. However, those should be well-understood exceptions and rare in practice.

Avoid the divisor being zero in the KPI calculation

When defining KPI calculations, make sure you check for the divisor being non-zero. For example, change:

Number_Red_Light_Processes div Total_Number_Processes

To:

if (Total_Number_Processes ne 0) then (Number_Red_Light_Processes div 
Total_Number_Processes) else (0)

Remove unnecessary cubes

There is a cube per Monitoring Context if using Business Monitor V7.5.1 or earlier. Usually, customers do not need a cube at each level. Remove unnecessary cubes from the dimensional model (available as of Business Monitor V6.1.1 on DB2®, as of V6.1.2.3 on Oracle) if there are no other user-created measures or dimensions in the cubes. Refer to Tuning Alphablox for WebSphere Business Monitor environment for recommendations on optimizing performance.

Naming rule for ID

Name your metrics, MC, and so on with short IDs. As there are some limitations, take Monitor Model ID as an example:

  • The schema is identical to the Monitor Model ID if the number of characters of the Monitor Model ID is less than 26 characters.
  • If the number of characters of the Monitor Model ID is greater than 26 characters, two operations are performed on the ID to minimize the number of characters generated:
    • Remove all the vowels out of the name of the schema.
    • Truncate the number of characters that are more than 26 characters.
  • For example, the Monitor model ID is:
    TestMonitorModel1abcdefghijklmnopqrstuvwxyz12345

    After the removing all of the vowels, it will be:

    TstMntrMdl1bcdfghjklmnpqrstvwxyz12345

    Then it will be truncated to:

    TstMntrMdl1bcdfghjklmnpqrs

Therefore, if the ID is too long, there may be a collision after the two operations are performed.


Conclusion

Business Monitor models are XML documents that specify how information should be extracted from events at runtime and collected, combined, and stored for representation on a dashboard. For some high-throughput environments (except for tuning the monitor server and database), it is important to design a high-efficient monitor model that describes business measures, dependencies on incoming events, conditions that warrant business actions, and outbound events that report these conditions and trigger business actions. This article addressed some best practices for monitor modeling and model versioning and described what you need to consider for a successful production monitoring environment.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=856692
ArticleTitle=Some tips for IBM Business Monitor modeling and versioning
publish-date=01302013