Page 1 of 60

JXInsight 4.0 User Guide

Chapter 1 - Basics Product Large scale enterprise applications, using J2EE™ application server technology, today demand performance management solutions, that provide insight into the transaction execution behavior of various modules and components. Performance management solutions that provide extreme low overhead data capture and analysis are critical to ensure that IT infrastructure withstands business demands and supports growth. About JXInsight JXInsight provides distributed tracing and profiling across multiple JVM’s potentially running on different hosts. JXInsight comes with highly configurable trace integrations for standard J2EE/J2SE technologies as well popular open source projects. The list of trace extensions includes:

• Servlet/JSP, • EJB • EJB3 (javax.persistence) • JCA CCI • JMS • JTS/JTA • JDBC • JNDI • CORBA • JCR (Java Content Repository) • JDO • Hibernate 2/3 • JBoss Client/Container Interceptors • Spring Interceptors • Ant • JUnit

The JXInsight console can correlate multiple traces as a result of user actions/transactions providing comprehensive JVM statistics (CPU, Clock, Blocking, Waiting, GC and Memory Allocation) as well as relating such traces to JXInsight transaction paths. JXInsight/JDBInsight is an innovative enterprise performance management product, aimed at simplifying the performance tuning and testing of J2EE™ applications, which access data through the Java Database Connectivity (JDBC™) API. JXInsight analyses the access of enterprise data by J2EE™ client-, web-, and bean containers. The analysis can encompass transaction executions, spanning multiple J2EE™ containers. JXInsight captures timing, resource usage, object allocations, thread blocking, thread waiting, and execution pattern information for enterprise data accessed by Servlets, JavaServer Pages, Session- and Entity Beans using JDBC™ or an Entity Bean using a container's persistence engine. JXInsight provides the ability to quickly detect performance bottlenecks within a J2EE™ system, reducing the need to allocate valuable development resources or purchasing further hardware to compensate for poor performance. It aids testing by providing unique information visualizations that show the execution of a J2EE™ application in terms of technology and component classification as well as transaction demarcation. What distinguishes JXInsight from all the other profiling and performance management tools on the market is that JXInsight provides analysis from a sequence perspective whereas other tools simply show a call tree and no attempt is made to indicate what particular execution plan occurred – who called who is available but not what happened after this particular Java method or SQL statement was called. Inefficiencies in J2EE applications occur mainly at the transaction level such as repeating the execution of a particular SQL locally and globally. JXInsight looks for patterns that exhibit inefficiencies when viewed in terms of the sequential execution of a business and/or resource transaction. For example JXInsight can show if an EJBHome.find method called is followed up by multiple single row select statements (EJB.findByPrimaryKey) indicating that the home find did not load the entity bean state in its initial query. Another more common problem found within J2EE that others tools failed to detect is multiple transactions within a business and/or resource transaction.

Page 2 of 60

Basic Concepts Before starting to use JXInsight it is important to understand some fundamental concepts and objects presented in the performance profile and the unique way that JXInsight approaches the performance management of J2EE™ applications. JXInsight is the first performance management product on the market that treats SQL as a first class citizen, alongside the Java language, in the profiling of J2EE applications. JXInsight provides powerful transactional analysis that goes far beyond SQL tuning tools. While JXInsight can determine poor performing SQL statements it has a powerful pattern recognition and classification engine that understands the context for the execution of a sequence of Java/JDBC/SQL operations. JXInsight provides a better understanding of J2EE applications because any profiling information captured is not related to entry points but to the execution across of multiple components. This helps when you have generic components such as servlet controllers or large session facades which contain many different execution paths across various classes and components based on passed parameters. JXInsight collects and aggregates performance measurements at various levels such as Path, Node, Visit, Interception, Call, Method and SQL statement. A Path typically represents the occurrence of a specific resource transaction pattern. A single JDBC transaction will equate to a Path in JXInsight, ignoring aggregation and compression and sub-transactions, during a profiling session. In terms of the model used by JXInsight, a Path is uniquely identified by two properties: start and end both of type Node. A Node represents a particular operation within a sequence of operations. A Node is uniquely identified by two properties, previous of type Node, and context, which in general is of type Interception. The importance of coupling Java and SQL is evident when there is a generic application framework and the only possibility of distinguishing one user transaction from another is in the data parameters passed via the framework hooks. Other profiling solutions would simply group all user transactions into the same call tree whereas JXInsight will group them based on framework hooks and SQL invocations, which are typically derived from passed parameters. An Interception represents an intercepted JDBC API call. A particular Interception is identified by the Call and the context, which can be either an SQL statement or a JDBC URL connection string. A Call represents an invocation of a Java method and its callers thus a Call represents the current frame on a Java call stack. A Call is identified by its caller, of type Call, and the called Method. A Method is effectively a java.lang.reflect.Member (constructors are supported as well). Though JXInsight 1.2 had similar concepts of Path and Node, version 2.0 introduced Visit to further refine the level of information captured at the transaction level. By aggregating performance profiling information at the Visit level, JXInsight can now show totals and counts for a particular Node within a particular Path. Please note that a Node can appear in multiple Paths. Additionally JXInsight now presents a Node as a pairing of call stack and SQL command (in the general case) instead of simply a SQL statement executed.

Diagram: Simplified Profile Model Diagram

Page 3 of 60

The above diagram shows the relationship and key properties of the concepts introduced. Please note that JXInsight builds up a comprehensive JVM runtime model including classes, threads, class loaders, packages, exceptions and much more. To better explain this lets look at the following contrived business transaction specified in terms of EJB technology. Update all orders for a particular customer by adding a discount line item

1. CustomerHome.findByPrimaryKey 2. OrderHome.findByCustomer // find outstanding orders for a customer 3. For Each Order found call OrderLineItemHome.create // create a discount line item

This would most likely result in the following JDBC API calls (assuming no caching of prepared statements and other applicable container managed persistence optimizations).

1. DataSource.getConnection // jdbc:xxxx 2. Connection.prepareStatement // select from customer 3. PreparedStatement.executeQuery 4. ResultSet.next // line 3 5. ResultSet.next // line 3 – persistence engine checking if more rows are returned than should be 6. ResultSet.close // line 3 7. PreparedStatement.close //line 15 8. Connection.prepareStatement // select from order 9. PreparedStatement.executeQuery // line 7 10. ResultSet.next // line 8 11. ResultSet.next // line 8 12. ResultSet.next // line 8 13. ResultSet.next // line 8 : returns false thus order count = 3 14. ResultSet.close // line 8 15. PreparedStatement.close // line 15 16. Connection.prepareStatement // insert into orderitem 17. PreparedStatement.executeUpdate // line 15 18. PreparedStatement.executeUpdate // line 15 19. PreparedStatement.executeUpdate // line 15 20. PreparedStatement.close // line 15 21. Connection.commit // line 1

The following Nodes will be created by JXInsight. The call stack has been omitted to aid comprehension. Row Previous Node.Context.Interception.Call Node.Context.Interception.Context 1 DataSource.getConnection jdbc:xxx 2 1 Connection.prepareStatement select from customer 3 2 PreparedStatement.executeQuery select from customer 4 3 ResultSet.next select from customer 5 4 ResultSet.close select from customer 6 5 PreparedStatement.close select from customer 7 6 Connection.prepareStatement select from order 8 7 PreparedStatement.executeQuery select from order 9 8 ResultSet.next select from order 10 9 ResultSet.close select from order 11 10 PreparedStatement.close select from order 12 11 Connection.prepareStatement insert into orderitem 13 12 PreparedStatement.executeUpdate insert into orderitem 14 13 PreparedStatement.close insert into orderitem 15 14 Connection.commit jdbc:xxx Note that while there are 21 steps in the Java/JDBC listing there are only 15 nodes listed. The reason for this is that JXInsight’s profiling engine performs transaction compression for local and global looping. A local loop is detected when an interception is repeated immediately. Please recall that an interception is a call stack and context (URL or SQL). Global looping is detected when the same interception pattern is repeated immediately. For example the following sequence of interceptions A, B, B, C, A, B, C will be compressed to A, B, C where local looping is performed for steps {2,3} and global looping for steps {(1,2,3),(5,6,7)}. This unique feature reduces the amount of profile data presented thus increases the likelihood of better application comprehensive through the profile trace. To turn off global looping, specify the VM property: -Djxinsight.server.profiler.global.looping=false. IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. JXInsight’s server and console have been specifically designed to ensure maximum comprehension of the transactional execution nature of large complex J2EE applications. JXInsight does not ship with a simple and somewhat primitive PetStore

Page 4 of 60

snapshot instead JInspired performs its product testing against SPECJAppServer2002 the industry standard EJB benchmarking application. This results in real world overhead measurements (low overhead) and scalable usability. The following is table lists the Visits that would be created for the above example with the count. Visit.Node.Context.Interception.Call Node.Context.Interception.Context Count DataSource.getConnection jdbc:xxx 1 Connection.prepareStatement select from customer 1 PreparedStatement.executeQuery select from customer 1 ResultSet.next select from customer 2 ResultSet.close select from customer 1 PreparedStatement.close select from customer 1 Connection.prepareStatement select from order 1 PreparedStatement.executeQuery select from order 1 ResultSet.next select from order 4 ResultSet.close select from order 1 PreparedStatement.close select from order 1 Connection.prepareStatement insert into orderitem 1 PreparedStatement.executeUpdate insert into orderitem 3 PreparedStatement.close insert into orderitem 1 Connection.commit jdbc:xxx 1 The Visits listing is exactly the same as the Node listing because the example relates to a single transaction path. There will be a difference when there are multiple transaction paths, which share common database activity at the start of their execution. The reason for having a Visit object is that statistics at the Node level are an aggregation across multiple transaction Paths as paths can share common Node prefix sequences. Visits are statistics aggregated based on the occurrence of a Node within a particular transaction path. A Visit relates to the visitation (hence its name) of a particular Node during the execution of a transaction Path which is a sequence defined via start and end Nodes. For most users of the console Visits are the objects the focus will be on. To summarise a Node can be associated with many Visits. Each Visit is distinct because of its associated transaction Path. The statistics at the Node level will equal the summation of all associated Visits statistics. JXInsight allows the user to filter out what particular methods are included in the transaction analysis while at the same time recording statistics at the Interception level. To reduce the amount of configuration, JXInsight groups filterable methods and classes into particular levels. By specifying a particular level you exclude all Classes or Methods at a level as well as lower levels. Level Classes or Methods Filtered from Transaction Path 6 java.sql.Statement 5 java.sql.ResultSet 4 java.sql.ResultSet.close 3 java.sql.Statement.close

java.sql.CallableStatement.close java.sql.PreparedStatement.close

2 (default) java.sql.ResultSetMetaData java.sql.DatabaseMetaData java.sql.PreparedStatement.getMetaData java.sql.CallableStatement.getMetaData java.sql.Connection.getMetaData

1 java.sql.Connection.prepareCall java.sql.Connection.createStatement java.sql.Connection.prepareStatement

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. The VM property, -Djxinsight.server.profiler.transaction.filterlevel=3, excludes close method calls on all types of java.sql.Statement’s as well as methods and classes in lower levels. These VM properties exclude the classes from any profiling whatsoever thus reducing the runtime overhead. -Djxinsight.server.jdbc.resultsets.intercept= true | false (default true) -Djxinsight.server.jdbc.statements.intercept=true | false (default true) -Djxinsight.server.jdbc.preparedstatements.intercept=true | false (default true) -Djxinsight.server.jdbc.callablestatements.intercept=true | false (default true) -Djxinsight.server.jdbc.databasemetadata.intercept= true | false (default true)

Page 5 of 60

-Djxinsight.server.jdbc.resultset.next.intercept= true | false (default true) -Djxinsight.server.jdbc.resultsetmetadata.intercept= true | false (default true) Distributed Tracing The new distributed tracing capabilities introduce new profile concepts. A Trace represents an entry in an executed trace stack similar to Call for Java call stacks. A Trace is uniquely identified by a string id and its parent Trace reference (caller). The parent Trace is the value of the active trace on the trace stack when the Trace was started. A Trace object aggregates JVM counters across multiple executions of the trace stack across multiple threads, processes and hosts. A TracePoint represents the execution of a Trace for a particular Java call stack this means a Trace can have multiple executions started from different locations within the Java code base allowing for arbitrary grouping of statistics by users and third party extension providers as well as isolation from any potential code changes. Traces can have meaningful business or operational identifiers and reduce the requirement for performance analysis staff to understand the class names and methods. The call stack is still available for most traces but it has a secondary importance in the displaying of information visualizations. Interceptions described above have been extended to include the current Trace on the trace stack. This means it is now possible to identify particular transaction paths by a sequence of trace identifiers. Such sequences of identifiers can help resolve the caller across multiple JVM’s processes and hosts.

Page 6 of 60

Chapter 2 – Browser Introduction The browser view site allows for the browsing of mounted clusters, servers, and directories with the purpose of loading stored snapshots or retrieving snapshots from an active server. The installation directory is automatically mounted. A mounted directory is basically the inclusion of a file system directory in JXInsight’s console’s browser. It could be viewed a short cut or link.

A mounted server is the configuration of an monitored JVM process instance on the network. The mount configuration includes the address (hostname or IP address) and port number of JXInsight server embedded within the appserver process. By default a JXInsight server will open a socket on 1515 for console requests. If multiple servers are active on the same host the port number is incremented until an available port is found. Mounts are stored in the <install>/console.jdb file. Sample snapshots, placed in the /snapshots directory of the installation, highlight the products performance visualizations across different application architectures and technologies. There are snapshots of JXInsight running with the BEA Weblogic, Solarmetric JDO, and Hibernate. Selecting a snapshot file in the browser tree pane or double clicking on file in the content pane of a selected directory will result in the loading of snapshot and the activation of the analysis views. Selecting a server or cluster for the first time will result in the automatic retrieval of a snapshot across the network. The JXInsight console will not retrieve another snapshot from a cluster or server unless explicitly requested via the Snapshot menu command. A mounted cluster is a user defined collection of servers (multiple hosts, multiple processes) for the purposes aggregating performance execution models automatically. A JXInsight cluster is not equivalent to an application server’s cluster though it can be configured to be the case. When a snapshot is requested at the cluster level a snapshot is requested from each server. Aggregation will be performed by the console of the profile model returned; to analyse an individual server select the child tree node of the server instance within the browser.

Page 7 of 60

Browser Menu • Mount Server Add a server to the browser tree view. • Mount Cluster Add a user defined cluster to the tree view. Servers can then be associated with clusters. • Mount Directory Add an existing file system directory to the browser tree view. • Merge Snapshot Merge multiple snapshots into a single snapshot file.

View Menu • Show Exclusions Includes folders that have been excluded from the view via the Exclude command. • Refresh Refresh the file system browser tree view.

Directory Context Menu

• Copy Path Copy path of the directory or file to the system clipboard. • Delete Delete the directory from the file system. • Exclude Exclude a folder from the view. For root folders the mount command is more appropriate. • Rename Rename the directory in the file system • Include Include a folder that has been previously excluded. • New Directory Create a sub-directory in the selected file system directory. • Unmount Remove a mounted file system folder from the browser tree view.

Snapshot Context Menu

• Copy Path Copy path of the file to the system clipboard. • Delete Delete the file from the file system. • Rename Rename the file in the file system.

Server/Cluster Context Menu • Ping Ping the selected server(s) to determine whether it is still active. • Unmount Unmount the selected server or cluster from the navigator view. • Reset Clear the profiling information in the selected server(s). • Run GC Invoke the GC command, System.gc(), in the selected server process(es). • Snapshot Take a snapshot of the current profiling information. • Monitoring Dynamic stopping and starting of profiling, tracing as well as various JVMPI event collecting

Cluster Context Menu

• Mount Server Add a server to the cluster. A new server instance will be created if the server does not exist already within the browser window. An existing server instance will be moved and placed under the cluster tree node within the tree view.

Page 8 of 60

Server Context Menu • Dump Profile Dumps the current profile model to the servers local file system. • JVM Properties Displays the JVM System properties including those set by the JXInsight mode. • JVM Threads Displays the current thread groups and threads within the server JVM process. • Recording Provides a dialog that automates the reset, snapshot and export actions for use case testing. • Shutdown Calls System.exit(0) in the remote JVM process.

Cluster Context Menu

• Recording Provides a dialog that automates the reset, snapshot and export actions for use case testing.

The above menu commands are accessible via a context popup menu within the browser tree view or the drop down button in the top right corner. The drop down menu will show contextual menu commands plus the view menu commands. When the context menu is activated via the OS specific mouse operation on a particular directory, snapshot, or server, the menu will include the view menu commands and context menu commands and not the browser view commands. Once a server has been created with the Mount Server menu command various operations can be performed such as retrieving a snapshot, running GC within the server, stop and starting the profiling engine and resetting the profile model (snapshot). When the console connects to a server it will automatically retrieve the current profile snapshot. The console will not automatically refresh the initial snapshot. To retrieve a more up-to-date snapshot you must execute the Snapshot menu command.

Dynamic Monitoring Options JXInsight 2.5 allows for the dynamic configuration of an active server via the “Monitoring…” menu command. From within the console a user can activate the monitoring and recording of particular JVMPI events (thread blocking, thread waiting, allocations, GC). Though JXInsight does not have the same high level of overhead of other Java profiling solutions, care should be exercised in turning on allocations monitoring as this can result in significant overhead. By default the JXInsight agent will thread blocking and waiting events recording the time spent threads spend in this state.

Page 9 of 60

The Profiler can also be stopped and started from within the console by checking or un-checking the “Profiling” option. When profiling has been activated the Tracing option can then be checked or un-checked. Turning off profiling from with the console will result in virtually zero overhead. This basically puts the profiler in hibernate mode which can be suitable for production environments during heavy traffic. Note: In our tests JXInsight has the lowest overhead on the market. Even with the most demanding and complex J2EE applications the product has managed to stay under the industry standard 5% ceiling while others performance management server trace tools have recorded 50% overhead. Snapshot Recording A new dialog speeds up the process steps involved in recording transactional behaviour during units tests or use cases. The “Start” button will reset the current profile model within the server process. The “Cancel” button re-enables the “Start” button allowing for another reset. The “Stop” button will take a new snapshot and export it to the file previous chosen during the start phase. During testing the “Start” button is called immediately prior to the invocation of the use case / scenario to ensure that there are no transactions present in the servers profile model. For example during client tests there might be additional steps (transactional work) involved to reach the test entry point such as login that do not need to be recorded within the profile model. The “Stop” button is called as soon as test has completed. Testing this way is very useful in that transaction counts and paths can be recorded for different tests and use cases for offline processing or continuous comparison during code base changes and redeployments. It is important to capture the software execution model (single user, sequential transaction operations) to eliminate obvious performance issues before starting the analysis of the system execution model (concurrency, transactional mixes and workloads). Note: For software execution models transaction counts, path depths, actual SQL statements are important. For system execution models the clock times, timeline tracing and JVM metrics are important.

Page 10 of 60

Java Source Code Console Integration The console now provides the ability to view the source of frames on the call stack of intercepted methods. The first step in integrating the source viewing is to mount the source directory within the console. The source directory mounted should be the parent of the first package directory. Right mouse clicking on the source directory and selecting the Add to Source Path will place all the directory's sub-directories on the search path for Java sources.

Jar and Zip files containing Java sources can also be added to the source path. All immediate directories will be searched. The JXInsight console can browse inside zip or jar files viewing source files or directories. It is possible to add nested directories within a zip or jar file to the consoles source path if the zip/jar file has been packaged with higher parent directories. Remote Runtime System Properties System properties on a remote Java server process running the JXInsight agent and server can be accessed from within the console by right mouse clicking on the server and executing JVM Properties menu action. A dialog is displayed allowing from different viewing options of the properties.

Remote JVM Threads The JXInsight console now provides the ability to query a remote server’s runtime thread groups and threads.

Page 11 of 60

Chapter 3 – Common Views and Menus Introduction The following describes some of the basic view components that are reused across perspectives. Within a perspective multiple views can be displayed at the same time and in general synchronization will occur automatically across views best on user selection. Perspectives and views also have the ability to store user preferences and restore them on activation within a session and across sessions. Table Views All table views within the JXInsight console have the following capabilities:

1. Change the column ordering within the table header 2. Sort on columns containing cells with numeric and string values 3. Numerical cells are shaded slightly where their value is above the average value for the column. 4. Colour encode cells in the selected column based on cell’s value as a percentage of maximum column value 5. Maximum values within a numeric column have a * placed alongside the cell’s value. 6. Show a thumbnail view of the table based on the encoding in item 3 above. 7. Store and load user preferences for column widths and header placement 8. Show a table row bar that can either display the row number of a bar chart of cell values for the selected column 9. Export an image of the table to the file system. The image maybe restricted to the visible part. 10. Copy an image of the tree to the system clipboard. The image maybe restricted to the visible part. 11. Switch the timing values between milliseconds or microseconds. 12. Attach, Open and Delete Cell Notes

Additionally some tables provide ability to show table totals for numeric columns. For columns that are averages, minimums, or maximums the column values are not totalled but averaged. Tree Views All tree views within the JXInsight console have the following capabilities:

1. Expand all tree nodes 2. Collapse all tree nodes 3. Export an image of the tree to the file system. The image maybe restricted to the visible part. 4. Copy an image of the tree to the system clipboard. The image maybe restricted to the visible part.

Text (SQL/XML) Views All text views within the JXInsight console have the following capabilities:

1. Copy text to clipboard 2. Export an image of the table to the file system. The image maybe restricted to the visible part. 3. Copy an image of the table to the system clipboard. The image maybe restricted to the visible part.

Tip #1: Use XML transformation tools to create custom reports from the copied XML listing. Call Stack Graph Views Each box represents a method present on a call stack. The icon in the box represents a classification of the method. Methods with no classification have a default Java class icon. The method name is also displayed along with a percentage value. The percentage is calculated by summing up all measurement totals having the method present on the Java call stack. The cell containing the percentage value is colour coded. Darker colours represent higher percentages. When a box is selected, methods which appear on the same subset of call stacks as the selection are shaded as well as having their font colour and connector lines darkened. A more comprehensive method signature is displayed when the mouse is moved over a box.

The current algorithm used for laying out call boxes is based on clustering high percentage boxes around the center of the y-axis. The call sequence is typically from left to right though it is possible for a method to reference a box to the left of it because of other caller sequences preceding the layout or cyclic calls. All call stack graph views within the JXInsight console have the following capabilities:

1. Filter the call stack graph using a slider that defines the percentage of a metric total that a method must have. 2. Switch the metric that is used in calculating percentages for methods (clock, cpu, blocking, waiting, allocations, gc) 3. Show or hide method names. 4. Export an image of the table to the file system. The image maybe restricted to the visible part. 5. Copy an image of the table to the system clipboard. The image maybe restricted to the visible part.

Tip #1: For large complex graphs turn off the display of methods names to first determine expensive call chain or sub trees. Then select a method within the call chain before turning back on the display of method names. The call graph will ensure that the selection made will stay visible. Tip #2: Use the slider to filter out methods not contributing to high percentage of metric costs.

Page 12 of 60

Source Code Views A Java source code viewer is integrated into the console and changes it display on changes to current selected call frame normally accessible from the Call Stack combo box in most views. To view the source path as above Split the view (view menu action) and in the second pane change the display via the Views menu to Source Code. It is also possible to view the source code in a separate window by clicking on the button adjacent to the combo box. If call line numbers are available the relevant line will be selected and automatically scroll to.

Annotations of Exported Snapshots It is now possible to attach notes to individual attribute values within a snapshot. Currently this functionality is available via the table view menus Attach Note, Open Note and Delete Note. This reduces the need to create separate textual documents noting observations found within snapshots. Now different users can collaborate in the performance engineering exercise by adding notes into the snapshot and exchanging snapshots via email. Notes are stored in a separate file than the snapshot. The notes file is simply the snapshot full filename with a ".notes" extension. This means it is also possible to restrict the viewing of notes by not sending the “.notes file. The notes file is automatically loaded into the snapshot on load within the console. The notes file must be placed in the same directory of the snapshot. Notes are indicated by a red box in the top left hand corner of the cell value. In the future notes will also be visible from within tree views and other visualizations. Nearly all attribute values can be annotated with text.

Page 13 of 60

Chapter 4 – Transaction Perspective Introduction The transaction perspective is available for snapshot files and connected clusters/servers. To switch to a different analysis perspective click on the top right most drop down command button (above the navigation tree views on the right most part of the console). The transaction perspective focuses attention on JDBC transactions (global and local, xa and non-xa). It is one of the most important performance aspects of J2EE applications. Tuning individual SQL statements can be productive initially but it is not always possible to control the type of statements issued to the database because of delegation to a persistence technology such as JDO, CMP or Hibernate. In the transaction perspective attention is given to the sequence of calls made during a transaction. Is the resource transaction consistent with the user transaction semantics? Is the number of statements executed within a transaction excessive and/or redundant? Is the interaction with the database via SQL commands not efficient when viewed at the transaction level? An example would be the retrieval of a collection of EJB’s by Primary Key’s followed by the loading of each EJB instance by a separate select row statement which occurs with BMP EJB find calls and some CMP configurations. The transaction perspective also helps identify potential sub transactions (outer transaction suspended) via call stack analysis. Sub-transactions occur in J2EE applications via EJB transaction attribute settings. For example when an EJB that has transaction attribute value of ‘Required’ calls another bean with transaction attribute ‘RequiresNew’ a separate transaction will be started and associated with the current thread work. In such situations the concurrent connection requirements increase as the outer connection is held outside the connection managers pool while the new transaction (with a new resource connection) is used. Typically increasing the number of transactions per user transaction has a negative impact on the performance and scalability of the solution. Note: There are cases where breaking (chopping) a transaction into smaller units of work can improve performance via improved concurrency and reduced locking within the database.

Entry Points Chart: The view presents a concise graphical visualization of the transaction entry points. Each vertical block represents a branch in the complete Java call stack tree for all path executions. Blocks are sized based on the sum of the active measurement totals for all paths originating at the Java call stack or having the Java call stack as a prefix to the path’s entry point call stack. The view helps determine the originating call stack sites for expensive transaction paths. The view is useful when a J2EE application has many paths with slightly different visit executions but a small number of transaction path entry points. Please note that the complete Java call stack is not presented as the view compresses and

Page 14 of 60

promotes calls on the Java call stack tree when there is a run in the call stack with no branching. The Java call stack tree is truncated to entry points. The measurement used for sizing of blocks can be changed via the views drop down menu. The following measurements are available: wall clock, cpu time, allocation, blocking, waiting, gc, and clock adjusted. Tip #1: This view can help identify clusters of transaction paths which have the same call stack though different visit sequence. The clustering can also help identify call stacks consuming large amounts of a metric, such as wall clock, total. A ToolTip displays statistical values for the active metric as well as the compressed call stack branch run.

Paths Table: The view presents statistical measurements captured at the path level in a tabular format. The measurements relate to the period between the start and end of a paths execution (the jdbc transaction). Path measurements also include non-jdbc work. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The Call Stack Prefix column provides a graphical display of the common call stack prefix between the first and last visit execution. The icons present common classified Java classes. Moving over an icon a tool tip is displayed showing the class name. The ordering of the icons left to right reflects the position on the call stack from bottom to top. Tip #1: The visit wall clock and CPU difference columns can help quickly identify transaction paths that are database bound. Where the difference is small between a path’s total and the sum of its visits, the transaction period of time is mainly a result of interaction with the database. Typical visits measurements relate to database activity (excluding JDBC object creations) while the path can include non-jdbc work. Tip #2: The clock adjusted metric values are not affected by thread monitor blocking, waiting as well as GC work thus providing a clearer picture of the time period that could be impacted by database and transaction tuning. A large GC event within a transaction may make a wall clock max look large though the GC event could be blamed on excessive object creation in another thread and transaction path. Tip #3: Where it is the case that transactions are impacted by large GC periods the object allocation counters can be enabled allowing for analysis of transaction paths in terms of object allocation rather that time intervals. The allocation counters will include JDBC and NON-JDBC object allocations during the transactions execution interval – from the first statement to a commit or rollback. Tip #4: The new distribution related columns (Median, Mode, Inter-quartile, Semi-quartile, Lower-quartile, Upper-quartile, Standard Deviation, and Coefficient of Variance) can help determine whether the average values reported are not affected by outliners. The Average column has a “Sparkline” graphic showing a compressed bar chart for the distribution. There is also a variation of the Box and Wisker Plot graphic showing graphical the values of the distribution related columns. Tip #5: The new SQL analysis related columns (Columns (*), Tables (*)) help quickly identify transaction paths that select a from a large number of tables and columns. There are counts for columns and tables based on access type: Select, Insert, Update, Delete and Query. Tip #6: The new row retrieval counts and total columns help quickly identify transaction paths processing large amounts of data.

Page 15 of 60

Entry Points Tree: The view helps indicate whether a J2EE application might have sub transactions that are a result of an incorrect configuration of the transaction semantics of a user transaction. The tree view contains two types of nodes – entry points and paths. All non-leaf nodes represent transaction path entry points. A transaction path’s entry point is its call stack prefix (see above for description). A method can appear multiple times in the tree but with different call stacks. The complete call stack is not shown in this view as it would reduce the usability of the view though such call stack representations are evident in common profiling tools.

All leaf nodes represent a transaction path that has the parent node as its entry point. The visualization of the path is based on the sequence of SQL statements executed against the database by the transactions path visits. Each icon represents a particular SQL statement. Icons are coloured & graphically encoded to aid recognition of selects, inserts, deletes, updates, rollbacks, and commit command. This powerful visualization helps recognize commonality and differences in transaction paths with a common entry point. Moving over an icon a tool tip is displayed showing the SQL statement.

When an entry point has child nodes, which are entry points, then there is a possibility that during the execution of the outer transaction path that the child entry point was also entered. Tip #1: A method signature can appear multiple times as an entry point. The difference between tree nodes with the same method displayed will be in the call stack of the entry point. Tip #2: Use the icon sequence of leaf nodes within the same parent to detect any differences in terms of database access and relate this to the percentage marked on the left. Tip #3: Use the Entry Points Chart view to navigate to important transaction paths (leaf nodes). When a path is selected in the chart view the tree view will automatically expand the tree nodes the path and adjust the scroll pane to make the node visible.

Page 16 of 60

Entry Points Graph: The view presents a typical profiling call graph view for all JDBC API executions. The call graph only includes the truncated call stack of each path’s entry point and the percentages are based on the path’s metrics and not its visits. The call the graph view represents transaction times.

Tip #1: For large complex graphs turn off the display of methods names to first determine expensive call chain or sub trees. Then select a method within the call chain before turning back on the display of method names. The call graph will ensure that the selection made will stay visible. Tip #2: Use the slider to filter out methods not contributing to high percentage of transaction costs.

Paths Xml: The view lists statistical information relating to all transaction paths in Xml format. When this view is activated the view’s context menu has a copy command which copies all text to the system clipboard. Alternatively it is possible to select text and press ctrl + c. Entry Points Table: The view displays path entry points in tree table component. The view is typical of existing profiling tools but with a difference in that we are not concerned with basic method profiling but transaction profiling. Aggregated totals relate to the costs of transaction paths. Non-leaf nodes represent methods on the call stack of one or more transaction entry points. Leaf nodes represent a transaction path (sequence of visits during a transaction). The difference between this view and the Entry Point Tree view is that this view includes the complete call stack as well as aggregated metrics at the call stack level. The view helps group transaction paths based on common call stack trees. Tip #1: The grouping and aggregation based on common call stack trees can be useful when transactional components have multiple calling interfaces such as a RMI/IIOP, servlet or web service. The call stack helps partition transaction costs across the different remoting protocols as their implementation is in general distinguishable from the call stack. Nodes Table: The view displays transaction nodes in tree table component. Recall a node represents a particular operation within a sequence of transaction operations. A node is uniquely identified by two properties, previous of type Node, and context, which is an intercepted call stack and SQL/URL reference. A node or run of nodes can be shared across multiple transaction paths. Visits support the separation of profile metrics for a particular transaction path. Thus the view provides a finer grain mechanism of looking at similar transactions. Instead of common call stack runs within entry points there is an additional requirement that the SQL operation is also similar as well as the preceding sequence of operations. The metric values displayed are an aggregation of visit costs across multiple paths having a reference to the node.

Page 17 of 60

Tip #1: Expensive transactional database operations can be nested deep in the tree and are not immediately identifiable from outer tree nodes. Use additional views to help quickly navigate to nodes with high metric totals. Tip #2: Sorting the table columns before searching the tree via expansion calls ensures that nodes with high values appear closer to the locus of focus. Nodes (Cum.) Table: The view displays transaction nodes in tree table component. Recall a node represents a particular operation within a sequence of transaction operations. A node is uniquely identified by two properties, previous of type Node, and context, which is an intercepted call stack and SQL/URL reference. A node or run of nodes can be shared across multiple transaction paths. Visits support the separation of profile metrics for a particular transaction path. Thus the view provides a finer grain mechanism of looking at similar transactions. Instead of common call stack runs within entry points there is an additional requirement that the SQL operation is also similar as well as the preceding sequence of operations. The metric values displayed are an aggregation of visit costs across multiple paths having a reference to the particular node as well its ancestor nodes in the transaction path. Tip #1: Compare current node metrics with parent totals to identify relatively large jumps in transaction costs. Tip #2: Expensive transactional database operations can be nested deep in the tree and are not immediately identifiable from outer tree nodes. Use additional views to help quickly navigate to nodes with high metric totals. In general the console views will synchronize their contents and selections when appropriate selections are made in adjacent views. Tip #3: Sorting the table columns before searching the tree via expansion calls ensures that nodes with high values appear closer to the locus of focus.

Schema Xml: The view provides an XML report of access types for tables and columns across all transaction paths. This can be useful during testing and when it is required to check at a high level whether the transaction test cases executed performed similar operations at the database object level. The Xml text export can be used for basic document/string comparisons. Fields or tables not covered in one run but another can be easily determined.

Page 18 of 60

Traces Table: The view provides a navigation of transaction paths via JXInsight traces. The view is helpful in quickly accessing whether traced executions are database bound and the number of transactions execution for particular traces (traces maybe nested as a thread has support for this via its own trace stack). Note: The Traces perspective within the profile mode allows provides a navigation of traces to transaction paths view master and detail (child) table views.

Traces Tree: The view provides a navigation of transaction paths via JXInsight traces. The difference between the view and the Traces Table view is that statistics are not displayed apart from percentages.

Page 19 of 60

Schema Tree: The view provides a way of locating transaction paths based on a database object. The database schema is derived solely from parsing all SQL statements executed within the profile snapshot. Because the schema reflects the real usage of the database for that particular profile run, it can assist tuning efforts when a database consists of many tables used by other legacy systems. Top level nodes typically represent JDBC connection strings – database node. Each database node contains child nodes representing tables. Each table node contains child nodes representing columns. The left most icon indicates the type of access a database object has undergone via SQL statements. A yellow box indicates selection. A green box indicates insertion. A blue box indicates an update. A red box indicates deletion. A purple box indicates the field has been used in a SQL Where clause. Selecting a database, table or node will result in the displaying of transaction paths in list view (bottom view) which refer to the object. Each path listed has a left most icon indicating the type of access the selected database object under went in its particular transaction execution. Tip #1: Use the schema tree view to identify transactions that access a database object in a particular manner (insert, select, update, delete).

Java Tree: The view provides a way of locating transaction paths via Java packages, classes and methods appearing on the call stack of a visit within a particular transaction path. Selecting a package, class or method will result in the displaying of transaction paths in list view (bottom view) which have a reference from a visit call stack. All Java packages, including sub-packages, are shown as root nodes (flatten package structure) in the view to reduce the depth of the tree. Selecting a path in the list view will result in the Paths Table view selection being changed. Tip #1: Use the tree view to identify transactions that have call stacks containing the selected package, class or method. Classifications Tree: The view provides a way of locating transaction paths via classifications applied to Java classes and methods appearing on the call stack of a visit within a transaction path. Classification is a technique used by JXInsight to aid the comprehension of the performance profile model. It hides the underlying Java implementation classes especially as many of the enterprise application programming interfaces are designed to be pluggable (service provider interface). For example the classification, “ejb:find”, allows for the quick location of paths which have a finder called during the transaction. Top level tree nodes represent classifications. Leaf nodes represent paths. Selecting a path will result in the Paths Table view selection being changed along with the Visits Table view.

Page 20 of 60

Visits Table: The view is similar to the Paths Table view. The view presents the statistical measurements captured at the visit level in a tabular format. The measurements relate to the period between the start and end of the visits execution. Recall that a visit is basically an intercepted JDBC API method call coupled with a Java call stack and database/SQL context. The measurements relate only to JDBC work. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The Call Stack Suffix column provides a graphical display of the additional Java calls on the call stack of the paths entry point call stack. The icons present common classified Java calls. Moving over an icon a tool tip is displayed showing the class name and method. Tip #1: Look for visits with high Count/Transaction ratios. In EJB 1.1 CMP engines it was common to see repeated loads of individual records (one at a time) following a multi-row select on the entity’s table retrieving only the PK fields. Tip #2: Use the cell colour encoding for the current selected column to quickly determine high metric values. Tip #3: The Path Clock % and Path CPU % columns displays the percentage of the transactions path total which includes non-JDBC execution time. Tip #4: Check the Paths/Visits view to determine whether the selected transaction path is database bound. It is not efficient spending time analysing visitation execution costs when the contributing factor is elsewhere. Tip #5: Use table totals display for comparison with the selected path’s metric totals. The differences related to non-monitored execution work during the transactions start and commit/rollback calls. Tip #6: Check for JDBC driver inefficiencies under heavy loads (high concurrency) by looking at blocking and waiting metrics. The clock adjusted values subtract waiting, blocking, and GC times providing a better view of the roundtrip costs between the container and the database.

Page 21 of 60

Visits Xml: The view lists statistical information relating to all visits for the selected transaction path in Xml format. The view can be useful for extracting relevant profile information for use with xml transformation tools. When this view is active the View menu has a copy command which copies all text to the system clipboard. Alternatively it is possible to select text and press ctrl + c.

Visits Sequence: The view provides a UML-like visualization of the selected transaction path. The icons at the top represent classes that have been classified by the JXInsight classification engine. Clicking on an icon will result in an expansion so as to display the class name. Clicking again will result in the hiding of the class name. A particular row (line with connectors) represents a visit within the transaction path. The connectors (small boxes) indicate that the particular class had a method(s) on the call stack of the visit’s interception. The block at the end is coloured and sized based on the SQL statement (yellow=select, green=insert, blue=update, red=delete, grey=connection/transaction operation) and the visit’s total for the active measurement. When a class icon is expanded, labels for method names are placed alongside connectors. There can be multiple labels for a particular connector if the class has more than one method within a particular visit call stack. Tool tips are provided for blocks and class icons. Tip #1: Export the image to the file system for inclusion within transaction task analysis or test case documents. Alternatively copy the image to the system clipboard and paste the image into the document directly. Tip #2: Click on the class icons within the header to expand the class name as well as the class’s method signatures appearing in the call stacks of visits. Call Stacks Tree: The view presents a call stack tree for all visits within the selected path. The tree view includes non-classified call stack elements. Call Stacks Graph: The view presents a call graph view for all visits within the selected path. Each box represents a method present on an intercepted call stack of a visit.

Page 22 of 60

SQL Transcript: The view provides a transcript of the executed SQL statements. Basic SQL syntax colour coding is performed for keywords. This view allows the copying of the transaction paths SQL statements into the system clipboard for possible analysis in a database specific SQL tuning tool.

SQL Sequence: The view provides a UML-like sequence diagram. The icons and adjacent text at the top represent tables that have been determined via analysis of the SQL statements executed by the path’s visits. A particular row (line with connectors) represents an executed SQL statement. The connectors (small boxes) indicate that the table was referenced in the SQL statement. The block at the end is coloured and sized based on the SQL statement (yellow=select, green=insert, blue=update, red=delete, grey=connection/transaction operation) and the visit’s total for the active measurement.

Visits Timings: The view displays in graphical form the visitation for all transaction paths in the profile model. This is a complete overview of the profile model. It is a useful view for quickly understanding the database access nature of a J2EE application and identifying transaction bottlenecks. Blocks are sized based on the totals for the active measurement (clock, cpu, gc, blocking, waiting, and clock adjusted). A horizontal sequence of blocks represents a particular transaction path. The sequence of blocks reflects the ordering of visits within the transaction path. Each block represents a visit. The colour of a block reflects the type of operation: yellow=select, green=insert, blue=update, red=delete, grey=connection/transaction operation. Tool tips are available for each block showing the SQL statement. When a block is selected all other blocks, across all paths, with the same SQL statement will have a small visual clue placed in the center of them. Tip #1: Expand the view horizontally (to the right) to see finer grain parts of transaction paths. Paths/Visits: The view shows the difference between the transaction path’s totals and visits totals. The top box is the path’s total and the bottom is the total of visit totals. The view can be used to quickly determine whether a transaction paths costs are dependant on jdbc-database calls (visits). Blocks are sized based the totals for the active measurement.

Page 23 of 60

Chapter 5 – Resource Perspective and Views Introduction The resource perspective helps track down JDBC resource leakages. A leakage in the JXInsight is the un-referencing of a JDBC resource object such as a connection, statement or result set that is not closed explicitly via a close() call. Though the JDBC specification has specified that child resources will be closed when a parent (factory) resource has been closed it is generally recommended the explicit closure be performed to ensure consistent behaviour across JDBC drivers and JVM’s (some rely on GC collection). The JXInsight profiler keeps track of JDBC resource objects by associating counters with particular interceptions (call stack and SQL/URL context). There are 3 types of counters maintained: Creation, Closure and Unreferenced. When a resource object is created and intercepted the profiler increments the creation counter. When a resource object is explicitly closed the interception point where the creation counter was incremented has its closure counter incremented. When a resource object is unreferenced within the JVM the unreferenced counter is incremented for the interception point that created the resource object. Thus JXInsight is unique in its tracking of object life cycle events in terms of the creation interception point. An interception point that creates and returns a new resource object is referred to as a allocation site. JXInsight does not currently distinguish explicit and implicit closure. In the next release of JXInsight this distinction will be made as well as the ability to track particular instances and associate instances with parent factories instances. Though explicit closure is highly recommended in all environments and will ensure portability of performance and scalability across drivers and connection management pools.

Bar Chart: The view is a bar chart that represents the count of JDBC resource objects created, closed and freed per resource type. The resources displayed are:

• java.sql.Statement • java.sql.PreparedStatement • java.sql.CallableStatement • java.sql.ResultSet • java.sql.Connection • javax.sql.PooledConnection

Page 24 of 60

Bars representing particular object states per resource type are layered. Green indicates the amount of objects created. Blue indicates the amount of objects closed. Green indicates the amount of objects freed (unreferenced). Green and Blue bars are layered over Grey bars.

Sites Table: The site table lists all interceptions (call stacks + SQL) returning a JDBC resource type. JXInsight keeps track of counters representing objects states for each interception point. When a JDBC resource changes state the site where it was created has its counters updated. This helps to pinpoint source code locations where resource objects are created and not closed properly or freed from memory. Because an interception is a combination of call stack and SQL the view caters for generic J2EE application frameworks, which create objects based on application parameters and callers. The Call Stack column in the table shows a concise representation of the classified Java classes on the call stack for the interception. The context column shows the tables listed in the SQL or the JDBC connection string for connect and disconnect events. The Created column lists the counters for resources created. The Closed column lists the counters for resources closed. The Unref column lists the counters for resources unreferenced. The active count is simply the Created column minus the maximum of Closed of Unref. Note that a resource can be unreferenced and not closed implicitly. JXInsight counts closures based on explicit close() calls. It does not count close() calls coming from a close() on a parent resource. For example when a Statement object is closed the ResultSet’s objects created by the statement are closed per the JDBC specification. This is an implicit close. JXInsight counts explicit closures whereas most profilers count closures irrespective. It is recommended practice to close resources explicitly and immediately following usage. Sites Xml: The view lists statistical information relating to interceptions, returning a JDBC resource type, in Xml format. The view can be useful for extracting relevant profile information for use with xml transformation tools. When this view is active the View menu has a copy command which copies all text to the system clipboard. Alternatively it is possible to select text and press ctrl + c. Call Stack Graph: The view displays the call stack for the selected interception in the site table. Call Stack Xml: The view displays the call stack for the selected interception in the site table in Xml format.

Sites Map: The site map visualizes interceptions returning newly created JDBC resource objects. Each box represents an object allocation site. The colour of the box indicates the difference between the creation and closure counts.

Page 25 of 60

Green boxes indicate that the number of objects created at the allocation site (Interception) is greater than the number closed or unreferenced. Blue boxes indicate that the all resources have been closed but not unreferenced from memory. Grey boxes indicate the all objects created have been closed and created. Red boxes indicate that some resources have been unreferenced but not closed (closed possibly during finalization). The view menu, accessible via the drop down menu button, provides menu options for including or excluding the JDBC resources such as statement, connections, result sets and meta data objects. Tip #1: Exclude all resource classes initially and then add those resource classes that are interesting

Page 26 of 60

Chapter 6 – SQL Perspective and Views Introduction The SQL perspective focuses on the performance of individual SQL statements. It helps identify poor performing SQL statements (and unlike most database tuning tools) the Java code responsible for the direct or indirect execution of the statement.

Additionally the perspective can help determine whether the JDBC driver is performing any CPU/Memory intensive operations while sending and retrieving the results from the database system for a particular SQL statement. Note: JXInsight can profile Java object allocations and as well as CPU usage within the calling JVM.

SQL Table: The SQL table lists all executed statements. A SQL statement can appear on multiple rows but with different operation types. The following operation types are possible:

• Execution The execution of a SQL statement. • Retrieval The navigation of a returned JDBC result set. • Preparation The creation of a JDBC prepared statement. • Closure The closure of a JDBC statement.

Page 27 of 60

Schema Tree: The view provides a way of locating SQL statements based on a database object. The database schema is derived solely from parsing all SQL statements executed within the snapshot. Because the schema reflects the real usage of the database for that particular profile run it can assist tuning efforts when a database consists of many tables used by other legacy systems. Top level nodes typically represent JDBC connection strings – database node. Each database node contains child nodes representing tables. Each table node contains child nodes representing columns. The left most icon indicates the type of access a database object has undergone via SQL statements. A yellow box indicates selection. A green box indicates insertion. A blue box indicates an update. A read box indicates deletion. A purple box indicates the field has been used in a SQL Where clause. Selecting a database, table or node will result in the displaying of transaction paths in list view (bottom view) which refer to the object. Each path listed has a left most icon indicating the type of access the selected database object under went in its particular transaction execution. Java Tree: The view provides a way of locating SQL statements via packages, classes and methods appearing on the call stack of an executed statement. Selecting a package, class or method will result in the displaying of SQL statements in the list view (bottom view), which have a from their execution call stack. All Java packages, including sub-packages, are shown as root nodes (flatten package structure) in the view to reduce the depth of the tree. Selecting a SQL statement in the list view will result in the SQL Table view selection being changed. Tokens Tree: The view provides a way of locating SQL statements via string tokens. A tree path represents the occurrence of multiple tokens consecutively in a SQL statement (ignoring white space). The token tree is similar to the classic computer science trie data structure. Token sequences are terminated when a SQL reserved or keyword is met so as to reduce the possible number of nodes within the tree. Symbols are skipped over during the construction of the tree. Selecting a token, will result in the displaying of SQL statements in the list view (bottom view), which have the sequence of tokens, represented by the tree path, within them. Classifications Tree: The view provides a way of locating SQL statement via classifications applied to Java classes and methods appearing on the call stack of a statement’s execution. Classification is a technique used by JXInsight to aid the comprehensive of the performance profile model. It hides the underlying Java implementation classes especially as many of the enterprise application programming interfaces are designed to be pluggable (service provider interface). For example the classification, “ejb:find”, allows for the quick location of SQL state which have a finder called during the transaction. Top level tree nodes represent classifications. Leaf nodes represent SQL statements. Selecting a SQL statement will result in the SQL Table view selection being changed. Entry Points Tree: The view provides a way of locating SQL statements via transaction entry points. Top level nodes represent transaction entry points and leaf nodes SQL statements. A SQL statement node under an entry point node indicates that the transaction started with the entry point called that SQL statement sometime during its execution. Interceptions Table: The view presents the statistical measurements for all interceptions of the selected SQL, in a tabular format. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. Interceptions Xml: The view lists statistical information for all interceptions of the selected SQL, in Xml format. The view can be useful for extracting relevant profile information for use with xml transformation tools. When this view is activate the View menu has a copy command, which copies all text to the system clipboard. Alternatively it is possible to select text and press ctrl + c. Call Stacks Tree: The view presents a call stack tree for all interceptions of the selected SQL statement and operation type. The tree view included non-classified call stack elements. Call Stacks Graph: The view presents a call graph view for all interceptions of the selected SQL statement and operation type.

Page 28 of 60

Chapter 7 – Calls Perspective and Views Introduction The calls perspective provides a visualization of all intercepted JDBC API method calls occurring in a profiling period. The perspective helps track method calls across different architectural layers inside a single JVM and across multiple databases. The JXInsight console uses the classification engine to Java call stack methods into application execution partitions. Classifications are assigned to particular partitions. The partitions are:

• Traces: JXInsight Traces created via extensions or custom user code • Presentation: Java Servlets, Swing, and JSP • Process: Workflow and business logic technologies such Session Beans, Message Driven Beans, Struts • Persistence: Persistence technologies such as Entity Beans, JDO, and Hibernate, iBatis • Database: Databases, Tables and Columns accessed by SQL statements executed by the JVM or multiple JVM’s when

used in the analysis of a cluster. The JXInsight console will parse all SQL statements and attempt to determine the database objects accessed.

Call Trace Graph: Within each partition a tree view component displays objects associated with intercepted call stacks and context. Partitions ‘Presentation’, ‘Process’ and ‘Persistence’ list classes and methods appearing on the call stack of interceptions. For the ‘Database’ partition the objects (tables and columns) are determined based on analysis of the intercepted context which is either a SQL statement or JDBC URL connection string. For each object (tree node) in a partition there are 4 adjacent cells. Each object within the trace graph aggregates clock totals for associated intercepted calls. The aggregation is further broken down into ‘External Incoming’, ‘Internal Incoming’, ‘Internal Outgoing’ and ‘External Outgoing’. ‘External Incoming’ totals relate to calls that originate (directly or indirectly) from objects (classes or methods) outside the object’s partition. ‘Internal Incoming’ totals relate to calls that originate from within the partition including the object itself. ‘Internal Outgoing’ totals relate to calls originating from the object (direct / indirect) to another object within the object’s partition. ‘External Outgoing’ totals relate to calls originating from the object (direct / indirect) to an object within another partition. For database objects there are only totals “External Incoming” calls. A direct call is a call stack that contains a call from one partitioned object to another without any intervening call stack frames that contained classifications associated with a partition type. An indirect call is a call stack that contains a call from one partitioned object to another with some intermediary call stack frames for non-classified objects.

Page 29 of 60

Simple Example: A, B, and C are classes on a call stack. Classes A and B are listed in the “Presentations’ partition with class C listed in the ‘Process’ partition. The call stack has a call cost of 10 milliseconds. A calls B, B calls C, and C makes a SQL statement that executes a select on table T. The following table lists the totals for an object’s adjacent cells.

External Incoming Internal Incoming Class / Partition Internal Outgoing External Outgoing 10 A / ‘Presentation’ 10 10 B / ‘Presentation’ 10

10 C / ‘Process’ 10 10 T / ‘Database’

Contrived Example: A, B, and C are classes on a call stack. Classes A and B are listed in the “Presentations’ partition with class C listed in the ‘Process’ partition. The call stack has a call cost of 10 milliseconds. A calls B, B calls A, A calls A, A calls C and C makes a SQL statement that executes a select on table T. The following table lists the totals for an object’s adjacent cells. Note that the incoming totals for class A are not updated twice though it received calls from both class B and itself. One a call stack has been added to a cell total during the processing of a single call stack subsequent appearances within the call stack are ignored.

External Incoming Internal Incoming Class / Partition Internal Outgoing External Outgoing 10 10 A / ‘Presentation’ 10 10 10 B / ‘Presentation’ 10

10 C / ‘Process’ 10 10 T / ‘Database’

Note: If C made a call to A the external incoming total would still be 10. Filtering The filtering menu command presents a dialog that restricts the interceptions (call stack + SQL/URL context) used in the generation of the trace graph. A filter is a list of classes, packages, methods or database objects that are required to appear in an interception or via some association (a class belongs to a package). An interception must contain one or more filter objects (logical OR). Filtering not all only reduces the number of trace graph objects but it also the interceptions listed in the detail views below the trace graph. Selection When an object is selected within the trace graph the interceptions view will only list filtered interceptions that contain a direct or indirect reference to the selected object via the call stack or SQL/URL context. Clicking outside of a partition will reset the selection resulting in the complete listing of interceptions within the details views. Mouse Movements To not clutter the trace graph calls (connected lines) from one partition to a non-adjacent partition are not painted until the mouse moves over an object that does have such external outgoing or incoming calls. The painted lines are drawn with dotted line stroke. The view includes the option of displaying Java packages and Code Sources across the various Java related partitions (Presentation, Process, and Persistence). This can help consolidate call statistics into more meaningful application units. Call dependencies can also be determined via this view. Selecting a code source (typically a jar) or Java package, results in the displaying of all interceptions with a direct or indirect association with the code source or package.

Page 30 of 60

The view includes a new partition, Traces, that contains JXInsight traces. Lines are drawn from traces to database objects (tables and columns) based on the active trace stack during the interception of JDBC method calls.

Page 31 of 60

Chapter 8 – Exceptions Perspective and Views Introduction The exceptions perspective focuses on the root cause of thrown exceptions (SQLException and XAException). The JXInsight profiler will create a failure statistic that is keyed on

• Interception (Java call stack + SQL/URL), • Exception (class name + message)

The failure statistics are updated every time an intercepted method call throws an exception. The statistics reflect the execution statistics of executions that have thrown exceptions. This is useful when a comparison is required for timing information related to successful and failed transactions or query executions. J2EE applications can routinely throw SQLException for high loaded database systems coupled with optimistic locking/concurrency configuration. The perspective consists of 4 UI component parts. The top part displays the list of failure statistics in tabular, XML and call graph form. The second component from the top displays the exception message for the selected failure statistic. The third component displays the SQL statement or JDBC URL connection string. The fourth and bottom component displays the call stack in list form. Each of the UI components can be resized.

Page 32 of 60

Chapter 9 – Configurations Introduction The configuration perspective within the profile mode provides a relatively easy means of associating change and configuration with specific exported execution profiles of a monitored application. The configuration perspective presents a view of the various monitored configurations for the application. The files that are loaded into the profile model are loaded when a new class loader is identified by the profiler via call stack analysis or the thread context class loader of an intercepted JDBC method call or a JXInsight Tracer call. The perspective is particularly useful when viewing exported snapshots and the necessary configuration files have since changed or not accessible to the console user from his development environment.

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. Server System Properties jxinsight.server.profiler.classloader.resources.include=[true|false] default=true jxinsight.server.profiler.threadcontextclassloader.include=[true|false] default=true jxinsight.server.profiler.classloader.resources.names=META-INF/ejb-jar.xml,META-INF/application.xml,WEB-INF/web.xml Resource names, separated by a comma, are loaded via a call to the ClassLoader method getResources(“xxxx”) . To capture jar manifests specify the system property as: -Djxinsight.server.profiler.classloader.resources.names=META-INF/MANIFEST.MF,META-INF/ejb-jar.xml,META-INF/application.xml,WEB-INF/web.xml

Page 33 of 60

Chapter 10 – Properties Introduction The properties perspective within the profile mode provides a snapshot of the JVM system properties at the time of the snapshot creation. The system properties can be displayed in a Table, Tree and Text format.

The system properties can be displayed in a Tree view with nodes representing elements of the system property delimited by ‘.’.

The Text view provides a textual view of the system properties sorted on property name.

Page 34 of 60

Chapter 11 – Classes Introduction The classes perspective focuses on the runtime dependencies of Java classes based on class meta information derived via the reflection API during call stack recording of intercepted JDBC calls and JXInsight traces. A major advantage of JXInsight approach over Java IDE’s offering similar navigation views is that in large part the visualizations presented derive their information from the runtime behaviour (call stacks and transaction paths) – runtime behaviour within a particular window of execution. Every time the profile is reset the classes, interfaces, packages, and methods are cleared. Thus when a new snapshot is taken and analysed the user is provided with required runtime classes for that period in terms of transactions and traces. The perspective is divided into 3 parts. On the left side is the navigation tree which includes all packages, classes, interfaces, and methods present in the model. The right the view is divided into 2 parts. Each part represents a view site (a set of views) containing the same set of views as the other. The view site is duplicated to allow for viewing a package, class, or method from different aspects. In the screenshot below the top view site is displaying the “Incoming Call Stack Tree” view. The bottom view is displaying the “Outgoing Call Stack Tree” view.

Incoming Call Stack Tree View: The view displays the incoming call stacks for a set of methods. The root nodes represent the set of methods derived from the selection in the “Classes Tree” navigation view. Outgoing Call Stack Tree View: The view displays the outgoing call stacks for a set of methods. The root nodes represent the set of methods derived from the selection in the “Classes Tree” navigation view. The derived “root” methods for both views are calculated differently for each type of node selected in the navigation view.

• Package: The set includes all methods for classes found in the package and sub packages. • Class: The set includes all methods for this class and its direct and indirect sub classes. • Interface: The set includes all methods for direct and indirect implementations of the interface. • Method: The set of methods consists of the actual selected method and all overriding methods.

The toolbar present in each call stack tree view allows for filtering of the non-root methods listed on the call stack tree based the classification(s) associated with the methods declaring class. The classifications displayed in the toolbar are dynamically defined from analysis of the model present classifications.

Page 35 of 60

Inheritance Tree View: The view displays the class and interface hierarchy for a set of classes and interfaces. An initial set of classes is determined based on the selection within the “Classes Tree” navigation view. For a package the set of classes includes all classes defined in the package and its sub packages. For a class the set contains a single element: the selected class. For a method the set contains the methods declaring class. Then for each class in the initial set it super classes, sub classes, interfaces and sub interfaces are added into the set. Note: The additions are not processed in the same manner reducing the growth of the set to some degree.

Page 36 of 60

Chapter 12 – Timelines Introduction JXInsight offers the ability to capture detailed profile data of the transactional execution behaviour of a J2EE/Java/JDBC application. The timeline service can be enabled with the following system property IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. -Djxinsight.server.profiler.timeline.enabled=true The timeline service is enabled by default for both [dev] and [test] server modes. To start analysing a server on start-up specify the following system property -Djxinsight.server.profiler.trace.autostart=true. Alternatively the analysis can be turned on and off dynamically from within the console via the server monitoring action. By default the server development operation mode automatically starts the timeline service. Note: The default server operation mode is [test]. The benefits in timeline analysis are

• Transaction/SQL Concurrency: With timeline information a performance engineer can detect whether performance slow downs occur under a certain level of heavy concurrency for particular transactions patterns or SQL statements. It is also possible to correlate high maximums for both transactions and SQL statement with other events or processing occurring within the servers JVM such as garbage collection, waiting and blocking.

• Database Bound Transactions: Timeline recording provides a visual clue of the Java code execution periods within

a transaction that do not contain database activity. This helps a performance engineer understand whether a transaction is database bound or has other computational work being performed within the transaction period. With the timeline graphs engineers can determine what parts within the transaction period result in slow downs (long periods of non-JDBC activity) without the performance impact typically associated with Java code profilers.

• Sub Transaction Analysis: The transaction timeline graph helps identity resource transactions nested (in terms of

timeline execution) within another resource transaction execution period. Nested transactions create additionally server resource requirements because of the need to utilize extra connections during the suspension of outer transactions. This suspension also results in the low utilization of connections resources. For EJB applications it can result in extra entity bean instances being instantiated, loaded and stored that have previously being accessed in an outer transaction or adjacent child sub transactions.

• Debugging: The tracing data includes system generated object id’s for JDBC resource instances allowing for

debugging of transaction executions at the instance level. This data can help determine what particular instances are being invoked on and whether object instances are closed explicitly within the transaction they were created in. The tracing data records creation points for instances (the result column) as well as close method calls (the target column). Additionally exceptions are associated with instances instead of methods or call stacks provided by other tools.

Page 37 of 60

Model Concepts

The timeline model is made up of the following entities:

• Host: The host of the process. Properties include hostname and IP address • Process: The JVM server process. Properties include OS process id. • Thread Group: A JVM thread group. Properties include name and parent (process | thread group). • Thread: A JVM Java thread. Properties include the object id, thread class, as well as thread group. • Transaction: A resource transaction. Properties include system generate id, initiating thread, timestamp,

wall-clock time, blocking, waiting, allocation, and GC metrics. A transaction consists of 1 or more invocations. A transaction can have a single direct parent and multiple ancestors (deep nesting of sub transactions).

• Invocation: A JDBC intercepted method call. Properties include calling thread, Java call stack, SQL/Database context, as well as the standard metrics such as wall clock, CPU, blocking, waiting, allocation and GC.

• SQL: The SQL statement executed. Properties include the database and SQL string. • Database: The database URL used as a connection string or data source identifier. • Call Stack: The Java call stack for an intercepted method call. Properties include method and line number. A.

call stack is effectively a hierarchy of call entities with each entity containing a reference to its caller as well as the frame method and source code line number.

• Object: A particular object instance identified by the profilers built in sequence generator. Properties include process, id, hash code, and class the object is an instance of.

• Exception: An exception instance thrown by an intercepted JDBC method call. Properties include exception class and message string.

• Code Source: The code source for a class or method appearing on the call stack. • Trace: A JXInsight trace via either a built-in extension (EJB, CORBA, JMS, JDBC, Servlets) or user call.

Console & Views The timeline analysis can be started from the command line or from within the console by selecting a server in the browser tree pane and activating the context sensitive menu and clicking on “Monitoring…”. The following dialog will be presented.

Page 38 of 60

Checking the Timeline (previously referred to as Tracing) option and then clicking on the finish button will result in the dynamic activation of tracing on the server. All further JDBC work performed by the server will be traced.

To take a snapshot and analyse the current timeline model select the profiles Mode menu and select Trace. Switching back to profile mode from within the timeline view is the same procedure.

Note: Use the servers or clusters Snapshot menu command to retrieve the latest model. JXInsight does not stream the model data continuously and instead allows the user to decide when the analysis model should be refreshed. The Reset command clears both the profile and timeline models.

Page 39 of 60

Timeline Graph: The timeline graph view is made up of the following UI component:

• Transaction Overview • Transaction Concurrency Bar Chart • SQL Concurrency Bar Chart • Thread/Transaction Timeline

Transaction Overview Component

The transaction overview component provides a complete visualization of the transactions executed during the period under tracing. The component divides the visual display vertically by thread and within each division (not delineated explicitly) horizontally by transaction. The component adjusts the lengths of transaction bars based on the pixel to time unit ratio which is calculated by dividing the timeline range (latest time - earliest time) by the component screen real estate width size in pixels. Transactions are colour encoded based on transactions clock value as a percentage of maximum transaction clock value. The purpose of the transaction overview component is to provide a bird’s eye view of the transaction timeline and allow easier navigation through a possible large time space. Mouse operations, such a click and drag, performed on the transaction overview component result in view adjustments in other components that support scrolling when contained in a limited viewing space. Tip #1: Use the transaction overview component to quickly identify long running transactions in a large time space. Click on a transaction bar to synchronize all other views. Tip #2: The transaction overview component can also provide a quick analysis to the concurrency levels of the system. Transaction Concurrency Bar Chart Component

The transaction concurrency bar chart component provides a scrolling view of the transaction concurrency levels across threads for a particular database URL. When used with user defined clusters the levels span hosts and processes. For each database identified in the snapshot there is a bar chart row created where the height and colour of the vertical bars represent the level of concurrent transaction activity. The colour is determined by comparing the transaction concurrency level for a particular time interval with the maximum concurrency level recorded for all intervals. A tool tip displays the concurrency value.

Page 40 of 60

Transaction concurrency levels are determined by comparing the degree of timeline overlap between the start and end of all transactions for a particular database URL. Note: This includes time not spent at the database executing SQL statements.

Tip #1: The transaction concurrency level provides a good indicator for a suitable connection pool size unless the purpose of limiting the pool size is to throttle the load placed on the database or additional components further down in the execution path. Tip #2: The transaction concurrency level should be viewed alongside particular SQL statement executions to help in determining whether the poor performance of a SQL statement is related to additionally activity being performed during its execution or possible shared resource locks acquired by active transactions. SQL Concurrency Bar Chart Component

The SQL concurrency bar chart component provides a scrolling view of the SQL statement execution concurrency levels across threads for a particular database URL. When used with user defined clusters the levels span hosts and processes. For each database identified in the snapshot there is a bar chart row created where the height and colour of the vertical bars represent the level of concurrent SQL statement execution activity. The colour is determined by comparing the SQL statement execution concurrency level for a particular time interval with the maximum concurrency level recorded for all SQL executions. SQL statement execution concurrency levels are determined by comparing the degree of timeline overlap between the start and end of all SQL statement executions for a particular database URL. Note: The concurrency analysis is more fine grain than the transaction concurrency because the period of interest relates to the time spent executing a single statement and not the complete duration of the resource transaction. Tip #1: The SQL statement execution concurrency level should be viewed alongside particular SQL statement executions to help in determining whether the poor performance of a SQL statement is related to additionally activity being performed during its execution.

Thread/Transaction Timeline Component

The timeline component provides a scrolling view of the transaction and SQL statement execution across hosts and processes. Each row in the timeline component represents a thread that has had recorded transactions and invocations associated with it. Intercepted invocations are presented as boxes on the timeline. The size of the box represents the duration of the call. The colour of the box is based on the type of SQL / DML operation performed.

Grey lines with slight vertical edge lines drawn above or below invocations but within the same thread row represent transactions. In the above graph we can see an outer transaction spanning four sub transactions. Transaction lines drawn below an invocation bar but within the thread row represent sub transactions. This representation also helps in determining whether a particular transaction is database bound or not. Empty cells during the transaction duration represent non-JDBC work. Currently the view does indicate the level of nesting of sub transactions a more suitable view would be the transaction tree table which can be activated in the bottom segment of the view. For transactions that are truncated because they occurred prior to timeline analysis recording session or have not ended prior to the snapshot the transaction line is drawn out to the respective edge.

Page 41 of 60

Grid cells shaded slightly indicate that non-visible invocations have occurred during this time slice period but are not substantial in duration to be shown. Tool tips are displayed for both transactions and invocations when the mouse is moved over their visual representation. Invocation bars can be selected by mouse clicking resulting in the synchronization of other views such as the invocations and transactions table views.

Zooming in and out of the timeline is supported via the slider component. Changes in the slider equate to changes in the granularity of the grid cell unit size (pixel to time ratio). Tip #1: Zoom out to quickly determine the type of SQL statements executing during timeline taking above average times by viewing bar lengths and colour encoding. Zoom in when clusters of expensive operations have been defined.

The UI components of the timeline view can be hidden via the view’s Options menu. New in 3.2 - Traces and Remote Correlation

Traces are layered on the timeline underneath the transactions and JDBC invocations. This is extremely useful in visually accessing how much time is spent in serving a user request spanning multiple process and technology stacks.

Page 42 of 60

JXInsight can visually correlate distributed traces. The image below shows a selected client trace and the corresponding server side traces as well as a JDBC transaction (single pixel bracket line) and SQL select statement execution (yellow box). This visualization is helps break down a client side trace by network latency (client request and server response), server side processing, database transaction execution, and post server response processing. Note: This is only possible when using a cluster of client and server processes within the console or alternatively exporting each individual timeline snapshot and later merging into a single one.

Filtering

The timeline analysis supports filtering of the view across all views. Filtering can be applied based on host, process, thread group, thread and datasource. The filter dialog allows for the exclusions of particular timeline elements based on a hierarchy with is associated directly or indirectly with invocations or transactions.

Page 43 of 60

Invocations Table: The view presents the recorded invocations during the tracing period. For each invocation, wall clock, cpu time, blocking, waiting, gc, and allocation metrics are presented as well as additional properties such as target object instance, call stack, thread, and associated transaction. Columns can be sorted, sized and moved.

Transactions Table: The view presents the recorded transactions and enclosed invocations during the tracing period. For each transaction or invocation, wall clock, cpu time, blocking, waiting, gc, and allocation metrics are presented as well as additional properties such as target object instance, call stack, thread. The transactions table helps identify sub transactions as rooted transactions can have child rows consisting of invocations and or sub transactions. Columns can be sorted, sized and moved. The view has options to include or exclude all invocations from the table. Server System Properties The JXInsight server profile stores invocations records in multiple in-memory databases and limits the memory size of the collected timeline records via a rolling mechanism which cycles through a pre-configured number of databases. For each database a record limit (numperslot) is defined before a new database (numofslots) is created or reused. The following system properties with their defaults listed can be used to configure this behaviour. IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. -Djxinsight.server.profiler.timeline.numofslots=5 -Djxinsight.server.profiler.timeline.numperslot=5000 The following additionally system properties allow for filtering prior to storage within in-memory database reducing the memory requirements for heavy loaded systems. -Djxinsight.server.profiler.timeline.filter.invocation.clocktime=10 -Djxinsight.server.profiler.timeline.filter.repeat.clocktime=250 The invocation clock time is used to filter the creation of invocation records based on the clock time of the intercepted method invocation. The system property specifies the minimum invocations clock time in microseconds before a record is created. The repeat clock time property specifies the time limit in microseconds between multiple method dispatches on the same JDBC object instance that should be considered repeat calls. In the interval (non-profiled time) between the last call and the current call for the same method is less than the system property then the invocation record for the last call will be reused with the number of executions incremented. The clock value associated with the invocation is based on the start time of the last invocation and the end time of the current invocation. It is important not to specify too large a value as this will affect the timeline views making a repeating call appear to consume more clock time. For resultset.next() calls the ability of the profiler to merge such records is important in reducing the memory footprint. The timeline feature is also dependent on the following system properties which are listed in the sample jxinsight.properties.config located in <jdbinsight-install-root>/properties directory. # determines whether invocations on plain statement objects are intercepted

Page 44 of 60

jxinsight.server.jdbc.statement.intercept=true # determines whether invocations on prepared statement objects are intercepted jxinsight.server.jdbc.preparedstatement.intercept=true # determines whether invocations on callable statement objects are intercepted jxinsight.server.jdbc.callablestatement.intercept=true # determines whether invocations on resultset objects are intercepted jxinsight.server.jdbc.resultset.intercept=true # determines whether invocations on database metadata objects are intercepted jxinsight.server.jdbc.databasemetadata.intercept=true # determines whether invocations on resultset metadata objects are intercepted jxinsight.server.jdbc.resultsetmetadata.intercept=true # determines whether setXXX invocations on prepared statements are intercepted jxinsight.server.jdbc.preparedstatement.set.intercept=false # determines whether next() invocations on resultset objects are intercepted jxinsight.server.jdbc.resultset.next.intercept=true # determines whether getXXX() invocations on resultset objects are intercepted jxinsight.server.jdbc.resultset.next.intercept=false When specified on the command line of a Java server process the property name must be prefixed with ‘-D’ (without quotes).

Page 45 of 60

Chapter 13 – Metrics Introduction A new Metric mode has been added within the console that provides a high level view of the last 60 minutes of JVM and JDBC activity. The JVM counters such as waiting and blocking relate to all activity within the VM including non-JDBC work. The information visualizations associated with the mode allow for visual comparison and correlation of a large multiple of JVM/JDBC counters. It is relatively easy to correlate across metrics via the spark-line bar charts graphics in the table view. Patterns of behaviour over time are equally visible complimenting the correlation efficiencies.

The table cell rendering compresses the large sample values into a maximum possible width of 720 pixel bars. Each pixel bar represents a 5 second interval (60 minutes * 60 seconds = 3600 seconds / 720 pixels => 5 seconds). The height of a bar is based on the bar’s value as a percentage of the maximum value recorded across all bars: colour encoded is likewise determined. For cumulative metrics the bar value for the 5 second interval is the difference between the first and last values within the interval. For all other metrics the bar value is the average of all sampled values recorded during the interval. Metrics have two board categories – JVM and JDBC. The JVM metrics are captured via the JVMPI agent installed with the VM parameter –Xrunjdbinsight. The JVM metrics are dependant on the JVMPI events enabled via the console or command line. JVM metrics are recorded for both JXInsight (User Tracing) or JXInsight (JDBC) clients and servers. The JDBC metrics are applicable for clients and servers accessing enterprise data via a JDBC driver or datasource that has been proxied by JXInsight. Useful server system properties related to metrics IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. jxinsight.server.profiler.metrics.sample.enabled=[true|false] default = true jxinsight.server.profiler.metrics.sample.interval=[milliseconds] default = 1000 (one second) Note: The metrics can be accessed from the terminal add-on. The textual output can be repeatedly refreshed from within this tool.

Page 46 of 60

Available Metrics Name Description jdbc.exception.cumulative.count The count of SQL exceptions thrown for intercepted driver and datasource calls. jdbc.exception.cumulative.time The clock time recorded for intercepted calls throwing SQL exceptions. jdbc.execute.cumulative.count The count of execute statements invoked. This is typically the number of SQL

commands executed against a database. jdbc.execute.cumulative.time The total clock time recorded for statements executing actually SQL commands

against a database. jdbc.resource.close.cumulative.count The count of close method calls on monitored JDBC resource object references. jdbc.resource.close.cumulative.time The total clock time associated with close method calls. jdbc.resource.create.cumulative.count The count of method calls resulting in the creation of JDBC resource objects. jdbc.resource.create.cumulative.time The total clock time associated with the creation of JDBC resource objects. jdbc.resource.unreference.cumulative.count The count of unreferenced JDBC resource objects. jdbc.resultset.next.cumulative.count The count of next method calls on JDBC result set objects. jdbc.resultset.next.cumulative.time The clock time associated with next method calls on result set objects. jdbc.transaction.allocation.cumulative.bytes The count of bytes allocated during transaction executions. jdbc.transaction.average.time The average clock time of transaction executions. jdbc.transaction.blocking.cumulative.time The total clock time for blocking events occurring during transaction executions. jdbc.transaction.commit.cumulative.count The total count of committed resource transactions. jdbc.transaction.commit.cumulative.time The total clock time associated with committed transactions. jdbc.transaction.cpu.cumulative.time The total cpu time consumed during transaction executions. jdbc.transaction.cumulative.count The count of executed transactions. jdbc.transaction.cumulative.time The total clock time for executed transactions. jdbc.transaction.current.count The count of active transactions. jdbc.transaction.gc.cumulative.time The total clock time for GC events occurring during transaction executions. jdbc.transaction.rollback.cumulative.count The count of transactions rolled back. jdbc.transaction.rollback.cumulative.time The total clock time associated with rolled back transactions. jdbc.transaction.throughput.count The transaction throughput count. jdbc.transaction.waiting.cumulative.time The total clock time for wait events occurring during transaction executions. jvm.allocation.cumulative.bytes The count of bytes allocated during the JVM’s execution. jvm.allocation.cumulative.count The number of objects allocated during the JVM’s execution. jvm.blocking.current.count The count of threads currently blocked on acquiring monitors. jvm.blocking.enter.cumulative.count The total count of enter events on contended monitors. jvm.blocking.entered.cumulative.count The total count of entered events on contended monitors. jvm.cpu.cumulative.time The total CPU time consumed during the JVM’s execution. jvm.cpu.percent The CPU percent for the JVM. This value factors in the number of processors. jvm.gc.cumulative.count The count of GC events occurring during the JVM’s execution. jvm.gc.cumulative.time The total clock time associated with GC events occurring. jvm.memory.free.bytes The count of free bytes. jvm.memory.free.percent The percentage of free bytes (free bytes * 100 / total bytes). jvm.memory.total.bytes The count of bytes allocated to the JVM heap. jvm.memory.used.bytes The count of bytes currently allocated from the JVM heap. jvm.memory.used.percent The percentage of used bytes (used bytes * 100 / total bytes) jvm.thread.current.count The count of threads currently active (started but not ended). jvm.thread.end.cumulative.count The count of threads that have ended. jvm.thread.start.cumulative.count The count of threads that have been started. jvm.waiting.current.count The count of threads currently waiting on a monitor. jvm.waiting.enter.cumulative.count The count of threads that have called wait on a monitored. jvm.waiting.exit.cumulative.count The count of threads that have returned from a wait call on a monitor.

Page 47 of 60

Chapter 14 – JXInsight Traces Introduction IMPORTANT JXINSIGHT 4.0 CHANGE NOTE Public trace extension classes have been migrated from com.jinspired.jdbinsight.trace.* to com.jinspired.jxinsight.trace.*. For backward compatibility the classes in com.jinspired.jdbinsight.trace.* still remain though in most cases they merely extend from the migrated and supported versions in com.jinspired.jxinsight.trace.*. The JXInsight Driver and DataSource classes remain unchanged. The JVMPI profiler has been augmented to allow users to profile applications at various levels (methods, user transactions, workflows, framework interceptions points, and AOP point cuts). The new Trace API (com.jinspired.jxinsight.trace.Tracer – jxinsight-all.jar or jxinsight-core.jar) provides flexible instrumentation and measurement capabilities allowing for specific individual code blocks to be profiled in terms of object allocation, thread waiting and blocking, GC and CPU and wall clock times. It is even possible to profile a thread call stack sequence – a trace can be started in a higher calling method and stopped in a called method. Traces can be nested and transferred between client and server processes allowing for distributed trace correlation and JVM statistic aggregation. All traces are associated with the calling thread. The traces started and stopped can be accessed from within the JXInsight console by creating a server, selecting the profile mode and then switching to the Traces perspective. To profile a particular code block surround it with the following code template try { Tracer.start(“mytraceid”); // code block to be profiled } finally { Tracer.stop(); } The following code example shows the nesting of traces. public void doOuter() {

try { Tracer.start(“outer”); doInner(); } finally { Tracer.stop(); }

} public void doInner() {

try { Tracer.start(“inner”); // do some work } finally { Tracer.stop(); }

} Model Concepts A Trace represents an entry in an executed trace stack similar to Call for Java call stacks. A Trace is uniquely identified by a string id and its parent Trace reference (caller). The parent Trace is the value of the active trace on the trace stack when the Trace was started. A Trace object aggregates JVM counters (into statistics) across multiple executions of the trace stack across multiple threads, processes and hosts. A TracePoint represents the execution of a Trace for a particular Java call stack this means a Trace can have multiple executions started from different locations within the Java code base allowing for arbitrary grouping of statistics by users and third party extension providers as well as isolation from any potential code changes. Traces can have meaningful business or operational identifiers and reduce the requirement for performance analysis staff to understand the class names and methods. The call stack is still available for most traces but it has a secondary importance in the displaying of information visualizations.

Page 48 of 60

cd

Trace

+ parent: Trace+ identifier: String+ statistics: Statistics

TracePoint

+ trace: Trace+ callstack: Call+ statistics: Statistics

Call

+ caller: Call

0..*

+tracepoint

1

+trace

0..*+tracepoint

1+call

+parent 0..1+children 0..*

The profile model created by the execution of the doOuter() method in the example above will consist of 2 Traces and 2 TracePoints as well as 2 Java Call Stacks. The first Trace will have an identifier of “outer” with a null parent. The second child Trace will have an identifier of “inner” with a parent reference to the Trace object identified by “outer”. A TracePoint will be created for both traces. The first TracePoint will have a reference to a Call object that references the doOuter() method. The second TracePoint will have a reference to a Call object references the doInner and indirectly doOuter() via the caller attribute. The JVM statistics (clock, CPU, blocking, waiting, GC, object allocations) for the “outer” includes the child “inner” statistics. To help isolate trace hotspots traces also provide additional calculated fields such as “Clock Total (S)” and “Clock Total (I)”. The first field returns the total for immediate sub traces. The second field returns the inherent clock time for all trace executions. Sub and Inherent totals are provided for each JVMPI agent event counter.

The add and remove methods of the Tracer API facilitate the adding and removing of Traces on the trace stack for the purpose of grouping and aggregation of statistics. Such traces do not have associated TracePoints or actually statistics – clock times are aggregated in the “Clock Time (S)” field. The VisiBroker and Servlet Filter extensions use Tracer.add(“xxx”) and Tracer.remove() method calls to break down traces into individual named traces. For example the VisiBroker extension is by default configured to create 3 Traces for each actually intercepted client or server request by specifying the following system property:

Page 49 of 60

IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All system properties have been changed from jdbinsight.* to jxinsight.*. For backward compatibility existing jdbinsight.* properties will be recognized though it is strongly recommended that all customers upgrade their existing configurations. -Djxinsight.server.tracer.ext.visibroker.trace.identifiers=${visibroker.protocol},${visibroker.typeid},${visibroker.operation} Trace Root System Property The system property -Djxinsight.server.tracer.root allows for the creation of a default trace root(s) for all thread trace stacks. By creating trace roots it makes it easier to identify particular processes or hosts within a clustered trace model. The strings are added as distinct trace nodes to explicit traces trees. The possible list values include ${host} ${process} ${threadgroup} ${thread} The following setting -Djxinsight.server.tracer.root=${host},${thread} will result in the grouping of traces by host and then thread. It is also possible to include arbitrary strings such as -Djxinsight.server.tracer.root=${host},test1 which will result in the prefixing of all traces with the host name and the string value 'test1'. The default value is -Djxinsight.server.tracer.root=${host},${process}. IMPORTANT JXINSIGHT 4.0 CHANGE NOTE Please read Chapter 4 in the Install Guide for information about the many technology and platform extensions provided out of the box. Traces Views

Traces Table: The view presents statistical measurements captured for JXInsight Traces in a tabular format. The measurements relate to the period between the start and stop of a Trace’s execution. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The Identifier column provides a tree navigation of the recorded trace stacks. Selecting a Trace within this view results in changes in the views contained in the bottom view site.

Page 50 of 60

Interceptions Table: The view presents the statistical measurements for all interceptions of the selected SQL, in a tabular format. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The view is filtered based on the selected Trace in the Traces Table view.

Paths Table: The view presents statistical measurements captured at the path level in a tabular format. The measurements relate to the period between the start and end of a paths execution (the jdbc transaction). Path measurements also include non-jdbc work. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The view is filtered based on the selected Trace in the Traces Table view. All visible Paths have at least one Interception which has the selected Trace on its trace stack.

Trace Points Table: The view presents statistical measurements recorded for TracePoints (Trace.start() method calls in a tabular format. The measurements relate to the period between the start and end of a Traces execution keyed additionally on the Java call stack. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The view is filtered based on the selected Trace in the Traces Table view.

Page 51 of 60

Leaf Traces Table: The view presents statistical measurements captured for JXInsight Traces in a tabular format. The measurements relate to the period between the start and stop of a Trace’s execution. For each measurement, total, min, average and maximum statistical values are presented. Columns can be sorted, sized and moved. The Traces displayed are leaf Traces of the Trace selected in the Traces Table view. Double clicking on a leaf Trace will result in the expansion and selection of the leaf Trace in the Traces Table view. The view is useful when viewing a top level Trace in the Traces Table view and wishing to navigate quickly to leaf Traces. All Remote Views: The remote views present statistical measurements captured for JXInsight Traces in a tabular format across distributed processes where the selected Trace in the Traces Table view appears as a forwarded and embedded client Trace. The remote views make is relatively easy to select a Trace in a Swing or Web client and immediately determine the number of resources transactions executed as a result of the Traces execution.

Page 52 of 60

Chapter 15 – JXInsight Console and Terminal Tools IMPORTANT JXINSIGHT 4.0 CHANGE NOTE All JXInsight application startup scripts have been changed from jdbi*.(bat|sh) to jxinsight-*.(bat|sh). jdbiconsole.(bat | sh) => jxinsight-console.(bat | sh) jdbiterminal.(bat | sh) => jxinsight-terminal.(bat | sh) jvmpitest.(bat | sh) => jxinsight-jvmpitest.(bat | sh) Running In the installation root directory there are 2 script files – jxinsight-console and jxinsight-terminal. For Windows users the files will have a .bat extension. For UNIX users the file will have a .sh extension. The installer will also create shortcuts on the desktop or in your home directory during the standard installation. All scripts should be run with the working directory set as <jxinsight-install-root-dir>. Console JXInsight comes with a powerful Java application console, which is able to automatically detect application server processes on the network that have instantiated either a JXInsight driver or JXInsight trace in the server’s process. The console can connect to servers and read the profiling data captured. The profiling information extracted is then presented in highly intuitive and detailed views. The JXInsight console sets a new standard in terms of ease of use, quality of presentation, and interaction style not evident in many of the current Java development tools on the market. The JXInsight console is discussed in later chapters. Terminal Services The JXInsight Terminal Services provides a quick and easy way to communicate with multiple servers without having to use a graphical user interface. This facilitates the streamlined connection, activation and deactivation of profiles on local or remote servers with the ability to control multiple servers from a single terminal. These Terminal Services also provide a powerful environment to create and schedule snapshot information, in order to monitor servers at regular intervals. It provides the ability to store and retrieve snapshots from any mounted drive, as well as providing a rich set of commands to assist in analysis of this highly detailed data. The installation of the JXInsight console will in addition install the necessary files to invoke the Terminal Services. Once you have run the appropriate script or command file you will see the following screen displaying the version and license information for the Terminal Services together with the $ prompt.

s:\jdbinsight>jre\bin\java -Xms64M –Xmx96M -Xrun"bin/windows/jdbinsight":off -jar lib/jxinsight-terminal.jar c:\jdbinsight_3_0>jre\bin\java -Xms64M -Xmx192M -Xrun"bin/windows/jdbinsight":off -jar lib/jxinsght-terminal.jar [jdbiagent] jvm load [jdbiagent] agent class loaded [jdbiagent] library version 3.0 [jdbiagent] build 1021 [jdbiagent] registering natives [jdbiagent] previous product evaluation detected [jdbiagent] license key is: 4B4EDF8CAE65C80 [jdbiagent] current time is Mon Dec 06 03:46:58 CET 2004 [jdbiagent] evaluation license expires on Sat Dec 25 12:00:00 CET 2004 [jdbiagent] license validated [jdbiagent] initializing agent static fields JXInsight 2.0 Terminal Services. Version [2.20] (C) Copyright 2002-2005 JInspired Inc.

$

In order to see a list of available commands execute the following command in the terminal window as shown below:-

JXInsight 2.0 Terminal Services $ help -group full Group: Server ping -(h)ostname [host-name] -(p)ort [port-number] server -start|stop|reset -(h)ostname [host-name] -(p)ort [port-number] timer -start|stop Group: Script script -(e)xecute -(r)ead -(f)ile [file-name] -(d)irectory [directory-name] Group: Terminal exit gc help -(g)roup [full|list] -(c)ommand [command-name] -(man)ual memory

Page 53 of 60

Group: Snapshot callstack -(e)ntrypoint [classification] classification -(c)lass [classname] -(m)ethod [method-name] classified -(c)lassification [classification-type] classify count -(t)ype [type-name] describe -(class)name [class-name] -(i)interface -(impl)ementation -(m)ethod find -(t)ype [type] [-(n)ame - (v)alue] resource -jdbc -callstack -depth [callstack-depth] snapshot -[(r)ead|(w)rite|(c)reate|(sch)edule] -(f)ile [file-name] -(d)irectory [directory-name] -(i)nterval [minutes] -start [minutes] -stop -(pre)fix [prefix] -(h)ost [host-name] -(p)ort [port-number] stats -(class)name [class-name] -(m)ethod [method-name] -(p)ath [sequence] -(v)isit [interception] -(i)nterception -(m)ethod [name] -sql [command] -clock wall|adjusted -cpu -(b)locking -(w)aiting - (a)llocation unclassify $

Commands are grouped into the four main target categories these categories consist of Server, Snapshot, Scripting and Terminal. Commands that are listed under the specified group may be related. A command instruction is followed by a list of options applicable to that command. An option is always preceded by a hyphen and may contain an additional value. Options may have both a short-name and a long-name, the short-name (where applicable) will be enclosed in parenthesis, for example, ping –(h)ost –(p)ort indicates that in order to specify that option the letter(s) enclosed in the brackets represent the short-name for that particular option, below is an example of using both the long-name and the short-name for options in respect of the ping command.

JXInsight 2.0 Terminal Services $ ping –host localhost –port 1515 or $ ping –h localhost –p 1515

In order to get further information on any particular command a usage option and a manual option are provided. The usage option will provide a list of options for a specific command displaying the short-name and the long-name for each available option.

JXInsight 2.0 Terminal Services $ ping -usage ping -(h)ostname [host-name] -(p)ort [port-number] $

In addition detailed information on a particular command can be obtained by the use of the –(man)ual option, this will also provide examples of how to use the specified command :-

JXInsight 2.0 Terminal Services] $ ping -man Ping: Attempts to connect a specified host on a specify port in order to ascertain whether a server is active. Options: -host: specify a host name default is localhost -port: specify a port number default is 1515. Examples: ping -host 172.105.45.20 - default port is 1515 ping -port 2524 - default host is localhost $

In addition, options may have a default value, which does not have to be specified unless of course the default value has been overridden or is not applicable. For example, the command below will automatically default to –h localhost –p 1515

JXInsight 2.0 Terminal Services $ ping

Page 54 of 60

The injecttrace command inserts a trace identifier that spans thread groups and threads. It can be viewed somewhat like a system trace root identifier but over time dynamic. The options are -get: retrieve the currently specified trace. -set: specify a new trace entry onto the trace stack for all future traces. -remove: remove the currently set trace. -host: direct the injecttrace action to a specified host. -port: specify the active port for a specifed server. Examples: injecttrace -set traceName -host 172.29.20.20 injecttrace -get -host 172.29.20.20 injecttrace -remove -host 172.29.20.20 The monitor command allows the dynamic setting of JVMPI events such as garbage collection, blocking, waiting, object allocations as well as server options profile and timeline analysis. The options are -status: retrieve the status of all monitoring events and profiling. -events: instructs the server to dynamically start monitoring gc, blocking, waiting and allocations. note events not listed within the -event {g|b|w|a} will be switched off. -profile: instructs the server to start|stop profiling. -timeline: instructs the server to start|stop tineline analysis. -host: specify a host name default is localhost -port: specify a port number default is 1515. Examples: monitor -events gbwa -profile start -timeline stop -h localhost -p 1515 monitor -events bw -pr start -tl start -h localhost -p 1515 monitor -status -h localhost -p 1515 Snapshots JXInsight Terminal Services permits the creation of snapshots both manually and automatically scheduled from the terminal command line. The snapshot command facilitates the reading, writing and scheduling of snapshots, connecting to a currently active server in order to create a snapshot dynamically or simply reading a previously created snapshot from the file system for subsequent investigation.

JXInsight 2.0 Terminal Services $ snapshot -usage snapshot -[(r)ead|(w)rite|(c)reate|(sch)edule] -(f)ile [file-name] -(d)irectory [directory-name] -(i)nterval [minutes] -start [minutes] -stop -(pre)fix [prefix] -(h)ost [host-name] -(p)ort [port-number] $

Once a server is active, the terminal can connect to it in order to create a snapshot or interrogate the server dynamically. Below is an example of how to create a snapshot from an active server. The terminal provides summary information of the creation:-

JXInsight 2.0 Terminal Services

$ snapshot -create -f wls8.1-SPECjAppServer2002.snp -d snapshots -h JINSPIRED-005 -p 1515 Connecting to JINSPIRED-005:1515 Connection time: 70 Invocation time: 1322 Model size: 1982 File write time: 170 Model saved to file: wls8.1-SPECjAppServer2002.snp File size is: 26624 Reading in model from saved... File read time: 231 Model size: 1982 Indexing model... Model indexing time: 10 Checking index by querying number of Java classes... Number of Java classes: 212 Query time: 0 $

Page 55 of 60

In the above example the server connects to the hostname JINSPIRED-005 on port 1515 and creates a snapshot with a filename of wls.81.-SPECjAppServer2002 in a sub-directory relative to the installation directory of the Terminal. This snapshot can be viewed by the JXInsight console or further analysed by the Terminal Services. The schedule option is provided in order to plan a snapshot, the start time and the interval time are specified using their respective options.

JXInsight 2.0 Terminal Services $ snapshot -sch -prefix myapplication- -start 5 -i 20 -host 172.29.20.5

The above example schedules the creation of a series of snapshots for the host 172.29.20.5 starting after 5 minutes with intervals of 20 minutes. The snapshots will have a random generated file name prefixed with myapplication- for easier identification. In order to stop the automatic scheduling of these snapshots the snapshot scheduler requires a stop instruction issued for that hostname the details of which are displayed below:-

JXInsight 2.0 Terminal Services $ snapshot -sch -stop -host 172.29.20.5

Once a snapshot has been generated commands exist for the interrogation of resource usage, statistics, classification and callstack information amongst others. Please note in order to obtain accurate snapshot information the snapshot after loading or creation must be classified. This can be performed using the classify command as shown below:-

JXInsight 2.0 Terminal Services $ classify

An example of one of these useful commands is the resource command which provides information related to the creation, closure and unreferenced resources, as shown below:- The dump command instructs the server to export a model to the servers local file system. When no arguments are specified the command will attempt to export all snapshot types.

$ dump $ dump -host 172.29.20.20 $ dump -type tl $ dump -type profile $ dump -type profile -host 172.29.20.20

Page 56 of 60

Metrics JXInsight Terminal Services permits the display of metric information; this is a high level view of the last 60 minutes of JVM and JDBC activity. The information provides crucial information related to transactions, jdbc, threads amongst others. The metrics command has the ability to output this high level summary categorized by type and value. The –repeat option allows the metric information to be re-displayed or output to a file after a period of time, specified in seconds.

JXInsight 2.0 Terminal Services $ metrics –repeat 25 -host 172.29.20.5 Invocation time: 691 Metrics size: 93 +---------------------------------------------------+--------------------+ | Metric Type | Last Value | +---------------------------------------------------+--------------------+ | jvm.waiting.exit.cumulative.count | 19394 | | jdbc.exception.cumulative.time | 0 | | jdbc.transaction.cpu.cumulative.time | 350504 | | jdbc.transaction.cumulative.count | 6 | | jvm.thread.end.cumulative.count | 50 | | jdbc.resource.unreference.cumulative.count | 20 | | jvm.blocking.enter.cumulative.count | 1469 | | jdbc.transaction.average.time | 576535 | | jvm.memory.free.percent | 9 | | jvm.cpu.percent | 2 | | jdbc.transaction.commit.cumulative.count | 6 | | jvm.blocking.entered.cumulative.count | 1469 | | jvm.memory.total.bytes | 312213504 | | jvm.memory.used.percent | 90 | | jdbc.transaction.rollback.cumulative.count | 0 | | jdbc.transaction.waiting.cumulative.time | 1358944 | | jvm.memory.free.bytes | 28353328 | | jvm.thread.current.count | 52 | | jdbc.transaction.blocking.cumulative.time | 25898 | | jvm.thread.start.cumulative.count | 102 | | jdbc.resultset.next.cumulative.time | 314 | | jdbc.resource.close.cumulative.time | 482823 | | jvm.waiting.current.count | 30 | | jdbc.transaction.gc.cumulative.time | 0 | | jdbc.resource.close.cumulative.count | 14 | | jdbc.execute.cumulative.time | 0 | | jdbc.resource.create.cumulative.time | 9808364 | | jvm.memory.used.bytes | 283860176 | | jdbc.resource.create.cumulative.count | 20 | | jvm.allocation.cumulative.count | 18180478 | | jvm.allocation.cumulative.bytes | 108166168680 | | jdbc.execute.cumulative.count | 0 | | jdbc.transaction.commit.cumulative.time | 3459214 | | jdbc.exception.cumulative.count | 0 | | jdbc.transaction.cumulative.time | 3459214 | | jvm.waiting.enter.cumulative.count | 19424 | | jvm.cpu.cumulative.time | 496774326 | | jvm.gc.cumulative.time | 219604741 | | jdbc.transaction.throughput.count | 0 | | jdbc.transaction.allocation.cumulative.bytes | 1506312 | | jdbc.transaction.current.count | 0 | | jvm.blocking.current.count | 0 | | jdbc.transaction.rollback.cumulative.time | 0 | | jvm.gc.cumulative.count | 405 | | jdbc.resultset.next.cumulative.count | 12 | +---------------------------------------------------+--------------------+ $

Page 57 of 60

JXInsight 2.0 Terminal Services $ resource –jdbc +-------------------+------------------+------------------+------------------+ | | Creation | Closure | UnReferenced | +-------------------+------------------+------------------+------------------+ | Connection | 40 | 0 | 0 | | DatabaseMetaData | 20 | 0 | 0 | | PreparedStatement | 744 | 0 | 0 | | ResultSet | 66 | 66 | 0 | | Statement | 53 | 53 | 0 | +-------------------+------------------+------------------+------------------+ | Totals | 923 | 119 | 0 | +-------------------+------------------+------------------+------------------+ $

Call stack information can also be obtained to further analyse these resource discrepancies by the use of the resource –callstack command. Please refer to the help system for examples of how to use this command. Statistics can also be viewed for performance counters dependant upon the counters defined within the JVMPI agent on the server. Please refer to the JVMPI section above for details of the configuration for these counters. Once a snapshot is active and has been classified performance counters may be displayed at the method level. The example below shows the performance counters for the findLargeOrders method of the org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB class. The –file option allows the output to be redirected to the specified stats.txt file:-

JXInsight 2.0 Terminal Services $ stats -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB -m findLargeOrders -visit -f stats.txt.

The output to file stats.txt shows the available counters currently active within this snapshot together with useful performance measurements. Statistics Visit ================ Class: org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB Method: findLargeOrders +---------------------------------+------------------------------+---------------------------------+ | Clock | Cpu | Adjusted | +---------------------------------+------------------------------+---------------------------------+ | Count Total Avge Min Max | Count Total Avge Min Max | Count Total Avge Min Max | +---------------------------------+------------------------------+---------------------------------+ | 6431 2818214 438.22 5 92758 | 2925 130188 44.51 0 10015 | 7397 3781000 511.15 5 92758 | +---------------------------------+------------------------------+---------------------------------+

Server A group of commands related to the server permit the profiler to be started, stopped or reset in order to further control the initiation of generated snapshot information. Using the –stop option for the server command will stop the profiler from storing any profiling information captured by the agent.

JXInsight 2.0 Terminal Services $ server -help $ server -start|stop|reset -(h)ostname [host-name] -(p)ort [port-number]

Scripting The JXInsight Terminal provides the ability to execute commands within a script file; this facilitates the automatic execution of several terminal commands in order to assist with the analysis of server activities. A sample script is provided in order to outline what is currently possible when chaining a series of terminal commands for snapshot analysis.

JXInsight 2.0 Terminal Services $ script –read –f sample.script

The above command will display the contents of the sample.script as follows:-

Page 58 of 60

echo reading snapshot... snapshot -read -f wls.snp echo writing snapshot... snapshot -write -f wls-SPECjAppServer2002.snp -d c:/snapshots echo reviewing memory... memory // classify all methods and classes within the model echo classifying... classify // check for classification echo checking classification classification -class echo review callstack entry point for a specific classification callstack -e ejb:find callstack -e ejb:load callstack -e ejb:store echo review classified for a particular classification echo print out all classifications find -type classification echo print classification for a particular class classification -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB echo describe interfaces for class describe -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB -i echo describe methods for class describe -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB -m echo output resource callstack descrepencies to file callstack.txt resource -callstack -depth 10 -f callstack.txt echo write statistics information for class LargeOrderSesEJB method findLargeOrders to file stats.txt stats -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB -m findLargeOrders -visit -f stats.txt echo print resource utilization for snapshot resource -jdbc. Executing the script from the Terminal command line with the command as shown below will produce the following extract :-

JXInsight 2.0 Terminal Services $ script –execute –f sample.script

echo reading snapshot... $ snapshot -read -f wls.snp echo writing snapshot... $ snapshot -write -f wls-SPECjAppServer2002.snp -d c:/snapshots echo classifying... $ classify

classify: model classified echo checking classification $ classification -class

echo review callstack entry point for a specific classification $ callstack -e ejb:find + org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSes_gjlri5_EOImpl_WLSkel.invoke --+ org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSes_gjlri5_EOImpl.findLargeOrders ----+ org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.findLargeOrders ------+ org.spec.jappserver.mfg.largeorderent.ejb.LargeOrderEnt_gem3t0_LocalHomeImpl.findAll --------+ java.lang.reflect.Method.invoke

Page 59 of 60

----------+ sun.reflect.DelegatingMethodAccessorImpl.invoke ------------+ sun.reflect.GeneratedMethodAccessor78.invoke --------------+ org.spec.jappserver.mfg.largeorderent.ejb.LargeOrderEnt_gem3t0__WebLogic_CMP_RDBMS.ejbFindAll

echo review classified for a particular classification $ callstack -e ejb:store

+ org.spec.jappserver.orders.orderses.ejb.OrderSes_534r13_EOImpl_WLSkel.invoke --+ org.spec.jappserver.orders.orderses.ejb.OrderSes_534r13_EOImpl.changeOrder ----+ org.spec.jappserver.orders.orderent.ejb.OrderEnt_nrczp2__WebLogic_CMP_RDBMS.ejbStore

echo print classification for a particular class $ classification -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB

ejb:bean ejb:session

echo describe interfaces for class $ describe -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB –I

javax.ejb.SessionBean java.io.Serializable javax.ejb.EnterpriseBean

echo describe methods for class $ describe -class org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB –m

org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.ejbCreate org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.setSessionContext org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.ejbRemove org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.ejbPassivate org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.createLargeOrder org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.findLargeOrders org.spec.jappserver.mfg.largeorderses.ejb.LargeOrderSesEJB.ejbActivate

Commands in the Server and Script command groups can also be passed to the jxinsight-terminal from the command line allowing for integration with other scripting environments and tools. jxinsight-terminal snapshot -create -f profile.snp -d snapshots -h localhost -p 1515

Page 60 of 60

Chapter 16 – Custom Classifications Introduction JXInsight comes with standard classifications for Java enterprise technologies such as EJB, JDBC, JMS, Servlets and Java Server Pages. Additional call stack classifications are provided for popular persistence technologies such as Hibernate and JDO. Classifications are used by JXInsight to better visualize the call stack of intercepted JDBC methods and highlight contributors to the level interaction of between a Java enterprise application and an enterprise data store. For proprietary application server technologies and persistence engines JInspired offers services to provide custom classifications. JXInsight classifications can be applied to business systems, such as CRM’s, relying on the JDBC API for resource communication. Classifications are under development for other Java enterprise technologies, with the possibility of allowing user defined classifications. The following screen shot shows a custom classification that was created for HP OpenView Service Desk product.