JXInsight 4.0 Install GuideChapter 1 Platform Support JXInsight is relatively easy to install into an existing J2EE application. The integration of the server-side part of the product into a J2EE application server is as easy as installing a JDBC driver into the same environment. Platform Support JXInsight and JVMPI Agent Windows NT 4.0, Windows 2000 Professional, Windows 2000 Advanced Server, Windows XP Solaris and Linux (RedHat, Suse) Mac OSX, AIX and HP-UX JDK 1.4.x, JDK 1.3.x JXInsight Console Windows NT 4.0, Windows 2000 Professional, Windows 2000 Advanced Server, Windows XP Solaris and Linux (RedHat, Suse) Mac OSX, AIX and HP-UX JDK 1.4.x (please use product installed JRE 1.4.2 when provided) JXInsight Terminal Windows NT 4.0, Windows 2000 Professional, Windows 2000 Advanced Server, Windows XP Solaris and Linux (RedHat, Suse) Mac OSX, AIX and HP-UX JDK 1.4.x (please use product installed JRE 1.4.2) Application Servers BEA Weblogic Server 5.x, 6.x, 7.x, 8.x and 9.0 IBM Websphere 3.5, 4.0, 5.x and 6.0 Oracle (OCJ) 9.x/10.x JBoss 2.44, 3.0 and 4.0 Pramati 3.x Borland Entreprise Server BAS 4.x, BES 5.x/6.x Apache Tomcat Resin In general the product should work with most web and component application server products Database Oracle DB2 Sybase Informix SQL Server Borland JDataStore Cloudscape PointBase In general the product should work with most SQL/92 database products supporting the JDBC standard
Page 1 of 47
Java Libraries IMPORTANT JXINSIGHT 4.0 CHANGE NOTE The old library jdbidriver.jar has been renamed and partitioned into multiple jars to support the class loading of particular trace extension into child class loaders which is typical within J2EE application server and web container class loader hierarchies. When deploying a jxinsight-ext-*.jar library the jxinsight-core.jar library must be deployed instead of jxinsight-all.jar. The jxinsight-core.jar must be visible to all trace extensions via the same class loader or a direct/indirect parent class loader. For backward compatibility the jxinsight-all.jar (previously named jdbidriver.jar) is built with all JXInsight and JDBInsight classes and resources. Recommendation: Deploy the jxinsight-core.jar into the application servers library path. Those extensions that are part of the application servers runtime should also be deployed into the servers library path. For technologies such as JDO, Spring, JCR, and Hibernate which are deployed as libraries in a the web-inf/lib directory copy the extension(s) into the same directory or update the web archive with the extension. jxinsight-all.jar All classes from jxinsight-core.jar, jxinsight-ext-*.jar and jxinsight-jdbc-drivers.jar. jxinsight-core.jar JXInsight Tracer and Profiler and JSE trace extensions (JDBC, CORBA, JNDI, RMI, JMX) jxinsight-jdbc-drivers.jar JDBInsight JDBC Drivers and DataSources jxinsight-ext-j2ee.jar J2EE trace extensions (JMS, JCA, EJB, JTS, JTA, Servlets/JSP, JAX-RPC) jxinsight-ext-jcr.jar Java Content Repository (JCR) trace extension jxinsight-ext-vbj.jar Borland VisiBroker (distributed) trace extension jxinsight-ext-kodo.jar SolarMetric Kodo JDO trace extension jxinsight-ext-jboss.jar JBoss EJB (distributed) trace extension jxinsight-ext-ant.jar Apache Ant trace extension jxinsight-ext-junit.jar JUnit trace extension jxinsight-ext-jdo.jar JDO trace extension jxinsight-ext-hibernate.jar Hibernate 3.0 and 2.0 trace extensions jxinsight-ext-ejb3.jar EJB3 trace extension (Note: The EJB3 trace extension is not included in jxinsight-ext-j2ee.jar) jxinsight-ext-commonj.jar commonj WorkManager and TimerManager trace extensions jxinsight-ext-spring.jar Spring Framework AOP based Trace Interceptor jxinsight-ext-hpovobs.jar HP OpenView OBS TraceInterceptor
Page 2 of 47
Chapter 2 - JVMPI Agent JXInsight requires the installation of a native library, jdbinsight.(dll | so | sl), which integrates into the JVMs Profiling Interface (JVMPI). The library needs to be installed on the native library path of the application server JVM process. To install the library on the library path this might require changing the servers start up script, changing the system environment or copying the native agent library into an existing directory on the library path. The native library can be loaded on JVM start-up by specify Xrunjdbinsight on the command line executing the Java process creation call. The Xrun allows various flags to be passed to the agent, which turn on or off various counters. Configurable counters include GC (g), Object Allocations (a), Blocking (b) and Waiting (w). To turn on GC simply specify Xrunjdbinsight:g=t. To turn off the blocking counter Xrunjdbinsight:b=f. By default Blocking and Waiting counters are turned on. Multiple flags can be turn on and off by separating flags with a comma. For example to turn off Waiting and Blocking Xrunjdbinsight:b=f,w=f. Important Note for BEA WebLogic Customers Using JRockit 8.01 The Xnoopt flag should be specified to stop the in-lining of JXInsight JDBC drivers methods by the JRockit VM. Currently the VM does not return the correct call stack when a method has been in-lined via its built-in code optimizer, this results in interceptions points not containing valid JDBC API calls. The latest release of BEA JRockit JVM has resolved this problem (1.4.2_04).
Page 3 of 47
Chapter 3 - JDBInsight JDBC Driver and DataSources JDBInsight is basically a driver that wraps around an existing JDBC driver/datasource, intercepting calls and analyzing the data. The driver will also plug into the VM profiler interface (JVMPI). The level of interaction with the profiler interface is kept to a minimum to ensure that JDBInsight does not incur the same high level of overhead found in Java code profiler products. This means, that no changes are required to an existing J2EE application source code (unless the JDBC connection strings have been hard-coded within source code, which is not recommended practice). Also the byte code of the underlying JDBC driver will not be changed by a class loader for instrumentation purposes. In general, the only small change that needs to be done is in the reconfiguration of connection pools or datasources. The changes required are in the specification of the driver class name and connection URL. The class name value should change to one of the following: a) com.jinspired.jdbinsight.drivers.jdbc1x.Driver b) com.jinspired.jdbinsight.drivers.jdbc1w2.ConnectionPoolDataSource With options (a) and (b) the URL should have jdbinsight: inserted after the initial jdbc: URL specification such as jdbc:jdbinsight:oracle:thin:@xxxx. c) com.jinspired.jdbinsight.drivers.jdbc1x.OracleDriver Option (c) instead should have orainsight inserted such as jdbc:orainsight:oracle:thin:@xxxx. Currently we are using the orainsight: prefix to differentiate between providing a standard compliant interface and an oracle proprietary interface one. If a J2EE application does not rely on Oracle specific JDBC API extensions then use option (a) or (b). IMPORTANT JXINSIGHT NOTE Oracle JDBC API extension clients should not refer to oracle.jdbc.driver.* classes but instead use the interfaces defined in the oracle.jdbc package. The JDBInsight Oracle driver will return connections and statements which implement the Oracle extensions. We recommend upgrading to the latest versions of the Oracle JDBC drivers. IMPORTANT JXINSIGHT NOTE Because options (d) to (p) wrap around an already existing configured and deployed datasources or a particular vendor class there is no need to alter the jdbc URL specification. Please only insert jdbinsight into URLs for JDBC Driver proxies and not JDBC DataSources. d) com.jinspired.jdbinsight.drivers.jdbc2.ConnectionPoolDataSource Options (d) is used to proxy an existing JNDI deployed connection pool datasource. The (e) datasource has a JavaBeans property dataSourceName - setDataSourceName(String jndiname). The installation of this datasource requires the pointing of the Application Server container connection pool to the JDBInsight datasource and pointing the JDBInsight datasource to the driver specific datasource. The JDBInsight datasource will simply delegate calls for pooled connections to the driver specific datasource. Thus both the JDBInsight and driver specific datasource need to be deployed into the JNDI. e) com.jinspired.jdbinsight.drivers.jdbc2.DataSource f) com.jinspired.jdbinsight.drivers.jdbc2.OracleConnectionPoolDataSource Options (f) to (i) provide datasources which have the same JavaBeans property set of the Oracle specific datasources. Thus the only change that should be made to an existing JNDI deployed datasource is in the datasource class name. The property configuration should be exactly the same. Options (f) to (i) should be used when the datasource clients require access to connections and statements which implement interfaces in the oracle.jdbc.* package. g) com.jinspired.jdbinsight.drivers.jdbc2.oracle9i.OracleConnectionPoolDataSource h) com.jinspired.jdbinsight.drivers.jdbc2.oracle9i.OracleDataSource i) com.jinspired.jdbinsight.drivers.jdbc2.oracle10g.OracleXADataSource Only use the oracle9i/oracle10g DataSource class if you are using specific data source properties not found in the standard Oracle DataSource proxy. j) com.jinspired.jdbinsight.drivers.jdbc2.PropertiesConnectionPoolDataSource k) com.jinspired.jdbinsight.drivers.jdbc2.PropertiesXAPoolDataSource Option (j) and (k) should be used for app server products such as Websphere 5.0, which do not make a distinction, in terms of JNDI deployments, between a configured vendor specific connection pool datasource (connection factory) and a connection pool (app server managed). PropertiesConnectionPoolDataSource and PropertiesXADataSource both load the configuration of a vendor connection pool or XA datasource class from a properties file located at a configured URL. Both have the following bean properties (setXXX) that can be configur