Chat now with support
Chat with Support

Foglight for Java EE Technologies 5.9.9 - Installation Guide

Install and Configure Foglight for Java EE Technologies Integrate with JBoss Integrate with Apache Tomcat Integrate with WebLogic Domain Startup Scripts Integrate with WebSphere Integrate with Oracle AS Create a Generic Installation for Manual Java EE Agent Integration Manage Java EE Agent Installations, Integrations, and Configurations Managing Java EE Agent Configurations Java EE Installation Management Java EE Integration Configuration FAQ and Troubleshooting Manual Application Server Integrations AppendixB: Managing Permissions for the Java EE Integration Agent Appendix A: Java EE Application Methods

Configuring instrumented simple method settings

Simple methods are methods for which instrumentation would add more byte-code and overhead to the original method.
By default, simple methods are not instrumented to reduce overhead of a sampled request and the complexity of single traces. When simple methods are not instrumented, any time spent in those methods is attributed to the caller.
* 
CAUTION: Simple methods usually run quickly, so instrumentation adds unnecessary overhead and complexity.
To explicitly name methods for instrumentation:
* 
TIP: To review how to access the instrumentation settings editor, see Editing agent instrumentation configurations .
1
On the General tab of the Edit dialog box, click Edit beside InstrumentedSimpleMethods.
2
In the Settings Editor dialog box, click Add.
3
If you want the method name to be treated as a regular expression, select the Regex check box.
4
Click in the Method Name box and type the name of the method you want to instrument. For example, in the following image, the getSugar() method is instrumented even if it is detected as a simple method.
5
Click OK.
6
Click Save.
7
Restart your application server.
Manual configuration — InstrumentedSimpleMethods
If you manually edit the instrumentation.config file, use the following syntax to enable simple method instrumentation:
•
InstrumentSimpleMethods = true;
To explicitly name methods to be instrumented, even if they are detected as simple methods:
•
InstrumentedSimpleMethods = MethodList(};
For example, to instrument the getSugar() method even if it is detected as a simple method:
InstrumentedSimpleMethods = MethodList(
include "com.globex.pocket.Sugar.getSugar()",
);

Changing user classes settings

Use the User Classes setting to customize the classes that are treated as user or application code.
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 that 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 .
1
On the General tab of the Edit dialog box, click Edit beside UserClasses.
2
In the Settings Editor dialog box, click Add.
A new row appears. By default, the Include or Exclude option is set to include.
3
Click include. The setting switches to exclude.
4
If you want the class name to be treated as a regular expression, select the Regex check box.
5
Click the Class Name box and type the name of the class you want to exclude.
For example, suppose that 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 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 Foglight for Application Servers User Guide.
6
In the Settings Editor dialog box, click OK to save your changes to the user class instrumentation.
7
In the Edit dialog box, click Save.
8
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 or 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 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 Foglight for Application Servers User 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.
Sometimes, 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 in the following screenshot. 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.
Figure 1. Default custom components
To configure custom components:
* 
TIP: To review how to access the instrumentation settings editor, see Editing agent instrumentation configurations .
1
On the General tab of the Edit dialog box, click Edit beside CustomComponents.
2
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.
a
Click Add component.
b
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.
c
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.
d
Optional — Add methods to include or exclude.
Click Add to add a single method at a time.
Or
Click Add multiple to open a text box where you can type several methods.
3
After you have added as many methods as you want, click OK.
4
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.
5
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:
1
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.
2
After editing the instrumentation.config settings, ensure that 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 the classes or interfaces that the custom components use 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 has 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 .
For more information, see Appendix A: Java EE Application Methods.
Figure 2. Default custom component callback settings
To add custom component callbacks:
* 
TIP: To review how to access the instrumentation settings editor, see Editing agent instrumentation configurations .
1
On the General tab of the Edit dialog box, click Edit beside CustomComponentCallbacks.
2
In the Settings Editor, you can add, remove, or change the order of callbacks.
Click Add to add a single class at a time.
Click Add multiple to open a text box where you can type several classes.
3
After you have added as many classes as you want, click OK.
4
In the Edit dialog box, click Save.
5
Restart your application server.
Manual configuration — CustomComponentCallbacks
If you manually edit the instrumentation.config file, use the following syntax to specify custom component callback instrumentation.
CustomComponentCallbacks = ClassList (
# Apache Struts 1.x
include "org.apache.struts.action.Action",
include "org.apache.struts.action.ActionForm",
include "org.apache.struts.action.ExceptionHandler",
);
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating