Step by step how-to on integrating your application with IBM Tivoli Monitoring 6.1

As a customer or business partner looking to hook an application to IBM® Tivoli® Monitoring 6.1, it may seem like a daunting task. But follow our step by step guide, and you'll find that integrating your application to IBM Tivoli Monitoring can be the easiest IBM integration you've done. We will describe scenarios in the Retail industry and steps on how to get the "Ready for IBM Tivoli software" validation.

Andrew R. Freed (afreed@us.ibm.com), Advisory Software Engineer, IBM

Andrew R. Freed is an Advisory Software Engineer at IBM's Research Triangle Park facility in North Carolina. He has spent the last two years on the WebSphere Remote Server team, specializing in monitoring solutions. He is the author of the WRS Data Provider.



Anhdao Nguyen ( anhdaon@us.ibm.com), Contract Software Engineer, IBM

Anhdao Nguyen is a Contract Software Engineer, ISV and Developer Relations of Developer Technical Support Center at IBM Innovation Center in Dallas, Texas. She supports and validates Business Partners integration projects with IBM Tivoli Monitoring and IBM Tivoli Composite Application Manager for Response Time Tracking products through the Ready for Tivoli Program.



Vinod Bijlani (vbijlani@in.ibm.com), Solution Architect, IBM

Vinod Bijlani is a Solution Architect working with the Industry Solutions Team in IBM India. Vinod has been architecting, designing and developing On Demand Retail Solutions and his focus is on InStore Systems and MultiChannel Retailing.



Albert Wong, I/T Architect, IBM Retail on Demand EBO , OCSolutions

Albert Wong is an IT Architect with IBM Retail On Demand Emerging Business Opportunities (EBO), the IBM skunk works organization with the mission to increase IBM business and technical solutions within the Retail industry. Due to the dynamic nature of the EBO, his skills span the whole spectrum of IT business and technical development from technical pre-sales, solution design and implementation, offering development to ecosystem enablement. He is the author of several IBM developerWorks articles and has an IBM developerWorks blog named Pragmatic Open Computing Blog.



Anhdao Nguyen ( anhdaon@us.ibm.com), Contract Software Engineer, IBM

Anhdao Nguyen is a Contract Software Engineer, ISV and Developer Relations of Developer Technical Support Center at IBM Innovation Center in Dallas, Texas. She supports and validates Business Partners integration projects with IBM Tivoli Monitoring and IBM Tivoli Composite Application Manager for Response Time Tracking products through the Ready for Tivoli Program.



28 June 2007

Introduction

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Architect retail solutions with the IBM Retail Industry Framework

In this article, we provide you a “how to” guide on integrating your application with IBM Tivoli Monitoring 6.1, IBM's health and performance monitoring tool. Within this article, we'll give you business pain points that IBM Tivoli Monitoring addresses, provide you sample integration scenarios, and explain how to get the maximum benefit from your integration with Tivoli through IBM's Ready for Tivoli program, all from a Retail Industry point of view.

What is monitoring? Why do monitoring? Why do you care?

So what does IBM mean by monitoring? Although there are many facets of monitoring, for the context of this article, it's from the point of view of health and performance. So what is health and performance monitoring? It's the ability to see if the system is working and how well is it working. By knowing how a system is working, you have the information and ability to proactively (for example, react to out of paper situations) or reactively (for example, find out why there is a degradation of IT systems) respond to quality of services issues. In any business where the availability of critical systems is paramount like Retail, health and performance monitoring systems are a requirement.

Health and performance monitoring in Retail

Retailers have hundreds, or perhaps thousands, of geographically distributed stores. Each store contains an array of hardware, applications and retail specific devices and solutions, for example, point-of-sale (POS) terminals; self check-out machines, signature capture devices, payment systems, digital media displays, RFID shelves, and kiosks. Monitoring these hardware and software assets is a complex problem. Typically, the retail stores have little or no local IT experience, and as a result, the management of all of the stores is done from a centralized location. The issue that IBM typically sees in this environment is that usually, non-local IT folks don't have enough information or the correct information from the store IT systems to quickly diagnose a problem and get the store back to normal operations. Factor in financial implications like x amount of reduced capability time equals y loss in revenue, and you can imagine that there is a huge expectation on all the various parties who use and maintain the IT systems in the store.

IBM's holistic approach to the store, the IBM Store Integration Framework

Before We jump into the architecture discussion, we want to give a brief history of IBM's retail industry experience.

IBM has forged a proven track record through 30 years of global experience in the Retail sector, including nearly two million POS terminal installations worldwide. Our capabilities go far beyond industry-leading technology to include consulting, store support services, and a vast network of 1,500 IBM Business Partners worldwide. For decades, we have also actively participated in retail thought-leadership groups, including those engaged in creating, expanding and improving open, industry technology standards, and we continue to spearhead the formation of new technology standards. Our experience and attention to your needs as a retailer are reflected in the capabilities, features and standards of IBM Store Integration Framework (SIF).

IBM understands that as a store becomes more complex with the addition of mobile devices (Web pads, self check-out, kiosks, RFID tags, and dynamic displays); the underlying infrastructure must support new technology and the older technology that is currently in place. In the past, store infrastructure has largely been vendor driven -- disparate, redundant technologies that are hard to support and expensive. IBM Store Integration Framework delivers the next-generation store platform. IBM Store Integration Framework provides the foundation for integrating existing store solutions, adding new solutions and touch points, and integrating the store to the enterprise. Unlike the typical store configuration, this is a fully integrated environment based on industry standards. The IBM Store Integration Framework supports the integration of IBM and Business Partner POS solutions and hardware from various providers. IBM Tivoli Monitoring is a core piece of the IBM Store Integration Framework and provides the health and performance monitoring of the network, hardware, operating system, middleware and applications that are deployed on the IBM Store Integration Framework.

Figure: IBM Store Integration Framework
IBM Store Integration Framework
Figure: The open standards that are used in the IBM Store Integration Framework
open standards used in IBM Store Integration Framework

Getting started on your integration to IBM Tivoli Monitoring

So you want to get started. Well, although there are many components that make up IBM Tivoli Monitoring (the presentation server, the management server, and universal agents), for the sake of connecting your application to IBM Tivoli Monitoring, all you have to do is integrate your application to the IBM Tivoli Monitoring universal agent (the generic IBM Tivoli Monitoring agent). In the following sections, we're going to talk about how to integrate your application to IBM Tivoli Monitoring Universal Agent.

We assume that you already have an IBM Tivoli Monitoring 6.1 environment deployed, including the monitoring universal agents. Check the Resources (make this an active link to section below) section for additional information.

IBM Tivoli Monitoring architecture

Figure: IBM Tivoli Monitoring 6.1 architecture
IBM Tivoli Monitoring 6.1 architecture

IBM produces several monitoring agents for the IBM Tivoli Monitoring infrastructure. This article focuses on using the Universal Agent, but IBM produces many other remote agents. For example, IBM Tivoli Composite Application Monitoring for WebSphere®, IBM Tivoli Monitoring for Databases, and Operating System monitoring agents.

Planning what to monitor

A typical retailer might want to monitor the following:

  • Is my POS application running?
  • Is my POS application running well?
  • How many transactions are being processed (and how long does each one take)?
  • Is the database responding quickly to requests?

Sometimes you simply want to know the value of an attribute - how many transactions are being processed? In most cases, you want to raise errors when certain things happen. For example, when the average response time exceeds two seconds or when the application is not running. When planning what to monitor, you must consider whether you are looking for information or for errors.

With error and event tracking, you must also plan event severities and responses. For example, if the application is not running, it is a critical error and there should be a response action to restart the application. If the database is running slowly, this is probably a minor event that does not require an immediate response.

In this article, we focus only on monitoring attributes of applications.

Planning how to monitor

The IBM Tivoli Universal Agent supports several different ways of collecting monitoring data. Data is collected for the Universal Agent using a data provider. The Universal Agent supports a wide variety of data providers.

Universal Agent data providers:

  • File - Monitors data in a sequential text file, such as a log file.
  • API - You can send data to the Universal Agent from scripts and C and C++ programs. This data provider also supports a command-line interface which implements a subset of the API functions.
  • Socket - Can be used by any programming language which supports sockets.
  • Post - An ad hoc version of the socket data provider.
  • HTTP - Monitors the availability and response time of selected URLs.
  • SNMP - Monitors any industry standard MIB or any MIB you supply.
  • Script - Collects monitoring data by running a script or program at regular intervals and parsing the script output to look for errors, anomalies and threshold conditions.
  • ODBC - Collects data from ODBC-compliant databases using SQL Select statements and stored procedures supported by the particular ODBC source that is being monitored (Windows® only).

Complete descriptions of all possible Universal Agent data providers are found in the "About data providers" section of the Tivoli Universal Agent User's Guide

Additionally, the WebSphere Remote Server team created a Java™ Management Extensions (JMX)-capable data provider called the WRS Data Provider. This data provider can directly query JMX servers for attribute and event data.

We recommend using the File, API, Socket data providers, and the WRS Data Provider for the following reasons:

  • File - Potentially requires no modification of the application, and works with applications in any language if they log.
  • API - Easiest way to add monitoring to a C and C++ application.
  • Socket - Works with applications in any language that supports sockets.
  • WRS Data Provider - Easiest way to add monitoring to a Java application.

Doing the monitoring

We present three sample applications and the artifacts required to monitor them:

  • Java - Monitoring of J2SE and J2EE applications, using JMX and the WRS Data Provider
  • C++ - Monitoring of a C++ application using the Universal Agent API data provider
  • Log file - Monitoring of a log file from a PHP application using the Universal Agent File data provider

In each example, we assume the Universal Agent has been installed on the machine running the application. For information on installing the Universal Agent, see "Chapter 5 - Installing Tivoli Monitoring" of the IBM Tivoli Monitoring 6.1 Installation and Setup Guide. For the Java example, we also assume the WebSphere Remote Server (WRS) Data Provider has been installed as part of a WRS Solution. For more information on installing the WRS Solution, see the WRS 6.1 Infocenter


JMX monitoring

This section describes monitoring two Java applications with JMX and the WRS Data Provider.

Description of Java application

Company A has created a J2EE solution that runs on WebSphere Remote Server. The solution consists of two applications that process transactions for customers. Both applications are instrumented in JMX so that Company A can do remote monitoring of the applications.

Applications:

  • Example 1: A standalone J2SE application that runs on POS terminals
  • Example 2: A J2EE application with a Web interface that is accessed via kiosks

Company A will deploy their solution at a pilot store. For simplicity, the Java applications, as well as the WRS Data Provider and the Universal Agent, are deployed to the same machine.

Instrumenting the application for monitoring with JMX

(We assume you are familiar with the basics of JMX. If not, read the JMX tutorial from Sun Microsystems.)

Company A developers only have to make a few small changes to their application to use the power of JMX. For the pilot deployment of their application, they will only monitor summary statistics of recent transaction history. They create only one MBean, which will expose these statistics in a class called TransactionManager.

By JMX naming standards, the MBean interface for the TransactionManager class must be called TransactionManagerMBean. This interface must define all the methods Company A wants to expose via JMX. Company A chose four summary statistics to expose as read-only MBean attributes.

TransactionManagerMBean: MBean interface for TransactionManager
 public interface TransactionManagerMBean { 

    public long getTotalTransactions();
    public long getTransactionsLastFifteenSeconds();
    public long getTransactionsLastMinute();
    public long getTransactionsLastHour();
	 }

Company A then modifies their TransactionManager class to implement the TransactionManagerMBean class. This forces them to implement methods that generate the four exposed summary statistics. In addition, Company A decides that they want to generate alerts every time the terminal processes a transaction. For this, they make TransactionManager extend the javax.management.NotificationBroadcasterSupport class. TransactionManager is now a legal MBean.

TransactionManager: MBean implementation
 public class TransactionManager extends NotificationBroadcasterSupport 
 implements TransactionManagerMBean{ 

  ...

    public long getTransactionsLastHour() {
       return getTransactionsInInterval(60L * 60L * 1000L);
    }

    public long getTransactionsLastMinute() {
       return getTransactionsInInterval(60L * 1000L);
    }

    public long getTransactionsLastFifteenSeconds(){
       return getTransactionsInInterval(15L * 1000L);
    }

    public synchronized long getTotalTransactions(){
       return (long) this.transactions.size();
    }

    /** In a real application, this would probably be a database lookup. */
    private synchronized long getTransactionsInInterval(long interval){
	...
    }
 }

Now that Company A has created an MBean, they must register the MBean into an MBeanServer so that it is visible outside of the running Java Virtual Machine. There are two parts to registering MBeans into an MBeanServer:

  1. Get a connection to an MBeanServer.
  2. Register each MBean to that MBeanServer.

Company A creates generalized methods for each of these processes in a class called JMXUtils.

Most J2EE application servers come with a built-in MBeanServer. This MBeanServer is automatically initialized -- all your code has to do is get a reference to it. Company A put this code into a static initialization block within the JMXUtils class.

Referencing an existing MBeanServer
 ArrayList servers = MBeanServerFactory.findMBeanServer(null);
 if (servers == null || servers.size() == 0) {
    throw new Exception("No MBeanServer found in this environment");
 }

 MBeanServer server = (MBeanServer) servers.get(0);

Note that in a J2SE application, you can create your own MBeanServer. Code exercising this functionality is in the J2SE sample application in the Sample Code section.

When the MBeanServer has been initialized, you can register MBean objects within that server. To promote loose coupling, Company A places this code in a generalized initialization method within the application.

Registering an MBean to an MBeanServer
Object obj = TransactionManager.getTransactionManager();
server.registerMBean(obj, "Freedville:name=TransactionManager");

if (obj instanceof NotificationBroadcaster) {
   ((NotificationBroadcaster) obj)
	addNotificationListener(listener, null, null);
}

With the addition of this code, Company A has created an MBean and exposed it to external applications. Now we will see an external application use the exposed MBean.

Integration with WRS Data Provider

Company A ultimately wants to integrate their applications with IBM Tivoli Monitoring. They read about how the Universal Agent can send data to IBM Tivoli Monitoring, and believe it is the right agent for their applications. Unfortunately, the Universal Agent does not natively support JMX data. They remember that WebSphere Remote Server comes with a utility called the WRS Data Provider, which bridges any JMX data source into the Universal Agent.

The WRS Data Provider allows you to specify any number of JMX data sources and attributes you want to monitor in IBM Tivoli Monitoring. It communicates with the Universal Agent via a custom socket protocol, and must be installed on the same system as the Universal Agent. Company A creates a WRS Data Provider configuration file specifying how to connect to their applications via JMX as well as which MBeans and attributes should be monitored. Company A also specifies that they want the alerts that are generated by their application to be forwarded to IBM Tivoli Monitoring.

A configuration file for the J2EE application (the J2SE sample is similar)

<WRSDataProvider> 
    <application name="WAS"
	   description="Kiosk POS application"
	   JMXServerURL="service:jmx:iiop://localhost:2809/jndi/JMXConnector"
	   collectionInterval="20000">
      <events objectNameQuery="Freedville:*" />
      <env key="java.naming.factory.initial"
	   value="com.ibm.websphere.naming.WsnInitialContextFactory" />
      <env key="java.naming.provider.url"
	   value="iiop://jmxwas:2809" />
      <env key="com.ibm.CORBA.ConfigURL"
 	   value="file:C:\Progra~1\IBM\WebSphere\AppServer\profiles\AppSrv01\
 	   properties\sas.client.props" />
      <env key="com.ibm.SSL.ConfigURL" 
 	   value="file:C:\Progra~1\IBM\WebSphere\AppServer\profiles\AppSrv01\
           properties\ssl.client.props" />
      <attribute-group
	   name="J2EESample"
	   description="Example2 J2EE Application"
	   objectNameQuery="Freedville:name=TransactionManager,*"
	   delimiter="^^">
	 <objectNameComponents>
	    <objectNameComponent
		 name="name"
		 displayname="MBean Name"
		 description="Uniquely identifies an MBean"
		 length="20" />
	 </objectNameComponents>
	 <attributes>
	    <attribute 
		 name="TotalTransactions"
		 displayname="Total transactions"
		 type="Numeric" />
	    <attribute 
		 name="TransactionsLastFifteenSeconds"
		 displayname="Last 15 seconds"
		 type="Numeric" />
	    <attribute name="TransactionsLastMinute"
		 displayname="Last Minute"
		 type="Numeric" />
	    <attribute
		 name="TransactionsLastHour"
		 displayname="Last hour"
		 type="Numeric" />
	 </attributes>
      </attribute-group>
   </application>
</WRSDataProvider>

The configuration file specifies several important entities:

  • JMXServerURL - Where the JMX server can be contacted
  • collectionInterval - How often (in milliseconds) to collect attribute data
  • events objectNameQuery - Which MBeans to listen to for events
  • Environment variables needed when connecting to the JMX server
  • attribute-group objectNameQuery - Which MBeans to gather attribute data from
  • objectNameComponents - Which parts of the MBean's ObjectName will be passed with the message (used as a primary key)
  • attributes - Which MBean attributes will be monitored

The WRS Data Provider also needs its classpath extended so it can download an RMI stub from the JMX server. Update the classpath in C:\Program Files\IBM\SIF\WRSDP\bin\setupCmdLine.bat or /opt/IBM/SIF/WRSDP/bin/setupCmdLine.sh.

Advanced: Running your applications on a different machine than the Universal Agent

In the wrsdp-config.xml file, you can specify JMXServerURL entries for remote machines. In any case, the WRS Data Provider must still run on the same machine as the Universal Agent.

Configuring the Universal Agent to monitor the Java applications

The WRS Data Provider configuration file must be saved to C:\Program Files\IBM\SIF\WRSDP\etc\wrsdp-config.xml or /opt/IBM/SIF/WRSDP/etc/wrsdp-config.xml.

Next run the import_metafiles.bat script (C:\Program Files\IBM\SIF\WRSDP\bin\import_metafiles.bat or /opt/IBM/SIF/WRSDP/bin/import_metafiles.sh), which generates Universal Agent metafiles for each of the Java applications and configures the Universal Agent to use these metafiles.

Finally, start the applications, and restart the WRS Data Provider (Windows Service WRSDataProvider or using start/stop scripts in /opt/IBM/SIF/WRSDP/bin). New entries will be available in the Tivoli Enterprise Portal. Click the Navigator Update Pending button and your application data will be visible under platform Systems->hostname->Universal Agent->hostname:JSE00, platform Systems->hostname->Universal Agent->hostname:JMX00, and platform Systems->hostname->Universal Agent->hostname:WAS00, where platform is Windows or Linux®, and hostname is the hostname of the system with the Universal Agent.


C++ monitoring

This section describes monitoring a C++ application with the Universal Agent API data provider.

Description of C++ application

Company B has created a C++ application that processes transactions for customers. Company B wants to do remote monitoring of the application, and has decided to extend the application for monitoring using the Universal Agent API data provider.

Instrumentation of the application for monitoring with the Universal Agent API

Company B developers only have to make a few small changes to their application to use the power of the Universal Agent. For the pilot deployment of their application, they will only monitor summary statistics of recent transaction history. Their application already maintains these statistics via a struct:

struct TransactionStatus { 

   int Register_ID;
   int Min_Trans;
   int Max_Trans;
   int Ave_Trans;
   int Total_Trans;
   int Total_Count;
   int Input;
};

Company B decides to install the Universal Agent on the same machine as their application, even though the Universal Agent supports API clients on remote systems.

The development team must add three segments of code to integrate their application with the Universal Agent:

  1. Connect to the Universal Agent
  2. Send data to the Universal Agent
  3. Disconnect from the Universal Agent

The following code was added to their application startup section, to connect to the Universal Agent:

 include "KUMPAPI.h" 

 ....
 do{ 
   universalAgentHandle = dp_AllocateHandle(&API_Status);  
   if (API_Status == KUMP_API_OK)
   {
      // Allocate DP buffer. Assumes 80 bytes maximum data

      dp_AllocateBuffer(universalAgentHandle, &WorkBuffer, 80, &API_Status);
      if (API_Status == KUMP_API_OK)
      {
	 // Signal Data Provider that Data Input is ready.
	 dp_BeginInput(universalAgentHandle,ApplicationName,AttrGroupName,&API_Status);

	 if (API_Status == KUMP_API_OK)
	    // Initialization complete. Begin data input.
	    continue;
	 else ;
      }
      else ;
   }
   else ;   
   dp_ShowMessage(API_Status, NULL, 0);
   return(API_Status);
}while (0);

The following code was added to their main application thread, to send data to the Universal Agent:

 dp_ClearBuffer(WorkBuffer, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Register_ID, sizeof(int),
	TypeIsNumeric, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Max_Trans, sizeof(int),
	TypeIsNumeric, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Min_Trans, sizeof(int),
	TypeIsNumeric, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Ave_Trans, sizeof(int),
	TypeIsNumeric, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Total_Trans, sizeof(int),
	TypeIsNumeric, &API_Status);
 dp_FormatBufferData(WorkBuffer, &Ts.Total_Count, sizeof(int),
	TypeIsNumeric, &API_Status);

 dp_InputData(WorkBuffer,&API_Status);

 if (API_Status == KUMP_API_OK)
    cout << "Finished sending data to API Data Provider.\n";
 }
 else {
    dp_ShowMessage(API_Status,NULL,0);
 }

The following code was added to their application termination section, to disconnect from the Universal Agent:

 dp_EndInput(universalAgentHandle,&API_Status);
 dp_FreeBuffer(WorkBuffer, &API_Status);
 dp_FreeHandle(universalAgentHandle, &API_Status);

Refer to the "Chapter 1 - API Introduction" and "Chapter 2 - API Descriptions" of the IBM Tivoli Monitoring 6.1 API and Command Programming Reference Guide (Guide link) for more information on the Universal Agent API.

The compilation process for the application must also be updated. The following files must be included in your compilation:

  • KUMPAPI.h (include file from C:\IBM\ITM\TMAITM6\ or /opt/IBM/ITM/li6243/um/bin)
  • KUMPAPI.lib (Windows only: library file from C:\IBM\ITM\TMAITM6\)
  • libkumpapi.so (UNIX® only: library file from /opt/IBM/ITM/tmaitm6/li6243/lib)

Example (Linux): g++ -lkumpapi SortArray_API.cpp.

For Windows, C:\IBM\ITM\TMAITM6\KUMPAPI.DLL must be on your application's runtime path.

If the application is compiled on a machine without the Universal Agent, the aforementioned files must be copied from a Universal Agent to the compiling machine.

Creating the metafile

The metafile is a straightforward conversion of the summary statistic struct.

 struct TransactionStatus{ 

    int Register_ID;
    int Min_Trans;
    int Max_Trans;
    int Ave_Trans;
    int Total_Trans;
    int Total_Count;
    int Input;
 };
Metafile derived from the struct: SortArray_API.mdl
//APPL Inventory
//NAME Transactions E 1200
//ATTRIBUTES ';'
Register_ID D 32
Max_Trans_Amount D 32
Min_Trans_Amount D 32
Ave_Trans_Amount D 32
Total_Trans_Amount D 32
Total_Trans_Count D 32

Note: "1200" is the time-to-live (TTL) value. It's the time in seconds your monitored data is cached by the Universal Agent. The default TTL is 300 seconds. Make sure your application sends monitoring data to the Universal Agent at least as often as the TTL.

Refer to Chapter 3 - Creating an Application and Appendix A: Data Definition Control Statements of the IBM Tivoli Monitoring 6.1 Universal Agent User's Guide for more information about metafiles.

Advanced: Running your application on a different machine than the Universal Agent

In this configuration, you must create the system environment variable KUMP_API_DPAPI_HOST on the application machine to reference the Universal Agent machine.

Windows:

  1. Go to Control Pannel/System/Advanced/Environment Variables.
  2. Select New under System variables.
  3. Type KUMP_API_DPAPI_HOST for Variable name.
  4. Type host name of Universal Agent API Data Provider (For example: Tivoli5.)
  5. Select OK several times to save the variable and exit "System Properties".

Linux/Unix:

  1. Add the line export KUMP_API_DPAPI_HOST=hostname of Universal Agent API Data Provider to your profile
  2. For example: echo export KUMP_API_DPAPI_HOST=Tivoli5 >> /root/.profile

Configuring the Universal Agent to monitor the C++ application

  1. Verify that the Universal Agent API Data Provider is active by checking for the line KUMA_STARTUP_DP=ASFS in the C:\IBM\ITM\TMAITM6\KUMENV file for Windows or /opt/IBM/ITM/config/um.ini file for Linux or UNIX. The API data provider is started by default when the Universal Agent is installed.
  2. Copy the metafile of your application to the metafiles subdirectory of the Universal Agent (C:\IBM\ITM\TMAITM6\metafiles or /opt/IBM/ITM/li6243/um/metafiles)
  3. Verify the syntax of your metafile, and import it into the Universal Agent.
  4. Windows verify and import:
    1. At a DOS prompt, change directory to C:\IBM\ITM\TMAITM6.
    2. Type kumpcon validate metafile_name. For example: kumpcon validate SortArray_API.mdl.
    3. If the metafile validates, type Import and press Enter. The message indicating that the import finished successfully will appear. Otherwise, fix the metafile and repeat the previous command.
    4. The imported metafile will be added to the KUMPCNFG config file in the folder C:\IBM\ITM\tmaitm6\work
  5. Linux verify and import
    1. From a shell prompt, change directory to /opt/IBM/ITM/li6243/um/bin.
    2. If the metafile validates, type ./kumpcon validate metafile_name. For example: ./kumpcon validate /opt/IBM/ITM/li6243/um/metafiles/SortArray_API.mdl.
    3. Type Import and then press Enter. The message indicating that the import finished successfully will appear. Otherwise, fix the metafile and repeat the previous command.

The imported metafile will be added to the KUMPCNFG config file in the folder /opt/IBM/ITM/li6243/um/work.

Now you are ready to run your application. When your application starts, a new entry will be available in the Tivoli Enterprise Portal. Click Navigator Update Pending button and your application data will be visible under platform --
Systems -> hostname -> Universal Agent -> hostname:INVENTORY00, where platform is Windows or Linux, and hostname is the hostname of the system with the Universal Agent.


Log monitoring

This section describes monitoring a PHP application via its log file with the Universal Agent File data provider.

Description of PHP application

Company C has created a PHP-based content management application to display their in-store catalog from a kiosk. Company C plans to monitor this in-store application remotely. This application has done a good job of logging all the warnings and errors in a log file.

Instrumentation of the application for monitoring with the Universal Agent API

Company C will configure the Universal Agent to monitor this application by parsing the log file and looking for error messages. The Universal Agent can easily implement this using the File data provider.

First, let's look at the log file. The log file uses a fixed column format, with a message severity, timestamp, category, and message.

Log file snippet
 Message  2007-01-30-06.29.06    UserLogin          D8765 logged in
 Message  2007-01-30-06.29.16    ProductAccess      D8765 accessed product sku 1987
 Message  2007-01-30-06.29.36    UserLogout         D8765 logged out
 Error    2007-01-30-06.29.45    DBError            Connect failed 
 						   [/var/www/bijlani/lib/sql.php:108]
 Error    2007-01-30-06.29.46    UserLogin          User Login Failed

No code is required to monitor a log file. Only a Universal Agent metafile is configured.

Creating the metafile

The metafile must specify the log file format and location for the File data provider.

Metafile for the log file: ContentMgmt.mdl
//APPL CONTENT-MGMT-PHP-APP 
//NAME APPLOG E 
//SOURCE FILE 'c:\bijlani\content-mgmt\log\app.log' tail 
//ATTRIBUTES ' ' 
LogEntryType D 16 
Date D 20 
LogEntryDesc D 16 
LogEntryMsg Z 88

A metafile for monitoring files must specify some metadata about the monitored application and the format of the monitored data.

The first metadata is an "application" name specified with APPL. The APPL statement must

  1. Be the first line in the metafile
  2. Be used only once in the metafile
  3. Have a value that does not start with K
  4. Have a value unique across all metafiles

The next metadata is the name of the attribute group (attributes which are being extracted from the log file) and the data collection method, specified with the NAME statement. The name must be unique within the metafile. Company C's metafile uses the Event (E) data collection method, so data is collected in an asynchronous fashion.

Next is the SOURCE statement which specifies using the File data provider, as well as the file location reading method. Company C's metafile uses "tail" mode, which scans new lines at the end of the monitored file.

The final metadata is the data delimiter, specified in the ATTRIBUTES statement.

After the metadata is specified, the log file format must be described. Since the log file uses mostly fixed-width string fields, the description is straightforward. Each field must be given a name and type. The fixed-width string fields are specified with Display String (D) and a field size.

The log message itself is an unknown size, but always less than 88 bytes. The attribute type Last (Z) is used, to tell the Universal Agent to ignore delimiters for this field and to read until the end of the line. This is important because Company C's delimiter is a space, and it is nearly certain that the message itself will contain spaces.

Refer to "Chapter 3 - Creating an Application" and "Appendix A: Data Definition Control Statements" of the IBM Tivoli Monitoring 6.1 Universal Agent User's Guide for more information about metafiles.

Configuring the Universal Agent to monitor the PHP application log file
To start monitoring the log file, we only need to configure the Universal Agent to load our metafile.

  1. Verify that the Universal Agent API Data Provider is active by checking for the line KUMA_STARTUP_DP=ASFS in the C:\IBM\ITM\tmaitm6\KUMENV file for Windows or the /opt/IBM/ITM/config/um.ini file for Linux or UNIX. The File data provider is started by default when the Universal Agent is installed.
  2. Copy the metafile of your application to the metafiles subdirectory of the Universal Agent (c:\ibm\itm\tmaitm6\metafiles or /opt/IBM/ITM/li6243/um/metafiles).
  3. Verify the syntax of your metafile, and import it into the Universal Agent
  4. Windows verify and import:
    1. At a DOS prompt, change directory to c:\ibm\itm\tmaitm6.
    2. Type kumpcon validate metafile_name. For example: kumpcon validate ContentMgmt.mdl.
    3. If the metafile validates, type Import and then press Enter. The message indicating that the import finished successfully will appear. Otherwise, fix the metafile and repeat the previous command.
    4. The imported metafile will be added to the KUMPCNFG config file in the folder C:\IBM\ITM\tmaitm6\work
  5. Linux verify and import
    1. From a shell prompt, change directory to /opt/IBM/ITM/li6243/um/bin.
    2. If the metafile validates, type ./kumpcon validate metafile_name. For example: ./kumpcon validate /opt/IBM/ITM/li6243/um/metafiles/ContentMgmt.mdl.
    3. Type Import and then press Enter. The message indicating that the import finished successfully will appear. Otherwise, fix the metafile and repeat the previous command.

The imported metafile will be added to the KUMPCNFG config file in the folder /opt/IBM/ITM/li6243/um/work.

Now you are ready to run your application. When your application starts, a new entry will be available in the Tivoli Enterprise Portal. Click Navigator Update Pending button and your application data will be visible under platform Systems->hostname->Universal Agent->hostname:CONTENT-MGMT-PHP-APP00, where platform is Windows or Linux, and hostname is the hostname of the system with the Universal Agent.


Monitoring the sample applications

After installing the sample applications and configuring the Universal Agent, your Tivoli Enterprise Portal will notify you about pending updates to its display.

When all of the applications are configured, and all updates incorporated into Tivoli Enterprise Portal, you should see six entries under the Universal Agent: Three for the JMX applications (one per application, plus a JMX event log), one each for the C and PHP applications, and one for the Universal Agent itself (ASFSdp:UAGENT00).

Clicking on each entry will give you a workspace for that application which you can customize. The default workspace will contain a table-based report.

Figure: J2EE application report (similar to J2SE application report)
Figure: J2EE application report (similar to J2SE application report)
Figure: JMX event report
Figure: JMX event report
Figure: C application report
Figure: C application report
Figure: PHP application report
Figure: PHP application report
Figure: Universal Agent general report
Figure: Universal Agent general report

More you can do with IBM Tivoli Monitoring

Now that you've got your application integrated to IBM Tivoli Monitoring and that data is now flowing into the presentation server (along with your other agents), there is where you can do some interesting things with the IBM Tivoli Monitoring. Although we won't cover them in this article, some of the things you can do are:

  1. Creating "situation(s)" that look for certain events (across one or more agents) to occur and then launch a process or a series of processes (send logs to a system administrator and page that system administrator when high CPU utilization on two servers occurs)
  2. Producing valuable reports on how your systems are doing (to either see how the current solution compares to the past)


And much more! As you can see, when you have the raw data come from all the components in your IT infrastructure, you can truly know what is going on and react to that information instantaneously.

IBM's Ready for Tivoli validation program

The IBM Ready for Tivoli validation program is a program for Independent Software Vendors (ISVs) to help showcase their integration to IBM Tivoli Monitoring. ISVs are highly encouraged to submit their solution to the Ready for Tivoli validation program. By completing the IBM Ready for Tivoli validation program, ISVs can gain valuable sales and marketing exposure and demonstrate to customers that their solution meets or exceeds IBM compatibility criteria and successfully integrates with IBM Tivoli Monitoring.
Some of the sales and marketing benefits

  1. Entry into IBM's sales solution databases where the IBM sales force helps sell your application.
  2. Entry into the IBM Tivoli Open Process Automation Library where your integration is displayed on the IBM Web site.
  3. IBM "Ready for Tivoli" Logo for your Web site and marketing literature so that your customers know that your software works with Tivoli.

How to validate your solution in the Ready for Tivoli validation program

Ready for Tivoli validation for Tivoli Monitoring 6.1 entails implementing one or more of the following integration options:

  1. Creation of a custom agent for your application as well as applicable custom workspaces, views, policies and actions. Custom agent options include:
    1. Usage of any of the out-of-the-box Universal Agent data providers.
    2. Creation of a custom Universal Agent data provider.
  2. Usage of the Tivoli Monitoring Web Services SOAP interface from your application to query agent data or issue Tivoli Monitoring commands.
  3. Query and usage of historical agent data from the Tivoli Data Warehouse 2.1 database.


This document should help you fulfill the Universal Agent integration requirement.

Additional information on Ready for Tivoli validation

Please visit the Ready for IBM Tivoli software validation site for the process steps, enablement support, and a current copy of this document: Ready for Tivoli.
Also visit the IBM Tivoli Open Process Automation Library where Tivoli validated solution integration extensions are listed: Tivoli Open Process Automation Library.

Conclusion

IBM Tivoli Monitoring provides a way for you to remotely monitor your application. Before adding monitoring capability to your application, you need to decide what and how you want to monitor. There is no right answer for what to monitor. You must find a balance between monitoring so much information that monitoring itself creates a heavy load, and monitoring so little information that you cannot do anything with it.

IBM Tivoli Monitoring supports a wide range of methods for monitoring applications. We have recommended and demonstrated some of the most common integration methods. No matter what kind of application you have built, it can be integrated with IBM Tivoli Monitoring. And remember, to submit your solution to the IBM Ready for Tivoli validation program to gain important IBM sales and marketing benefits.


Download

DescriptionNameSize
Sample codedwSoftwareArticleCode.zip141KB

Resources

Learn

Get products and technologies

Discuss

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 Tivoli (service management) on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Tivoli (service management), Tivoli
ArticleID=229997
ArticleTitle=Step by step how-to on integrating your application with IBM Tivoli Monitoring 6.1
publish-date=06282007