Foglight for Java EE Technologies 5.9.7.5

Excluding a class prevents the class from being instrumented as user code. It may still be partially instrumented if it implements important application server functionality (such as RMI communications).

Including a class ensures the class is specified and instrumented as user code.


	NOTE: This setting is only valid for FullDetail, ComponentDetail, and BasicDetail instrumentation levels. Changing its value has no effect if the Instrumentation Level is set to NoDetail. For details about setting instrumentation levels, see “Changing the Instrumentation Level for Request Metric Data Collection” on page 55.

For more information about instrumented class and custom components, see: Customizing Instrumented Classes , and Changing Custom Component Settings .

To exclude a user class or package:


	TIP: To review how to access the instrumentation settings editor, see Editing Agent Instrumentation Configurations .

On the General tab of the Edit dialog box, click Edit

beside UserClasses.

In the Settings Editor dialog box, click

Add.

A new row appears. By default, the Include or Exclude option is set to include.

Click include. The setting switches to exclude.

If you want the class name to be treated as a regular expression, select the Regex check box.

Click the Class Name box and type the name of the class you want to exclude.

For example, suppose you have an instrumented user class named com.globex.plan.DominateWorld, but the instrumentation is causing excessive load on the agent or Nexus. You can exclude this class.

You can also exclude entire packages. For example, com.globex.scheme.

The class com.globex.plan.DominateWorld is excluded, as well as all classes in the package "com.globex.scheme".


	IMPORTANT: Order is important. You can use multiple include and exclude elements to build a pattern, but it is the first element that matches that controls the outcome.

For example:

In this case, the class com.globex.plan.DominateWorld is included, but the class com.globex.pocket.Sugar is actually excluded because it matches the exclude pattern on the second line. Also, any classes in net.globex. package or the root globex. package are excluded since they match the exclude regular expression.


	TIP: For more information about regular expressions, see the “Appendix: Regular Expressions” in the Monitoring Application Servers User and Reference Guide.

In the Settings Editor dialog box, click OK to save your changes to the user class instrumentation.

In the Edit dialog box, click Save.

Restart your application server.

Manual Configuration - UserClasses

If you manually edit the instrumentation.config file, use the following syntax to enable user class or package instrumentation:

•

UserClasses = ClassList();

Example #1

One use for configuring user classes is to exclude a class because instrumenting it is causing excessive load on the agent or Nexus. You can also include/exclude entire packages:

UserClasses = ClassList(
exclude "com.globex.plan.DominateWorld",
exclude "com.globex.scheme."
);

The class com.globex.plan.DominateWorld is excluded, as well as all classes in the package "com.globex.scheme".

Example #2

Regular expressions can also be used to include or exclude classes. Also, multiple include and exclude elements can appear in the block, but it is the first element that matches that controls the outcome.

UserClasses = ClassList(
include "com.globex.plan.DominateWorld",
exclude /(\.|^)globex\./,
include "com.globex.pocket.Sugar"
);

In this case, the class com.globex.plan.DominateWorld is included, but the class com.globex.pocket.Sugar is actually excluded because it matches the exclude pattern on the third line. Also, any classes in net.globex. package or the root globex. package are excluded since they match the exclude regular expression.

For more information about regular expressions, see the “Appendix: Regular Expressions” in the Monitoring Application Servers User and Reference Guide.

Changing Custom Component Settings

The Custom Components setting extends the default set of J2EE components to be included when recording a session at the Component Detail instrumentation level.

In some cases, your distributed application may use third-party technologies that are not part of the default list of items included in the default instrumentation for the Java EE agent. If you want to include these in the component-only view, you can use custom component instrumentation.

The default custom component settings are shown below. Some customizations may be required to add additional classes if these frameworks have been extended. You can add package listings if necessary.

The method signature can be specified but it must be specified using the internal JVM format. For more information see the Oracle Java SE Documentation: http://docs.oracle.com/javase/specs/#7035.

To configure custom components:


	TIP: To review how to access the instrumentation settings editor, see Editing Agent Instrumentation Configurations .

On the General tab of the Edit dialog box, click Edit

beside CustomComponents.

In the Settings Editor dialog box, you can add additional custom components, or include or exclude methods from the default components.

For example, you could add the component Globex, and then specify methods to include or exclude.

Click

Add component.

In the Add component dialog box, type a name for the component. For example, type Globex.

The new component appears at the bottom of the list.

Optional — Include full detail when tracing.

By default, the Java EE agent does not collect method level detail within custom components. If you want traces for custom components you specify to include method level detail, select the Include full detail when tracing check box.

Optional — Add methods to include or exclude.

Click

Add to add a single method at a time.

Click

Add multiple to open a text box where you can type a number of methods.

After you have added as many methods as you want, click OK.

In the Edit dialog box, click Save.

Any components you added appear in the CustomComponents list and, if you enabled full detail while tracing for any methods, the text FULL DETAIL appears beside the custom component name.

Restart your application server.

Manual Configuration - CustomComponents

If you manually edit the instrumentation.config file, use the following syntax to specify custom component instrumentation.

To manually configure custom components:

Edit CustomComponents. Specify the name of each component in a method list, either by entering the name or by forming a regular expression that matches the name or pattern. Enter the include element before each item in the list. For example:

CustomComponents = {

"MQSeries": MethodList(

include /com\.ibm\.mq\..*/

"TopLink": MethodList(

include "oracle.toplink."

"Globex": MethodList(

include "com.globex.plan.DominateWorld",

include "com.globex.pocket.Sugar",

include "com.globex.cypresscreek.HammockHut.sit",

exclude /(\.|^)globex\./

include "com.globex.plan.DominateWorldServlet.doGet(Ljavax/servlet/http/HttpServletRequest;Ljavax/servlet/http/HttpServletResponse;)V",

include "com.globex.plan.DominateWorldHelper.dominate(Ljava/lang/String;Z[B)I",

)

};

When the Java EE agent matches method names to the methods in the list, it interprets them as custom components.

After editing the instrumentation.config settings, ensure it is read by restarting the instrumented application servers.

Default Custom Component List

The default custom component settings are shown below. Some customizations may be required to add additional classes if these frameworks have been extended. In the example below, you can uncomment and add package listings if necessary.

CustomComponents = {

"Apache Beehive": MethodList (

exclude "org.apache.beehive.netui.tags.",

include "org.apache.beehive.",

"Apache Struts": MethodList (

exclude "org.apache.struts.action.ActionServlet",

exclude "org.apache.struts.taglib.",

include "org.apache.struts.",

include "org.apache.strutsel.",

"AquaLogic Service Bus": MethodList (

include "com.bea.wli.config.AppListener",

include "com.bea.wli.sb.",

include "stages.logging.",

include "stages.publish.",

include "stages.routing.",

include "stages.transform.",

"BEA WebLogic Integration": MethodList (

# Consult BEA WebLogic Integration javadoc for more info.

# http://e-docs.bea.com/wli/docs81/javadoc/index.html

include "com.bea.wli.bpm.runtime.",

"FreeMarker": MethodList (

include "freemarker.template.Template",

include "freemarker.template.Configuration",

"GigaSpaces Cache": MethodList (

include "com.j_spaces.",

"Hibernate": MethodList (

include "org.hibernate.",

include "net.sf.hibernate.",

"IBM Portal": MethodList (

# Consult IBM WebSphere Portal javadoc for more info.

# http://www-106.ibm.com/developerworks/websphere/zones/portal/portlet/5.0api/WPS/

# include "com.ibm.wps.portlet.",

# include "com.ibm.wps.portletservice.",

include "org.apache.jetspeed.portlet."

"OpenSymphony": MethodList (

include "com.opensymphony.",

"Oracle Toplink": MethodList (

# Consult Oracle TopLink javadoc for more info.

# http://download-east.oracle.com/docs/cd/B10464_04/web.904/b10491/index.html

include "oracle.toplink."

"Spring": MethodList (

exclude "org.springframework.web.servlet.tags.",

include "org.springframework.",

Changing Custom Component Callbacks Settings

Use the Custom Component Callbacks setting to specify which classes or interfaces are used by custom components to call customer written code. The default instrumentation settings include some custom component callbacks for Apache Struts and Spring.


	NOTE: This setting is only valid for Full Detail and Component Detail Instrumentation Levels. Changing its value will have no effect if the instrumentation level is Basic Detail or No Detail. For information about instrumentation levels, see Changing the Instrumentation Level for Request Metric Data Collection .