Foglight for Java EE Technologies 5.9.12 - Installation Guide

Changing the instrumentation level for Request Metric data collection

The Java EE agent uses instrumentation for request monitoring and to collect single traces. This instrumentation does add some overhead to your monitored servers and the information collected indirectly applies load to the Foglight Management Server. However, if you only require single traces collected at component level, or you do not require request monitoring at all, you can reduce or turn off instrumentation using the Instrumentation Level setting. This reduces the overhead on your monitored servers and the load on the Foglight Management Server.

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 .

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

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

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

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.

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.

If you manually edit the instrumentation.config file, use the following syntax to enable simple method instrumentation:

To explicitly name methods to be instrumented, even if they are detected as simple methods:

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 .

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.

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.

TIP: For more information about regular expressions, see the Appendix: Regular Expressions in the Foglight for Application Servers User Guide.

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

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

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.

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.

a	Click Add component.

Click Add to add a single method at a time.

Click Add multiple to open a text box where you can type several methods.

If you manually edit the instrumentation.config file, use the following syntax to specify 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. In the example below, you can uncomment and add package listings if necessary.