Foglight for Java EE Technologies 5.9.10

The default instrumentation level is FullDetail. At full detail level, request monitoring can be enabled and, when single traces are collected, all nodes in the call tree are included. This level provides the most flexibility in terms of request monitoring and single trace collection and should be acceptable for most customers.

If you require request monitoring, but do not require full detail single traces, instrumentation can be set to Component Detail. At component detail level, you can enable request monitoring, but when single traces are collected, they are collected at only the component technology detail level, reducing the complexity of the call tree. This level is more restrictive in what information can be collected for single traces, but reduces both the agent overhead on the monitored server and the load on the Management Server.

If you require request monitoring but only require request metrics for HTTP, JMS, and RMI requests, instrumentation can be set to Basic Detail. At this level, no breakdowns are collected and, if single traces are collected, only HTTP, JMS, and RMI nodes are included in the Request Trace call tree. No other component or full detail methods are collected, therefore reducing both the agent overhead on the monitored server and the load on the Management Server, compared to the Component Detail instrumentation level.

If you do not require request monitoring or the ability to capture single traces, instrumentation for this purpose can be disabled by setting the instrumentation level to No Detail. At this setting, request monitoring cannot be enabled and you are unable to capture single traces at any detail level. This removes instrumentation overhead on the monitored server and greatly reduces load on the Management Server.


	IMPORTANT: If you want to monitor the classes or interfaces that custom components use to call customer written code, see Changing custom component callbacks settings .

To set the instrumentation level:


	TIP: To review how to access the instrumentation settings editor, see Editing agent instrumentation configurations .

On the General tab of the Edit dialog box, select the instrumentation level from the InstrumentationLevel list.

•

Full Detail — Instruments at full detail level. All methods in the call tree are captured.

•

Component Detail — Instruments at the component level only. Methods from defined component technology, including custom components, are captured.

•

Basic Detail — Instruments at a basic level. Only request metrics for HTTP, JMS, and RMI request are collected. No other component or full detail methods are captured.

•

No Detail — Turns off instrumentation that is not essential for running an agent. As a result, no request metrics are collected, and single traces call trees cannot be captured.


	NOTE: As a result of setting instrumentation to this level, no data is displayed in the Application Servers Monitor > Requests tab.

Click Save.

Restart your application server.

Manual configuration — InstrumentationLevel

If you manually edit the instrumentation.config file, use the following syntax to set the instrumentation level:

Table 5. Instrument level syntax.
Level	Syntax
FullDetail	InstrumentationLevel = "FullDetail";
ComponentDetail	InstrumentationLevel = "ComponentDetail";
BasicDetail	InstrumentationLevel = "BasicDetail";
NoDetail	InstrumentationLevel = "NoDetail";

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 .

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

beside InstrumentedSimpleMethods.

In the Settings Editor dialog box, click

Add.

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

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.

Click OK.

Click Save.

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 .

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 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.

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 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 .

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 several 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",