## Filters for call tree collection - how they work and how they are configured |
previous | up | next

### 1. Introduction

Call tree collection filters determine the detail level that JProfiler uses when recording call sequences in the profiled application. Filtering helps to eliminate clutter and decrease the profiling overhead for the profiled application. Also see the article on profiling settings for a discussion of profiling settings in general.

Since the internal data storage of CPU data in JProfiler is similar to the invocation tree, call tree collection filters are most easily explained while looking at the invocation tree view. As an example, we profile the "Animated Bezier Curve" demo session that comes with JProfiler. When talking about filters, it is important to define the distinction between your code and framework or library code. Your code should be unfiltered, framework or library code should be filtered. In our example, the `BezierAnim` class is code written by you and the JRE is library code.

### 2. What are call tree collection filters?

The invocation tree shows call sequences. Each node and each leaf of the invocation tree corresponds to a certain call stack that has existed one or multiple times while CPU recording was switched on. You will notice that there are different icons for nodes in the tree. Among other things, these icons serve to highlight if classes are filtered or not.

The methods of a filtered class are endpoints in the call tree, i.e. their internal call structure will not be displayed. Also, any methods in other filtered classes that are called subsequently, are not resolved. If, at any later point in the call sequence, the method of an unfiltered class is called, it will be displayed normally. In that case, the invocation tree shows the filtered parent method with a special icon that indicates that it is from a filtered class and that there may be other method calls in between. The inherent time of those missing method is added to the time of the filtered parent method. In JProfiler's terminology, this is called an "upward filter bag".

### 3. Example with and without filters

The image below illustrates the different node types for a profiling run of the BezierAnim class:

In the above invocation tree, the `java.*` package is filtered, so only the first method in the the AWT event dispatch thread is shown. However, the AWT is a complex system and the `java.awt.EventDispatchThread.run()` does not call `BezierAnim.paint()` directly. If we switch to full instrumentation and disable all filters, the invocation tree looks like this:

Now, the entry method into your code - `BezierAnim.paint()` - is substantially more difficult to find. In cases where events are propagated through a complex container hierarchy, the call tree can become many hundreds of levels deep and it becomes next to impossible to interpret the data. In addition, calls like `java.awt.Graphics2D.setPaint()` show their internal structure and implementation classes. As a Java programmer who is not working on the JRE itself, you probably do not know or care that the implementation class is actually `sun.java2d.SunGraphics2D`. Also, the internal call structure is most likely not relevant for you, since you have no control over the implementation. It just distracts from the main goal: how to improve the performance of your code.

Not only is it easier to interpret a call tree that has proper call tree collection filters, but also the profiling overhead of the profiled application is much lower. Recording the entire call tree without filters uses a lot of memory and measuring each call takes a lot of time. Both these considerations especially apply to application servers, where the surrounding framework is often extremely complex and the proportion of executed framework code to your own code might be very big.

### 4. Configuring call tree collection filters

Call tree collection filters are part of the profiling settings of a session. Please see the article on profiling settings for an explanation on how to change the profiling settings for a session. While call tree collection filters can be changed during a running session, the change will only be effective when the session is restarted.

There are two alternative ways in JProfiler to specify the filtered classes:

- by defining exclusive filters

  By default, a profiling session uses exclusive filters. "Exclusive filters" means that you specify a list of packages that should be filtered. In order to facilitate working with exclusive filters, you do not have to enter the list of packages in a text field but rather select appropriate "filter sets". Filter sets are named lists of packages that apply to a certain software library, application server or software company. The "Bea WebLogic" filter set contains all packages that are part of the Bea WebLogic application server. Filter sets are defined in JProfiler's general settings and are globally available for all sessions.

  For a new profiling session, all filter sets are activated. If you want to resolve classes in a filtered package, you have to deselect the corresponding filter set in the profiling settings.

  Exclusive filters are most appropriate for profiling application servers and regular applications where you're interested in all classes except a set of well-defined framework and library classes. If you have more specific requirements with respect to filtering, inclusive filters might be the better choice.

- by defining inclusive filters

  With inclusive filters you define a list of packages and classes that should not be filtered. The call tree is only resolved for packages and classes that you have specified, all other classes are filtered.

  This approach is recommended if you have a lot of different library or framework classes that are not contained in JProfiler's default list of filter sets, or if your code base is very large and you're only interested in certain parts of it.

### 5. View filters

In addition to the call tree collection filters, there is a view filters control at the bottom of all views that display call trees. View filters are similar to inclusive filters and can be changed during a session. However, they can only reduce the recorded information by taking out classes that do not correspond to the selected view filter.

In the invocation tree, they have a similar behavior like the call tree collection filters. In the hot spot views, they simply hide all classes that do not correspond to the filter selection. This is very different from call tree collection filters, where the hot spots themselves change with different filter settings.