Rational Connector tracing and logging

The Rational® Connector provides logging and tracing capabilities for many of its key operations.

By default, logging is enabled and all errors that the connector encounters during its operation is printed to the connector.log file in the Tomcat_directory/logs directory. The only exception is the blueprintLogger, which writes to its own log, blueprint.log, in the same directory.

Tracing provides more non-error information about connector operations for the purposes of debugging. By default, tracing is disabled. It can be enabled by using a JMX console. If the server is properly configured, any JMX console can be used to enable tracing. The instructions are for a jconsole, which is a JMX console provided with a Java™ SDK.

Setting up the server

The Tomcat application server must be configured to accept connections from a JMX console.

  1. Stop the Tomcat application server.
  2. To enable JMX capabilities, add the following lines to the JAVA_OPTS section of the Tomcat catalina.bat file, which typically is found in the Tomcat_install_dir/bin directory.
    Dcom.sun.management.jmxremote
    Dcom.sun.management.jmxremote.port=9004
    Dcom.sun.management.jmxremote.authenticate=false
    Dcom.sun.management.jmxremote.ssl=false

    The first line enables the JMX remote login. The second line specifies the port to listen on for incoming JMX console requests. The next two lines disable authentication and encryption, which might be undesirable in production environments.

  3. Restart the server.

For more advanced JMX configurations, consult the Tomcat documentation athttp://Tomcat.apache.org/tomcat-5.5-doc/monitoring.html#Enabling_JMX_Remote

Starting jconsole to Connect to WebSphere Application Server

No changes to the WebSphere® Application Server JVM properties are necessary to use jconsole to connect. However, you must create a startup script and a properties file. An example startup script is:

@echo off

set WAS_HOME=C:\PROGRA~2\IBM\SDP\runtimes\base_v7
set HOST=localhost:2809

set PROPS_DIR=c:\temp

:: properties

set PROPS=
set PROPS=%PROPS% -Dcom.ibm.CORBA.ConfigURL=file:/%PROPS_DIR%/sas.client.props
set PROPS=%PROPS% -Djava.naming.provider.url=corbaname:iiop:%HOST%

:: classpath

set CLASSPATH=
set CLASSPATH=%CLASSPATH%;%WAS_HOME%\java\lib\tools.jar
set CLASSPATH=%CLASSPATH%;%WAS_HOME%\runtimes\com.ibm.ws.admin.client_7.0.0.jar
set CLASSPATH=%CLASSPATH%;%WAS_HOME%\runtimes\com.ibm.ws.ejb.thinclient_7.0.0.jar
set CLASSPATH=%CLASSPATH%;%WAS_HOME%\runtimes\com.ibm.ws.orb_7.0.0.jar
set CLASSPATH=%CLASSPATH%;%WAS_HOME%\java\lib\jconsole.jar

:: start jconsole using was jdk

start %WAS_HOME%\java\bin\javaw.exe -classpath %CLASSPATH% %PROPS% sun.tools.jconsole.JConsole service:jmx:iiop://%HOST%/jndi/JMXConnector

The example script was written as a Windows .bat script. You need to change the values for WAS_HOME to the 8.3 path for your WebSphere Application Server installation directory, and PROPS_DIR to the directory with the following properties file, named sas.client.props:

com.ibm.CORBA.securityEnabled=true

com.ibm.CORBA.authenticationTarget=BasicAuth
com.ibm.CORBA.authenticationRetryEnabled=true
com.ibm.CORBA.authenticationRetryCount=3
com.ibm.CORBA.validateBasicAuth=true
com.ibm.CORBA.securityServerHost=
com.ibm.CORBA.securityServerPort=
com.ibm.CORBA.loginTimeout=300
com.ibm.CORBA.loginSource=prompt

com.ibm.CORBA.loginUserid=
com.ibm.CORBA.loginPassword=

com.ibm.CORBA.krb5ConfigFile=
com.ibm.CORBA.krb5CcacheFile=

com.ibm.CSI.performStateful=true

com.ibm.CSI.performClientAuthenticationRequired=false
com.ibm.CSI.performClientAuthenticationSupported=true

# all false from here

com.ibm.CSI.performTLClientAuthenticationRequired=false
com.ibm.CSI.performTLClientAuthenticationSupported=false

com.ibm.CSI.performTransportAssocSSLTLSRequired=false
com.ibm.CSI.performTransportAssocSSLTLSSupported=false

com.ibm.CSI.performMessageIntegrityRequired=false
com.ibm.CSI.performMessageIntegritySupported=false

com.ibm.CSI.performMessageConfidentialityRequired=false
com.ibm.CSI.performMessageConfidentialitySupported=false

# not needed
#com.ibm.ssl.alias=DefaultSSLSettings

com.ibm.CORBA.requestTimeout=180

Setting up the client connection

  1. With the server properly configured, start jconsole. The default location is java_home>\bin\jconsole.exe
  2. On the Remote tab, enter the host name or IP of your server and the port number (for example, 9004) and click Connect.
  3. On the MBeans tab, expand the log4j folder. You see a list of all log4j components in use by the application server. Any logger name that begins with com.ibm.rational.connector.sap belongs to the Rational Connector.
  4. The connector uses a naming convention of com.ibm.rational.connector.sap.*Loggerand com.ibm.rational.connector.sap.*Tracerwhere the asterisk* indicates the specific component of the connector that is controlled by the logger or tracer.
  5. Click the tracer that you are interested in. To enable tracing for the selected logger, in the priority field, delete the default INFO text and type TRACE.

    By default, tracers are set to a level of INFO, which is low priority in log4j. A trace level of INFO means that tracing statements within the connectors are not printed to the connectorTrace.log file.

  6. Repeat step 5 for all other tracers that you are interested in. Changes take effect immediately and do no need a server restart.
The following is a complete list of loggers and tracer components, and their capabilities.
  • blueprint - Useful when you push a blueprint from Solution Manager. The blueprint Logger writes to the blueprint.log.
  • certs - Useful when you have problems with certificates.
  • connector - General message handling of the connector. This tracer must be enabled along with other components when you evaluate a problem.
  • cq - Useful for debugging errors between the connector and ClearQuest®.
  • reqPro - Useful for debugging errors between the connector and Rational RequisitePro®.
  • rqm - Useful for debugging errors between the connector and Rational Quality Manager.
  • rrc - Useful for debugging errors between the connector and Rational Requirements Composer.
  • sdAdapter - Useful for debugging errors between service desk and the connector.
  • serviceDesk - Useful for debugging errors between service desk and the connector.
  • testData - Useful for debugging project level operations such as association, disassociation, and reassociation between the connector and solution manager.
  • testresult - Useful for investigating issues with test results that are not showing in solution manager.

Using a combination of several tracers often yields a better result. When you investigate problems, ensure that the connector tracer is enabled. When you investigate issues between Rational ClearQuest and Service Desk, enable the cq, sdAdapter, and serviceDesk tracers. When you do a blueprint push, enable the Rational servers, such as rqm and reqPro, in addition to the blueprint tracer.


Feedback