This is part of a group of documents and examples commonly referred to as the System Management Methodology (SMM). The SMM provides information and techniques as examples of how an administrator uses the standard features of IBM Cognos Administration along with IBM Cognos Business Intelligence functionality in order to increase their own productivity and pro-actively manage IBM Cognos BI applications, users, and servers. By combining the live view of IBM Cognos BI system activity provided by the IBM Cognos Administration features with system trending information using the reporting and analytical features of IBM Cognos BI, administrators can get a full view of BI system utilization.
Additional information about the Administrative features of IBM Cognos BI are available within the IBM Cognos Business Intelligence Administration and Security Guide.
The documented information and technique(s) apply to all IBM Cognos Business Intelligence v10.1.1 installations. Although precautions are taken to ensure that the information and technique(s) span newer releases, some of the content may become obsolete and/or no longer applicable.
Content found in an appendix pertains to previously released System Management Methodology topics/techniques that have been replaced with a newer technique. The newer technique(s) will appear in the regular chapters of the document. When a new topic/technique is added that replaces a technique, it will be highlighted in the document.
Exclusions and Exceptions
The scope of the documents in this series may not include detailed steps on how to use the product as this information is contained within the core product documentation. For example, the document “System Management Methodology For IBM Cognos 10 – Setting Thresholds” deals with thresholds that can be applied to the system metrics. The document offers guidance on how to interpret those metrics to apply default thresholds programmatically but does not include the actual steps required to manually set or modify a threshold.
Using Tivoli Directory Integrator to Load IBM Cognos System Metrics into a System Trending Database
This document is part of the IBM Cognos System Management Methodology and focuses on a predefined Tivoli Directory Integrator (TDI) project which provides the ability to connect to the IBM Cognos BI environment and programmatically extract the related metrics via JMX.
The technique applies to environments that have an installed instance of Tivoli Directory Integrator and an IBM Cognos Business Intelligence environment that has enabled access to system metrics via JMX.
NOTE: If the IBM Cognos environment has not been enabled for JMX access, this technique will not work as documented.
Included with this document is a ZIP file containing the sample components necessary to easily load IBM Cognos BI system metrics into a relational reporting database that can be used for system trending reports and archiving of system metrics. The components include,
- CognosMetrics.xml - a TDI assembly line
- CognosMetrics.bat – a Windows batch file used to run the TDI assembly line
- CognosMetrics.properties – a TDI properties file used to customize TDI to match your IBM Cognos BI environment
- MbeanListForMetics.txt – a file used to filter the IBM Cognos system metric types to be loaded into the reporting database by TDI
Accessing System Metrics via JMX
IBM Cognos BI system metrics are maintained by the Cognos Dispatcher and stored within JMX MBeans. When system metrics values are viewed within the IBM Cognos Administration Console, the values presented within the Metrics status panel are read from the system metric MBeans. These same metric values can also be read directly from the MBeans using any JMX monitoring tool such as JConsole which is included with a Java Development Kit (JDK) or an enterprise monitoring solution such as IBM Tivoli Monitoring. For IBM Cognos BI version 10.1 and 10.1.0.1, the external JMX interface is disabled by default, has a default port of 9999 and must be enabled by editing a properties file before MBeans can be read by a JMX monitoring tool. As of IBM Cognos BI version 10.1.1 (RP1), the external JMX interface is enabled by default, has a default port of 9700 and is managed through IBM Cognos Configuration.
For IBM Cognos BI v10.1.1 (RP1), the URL for the external JMX interface is,
For IBM Cognos BI v10.1.0.1 or older, the URL for the external JMX interface is,
Enabling the external JMX interface for IBM Cognos BI Version 10.1.0.1 or older
Before the metrics can be exposed to external sources, the Java MBean must first be made available for external access. To accomplish this, a parameter must be added to one of files within the application server. For a default Tomcat installation,
- Navigate to the <install_dir>\webapps\p2pd\WEB-INF directory and open the file p2pd_deploy_defaults.properties in a text editor such as Notepad or vi.
- Search for the line
#rmiregistryport=9999and uncomment it by removing the leading '#' character.
- Set the port number to the desired value. The default value is 9999.
- Save the file.
- System metric MBeans can now be accessed externally via the RMI proxy URL (for example service:jmx:rmi://bisvr01/jndi/rmi://bisvr01:9999/proxyserver).
Managing the external JMX interface for IBM Cognos BI Version 10.1.1
As of IBM Cognos BI v10.1.1, the external JMX interface is enabled by default and is configured to use port number 9700. You may also elect to secure the connection to the external JMX interface by configuring a user name and password that would be required before connections to the JMX interface are permitted.
You can manage both the TCP port number and the credentials for the external JMX interface using the Environment Properties within IBM Cognos Configuration.
- Open IBM Cognos Configuration on an IBM Cognos BI server.
- Within the Explorer Panel, click Environment.
- Modify the External JMX Port and External JMX credential properties as required to fit your environment.
Illustration 1 - IBM Cognos Configuration external JMX port and credential settings
The TCP port value defined using either the rmiregistryport property, (for Cognos BI versions 10.1 and 10.1.0.1), or the External JMX port property, (for Cognos BI version 10.1.1 or newer), will be used to to configure a property within TDI called cognos.jmxport (section 4.1).
Deploy the CognosMetrics project to the TDI Solutions Directory
In order to install the CognosMetrics TDI project, simply unzip the contents of the file CognosMetrics.zip into the top level of your TDI Solution Directory. The default TDI Solution Directory location for Windows installations is a folder called TDI under your home directory (for example, C:\Documents and Settings\userName\My Documents\TDI).
NOTE: Ensure that you keep the folder structure from the CognosMetrics.zip file intact when extracting the files.
After extracting CognosMetrics.zip, the resulting folders and files within your TDI Solution Directory will appear similar to the following,
/TDI /CognosMetrics CognosMetrics.bat CognosMetrics.properties CognosMetrics.xml MbeanListForMetrics.txt /configs /etc /libs /logs /MqePWStore /serverapi /workspace
Modify properties for your environment
As the TDI project was not created in your environment, some changes will be required to the property values before it can be executed successfully. First, provide connection properties for the database that you will use to collect IBM Cognos BI system metric trending data. Next, provide the IBM Cognos BI server name and port for connecting to JMX MBean information.
- Using a text editor open and edit the file CognosMetrics.properties to update the TDI properties for your environment.
- db.url - the URL required to connect to the server hosting the system trending database
- db.driver - the JDBC driver to be used when connecting to the system trending database
- cognos.servername - the name of the IBM Cognos BI server that will be used to collect system metrics
- cognos.jmxport = the TCP port number configured and enabled earlier using either the rmiregistryport property in the p2pd_deploy_defaults.properties file or the External JMX port property within IBM Cognos Configuration (depending upon your version of IBM Cognos BI).
TDI Property RDBMS Example Value db.url DB2 jdbc:db2://DB2SVR01:50000/METRICS SQL Server jdbc:sqlserver://SQLsvr01;DatabaseName=METRICS;SelectMethod-cursor db.driver DB2 com.ibm.db2.jcc.DB2Driver SQL Server com.microsoft.sqlserver.jdbc.SQLServerDriver cognos.servername all BISVR01 cognos.jmxport all 9999 or 9700
- Customize the db.user, db.password, db.schema, and db.tableName properties as required to connect to the system trending metrics database within your environment.
- After completing your updates save and close the file.
db.password Property Encryption
The value for the db.password property can be entered in clear text however, once the Assembly Line is run for the first time, TDI will update the properties file and encrypt the value that is stored within CognosMetrics.properties. Before the CognosMetrics Assembly Line is run for the first time, the db.password property will appear as follows within CognosMetrics.properties,
After the Assembly Line is run, TDI will encrypt the value for db.password within the CognosMetrics.properties file and the db.password property will appear as follows:
Customize monitored services
This sample integration technique for IBM Cognos BI and IBM Tivoli Directory Integrator is configured to extract and write metrics for all of the IBM Cognos services. If there is a requirement or desire to limit the range of focus, there is a configurable text file that can be modified to reflect the desired services.
Opening the MBeanListForMetrics.txt file will display the IBM Cognos service names designated for monitoring. The following list shows all available services for IBM Cognos 10.1.
The TDI assembly line reads from this file to determine which service metrics will be written to the system trending metrics relational database. To alter which services are being monitored, simply remove the appropriate service(s). For example, if a particular administrator was only interested in the reporting services, all of the services could be removed except the report and batch report services. The resulting text file would look like this,
Running the project
Included within the CognosMetrics package is a batch file named CognosMetrics.bat. Once the customizations have been made to the TDI properties, the CognosMetrics assembly line can be run interactively or deployed to run via a scheduler using CognosMetrics.bat.
The CognosMetrics.bat may need to be customized in order to run within your environment. Open the file CognosMetrics.bat with a text editor such as Notepad or vi and modify the environment variable tdihome so that it matches your TDI installation.
Errors and Logging
Errors generated during a run of the CognosMetrics assembly line will be written to either the TDI CE console (if you are running this interactively) or to the command window (if you are using the CognosMetrics.bat file). TDI will also create log files for the CognosMetrics assembly line each time it is run. The log files are located within the logs folder of your TDI Solutions Directory and are named CognosBISystemMetrics.log, CognosBISystemMetrics.log.1, etc. A new version of the log file will be created for each run of the assembly line. Log files are kept for the last 15 runs of the CognosMetrics assembly line.
Most errors encountered with the CognosMetrics assembly line will be due to one of two problems.
- Misconfigured properties within the CognosMetrics.properties file. For example, an invalid password for the database user credentials or an incorrect value for the IBM Cognos server and rmiregistryport.
- Unavailable connections. Maybe your RDBMS server is down or the IBM Cognos server is down or misconfigured.
The technique documented in this document programmatically connects to the IBM Cognos Java environment, reads the IBM Cognos application metrics, and then writes the metrics and values to a relational database. The purpose of this operation is to provide near real time monitoring through IBM Cognos reporting.
To leverage this technique and to easily adopt the other techniques and reporting content provided as part of the System Management Methodology, the relational database called METRICS should be created with the following column names and data types (or similar data types depending on the database vendor).
|Column Name||Data Type||Allow Nulls?|
|Value||float or double||yes|
Once the TDI assembly line has been run for the first time, you will have system metrics within the System Trending database and can now begin using IBM Cognos BI dashboards and reports to understand the ongoing health and utilization of your IBM Cognos BI applications and platform.
Schedule your TDI assembly line to run on a periodic basis in order to maintain an ongoing and historical view into your system health.
|Sample scripts for this article||SMM_For_IBM_Cognos_10-Loading_Metrics_with_TDI.zip||61KB|