Method Sensor Rules

Method Rules define one or more methods and how they should be instrumented. A Method Rule is always a child of a Class Rule, and instruments only methods from classes/interfaces, defined by the parent Class Rule.

Since Method Rules are defined within a Sensor Group, they inherit technology type (Java or .NET) from the group.

Method Rule Properties
Method Rule Properties

Configure a Method Rule in the Method Rule Properties dialog box:

  • While creating a new Method Rule:
    1. Open the System Profile Preferences dialog box, and select the Sensor item.
    2. Select the required Sensor Group.
    3. Select the required Class Rule, or create a new one and then select it. See Class Rule to learn how.
    4. Click Add Method.
  • While editing an existing Method Rule:
    1. Open the System Profile Preferences dialog box, and select the Sensor item.
    2. Select the required Sensor Group.
    3. Expand a Class Rule, select the required method, and then click Edit.

You can also add Method Rules by using the Class Browser. In that case, you don't have to create Class Rules first, as they will added automatically.

Method pattern

Method Rules do not necessarily specify concrete names of methods. Instead they use patterns. These patterns can be specified using one of the following modes:

  • equals: The pattern applies if the actual name is equal to the pattern text.
  • starts: The pattern applies if the actual name starts with the given pattern text.
  • ends: The pattern applies if the actual name ends with the given pattern text.
  • contains: The pattern applies if the actual name contains the given pattern text.
  • regex: Allows regular expressions. For example, MethodName[0-9]+ specifies all methods that start with MethodName followed by any number.
Notes

Use a regular expression only when necessary because of its impact on the CPU. A starts may be good enough if the methods are named efficiently.

A Method Rule with an empty pattern affects all methods.

Constructors are excluded by default.

General

Place: The placement state of a Method Rule can be one of the following:

  • include: Methods affected by this rule should be instrumented using the given Sensor type.
  • exclude: Methods affected by this rule should not get instrumented.
  • inactive: This rule is inactive.
  • globalexclude: Methods affected by this rule should not get instrumented and even include rules in Custom Sensor Packs are overwritten.
Note

Be careful when use globalexclude, because this rule can even override include rules defined in Custom Sensor Packs. The impact of such a rule is not limited to the containing Sensor.

Type: Defines the type of method that should be instrumented, which can be a method (static or instance), a constructor, or a static constructor.

Pattern: The string pattern used to match names of actual methods. See the Patten section above.

Visibility: Defines the visibility of methods that get instrumented (public, default, protected, private).
Inheritance: When you use this option, you can instrument methods of a specified class and methods of super- or sub-classes. The following modes are available:

  • this method: Only methods are instrumented where the containing class matches the corresponding Class Rule.
  • inherited methods: All methods are instrumented where the containing class matches the corresponding Class Rule or the containing class extends a class or implements an interface that matches the corresponding Class Rule.
    For example, by declaring the method toString() of java.lang.Object to be instrumented with inherited methods, the method toString() of every class gets instrumented.
  • super methods: All methods are instrumented where the containing class matches the corresponding Class Rule or the containing class is a super class to a class that matches the corresponding Class Rule.
    For example, by declaring the method equals() of java.lang.String to be instrumented with super methods, the method equals() of java.lang.Object also is instrumented.
  • automatic: If the pattern of the corresponding Class Rule is an interface, the mode inherited methods are used, otherwise this method option is applied.
Note

At run time, the complete inheritance hierarchy of a diagnosed system may not be known, especially when a system is diagnosed for the first time, Method Rules using inherited methods, super methods or automatic may not be correctly applied.

That's the reason why the Discovery Run is required. After the Discovery Run AppMon Collector remembers the inheritance hierarchy of introspected applications. Restart the System under Diagnosis to solve the problem.

Arguments Rules: Specify Argument Rules to limit the matching methods to those with the specified argument types. Additionally, you can specify which arguments to capture every time matching methods are called and shown in the PurePath.

Accessor: Deep object access is an extension of Java/.NET method argument or return value capturing. To use deep object access on an argument or the return value of a method, enter an accessor string in the corresponding text field. For arguments, this is the field in the accessor column in the Arguments Rules table. For the return value, there is a dedicated text field.

Additional Accessor Details

  • You can specify the accessor with or without a leading dot. Both expressions are valid and equivalent.
  • The value accessor failed returns if the accessor fails because the specified method was not found or the method threw an exception.
  • If any object in the chain of access method calls has a value of null, the access result is null.
  • When specifying an accessor, consider potential side-effects, performance impact, and resource consumption that calling the accessor methods may have on your application.

Limitations

  • Only one accessor can be defined per argument or return value.
  • The methods that the accessor is composed of cannot have any parameters.
  • If the argument or return value is an array, deep object access is not possible.
  • AppMon does not check whether the specified accessor is a valid method.

Java Annotations or .NET Attributes: Java Annotations or .NET Attributes can also be specified, which results in instrumenting those methods that have these Annotations or Attributes applied. Additionally, you can also specify to only instrument this method if one of the Properties has a certain value.

The following example shows a rule that instruments those .NET Methods that have the ToInstrument .NET Attribute specified.

Options

Capture Events: Toggle the capturing state of methods instrumented due to this rule. If event capturing is disabled, the Sensors placed due to this rule are disabled. You can change the capturing during runtime.

Allow to start PurePaths from this method (Entry Point): Allows calls to methods that match this rule start a new PurePath, if the call is not part of an already started PurePath.

This method rule denots an External API Service call: Mark invocations of this method as External API Service calls.

Optionally you can specify service and instance name for this External API Service call. The instance name will fall back to the method name. It is possible to specify patterns of the form '{X}', where X is the Xth captured argument. Note, that 0 being reserved for the return value. Special placeholders '{method}' and '{service}' will evaluate to method name or service name, respectively.

Method return values are recorded: Records and shows the return value in the corresponding PurePath every time a matching method is called.

Rule execution order

  • Sensors are evaluated from the first to the last in their order.
  • For every Sensor, these steps are applied:
    • All Sensor Rules are evaluated top down.
    • The first matching Sensor Rule is applied, whether it is an inclusion or an exclusion.
    • After the first match in a Sensor, the evaluation for this Sensor is stopped.
  • Any global excludes override any includes in all Sensors.

Automatic Method Sensor Rules management

When you create a Method Measure, a method is selected using the class browser. By default, the Method Measure is configured to match exactly on that method. In this case, AppMon manages the Method Sensor Rule automatically throughout the lifetime of the Method Measure. You don't have to configure any Method Sensor Rule.

When a new Method Sensor Rule is created implicitly, Hot Sensor Placement is performed under the following conditions:

  • The user has the permission to perform Hot Sensor Placement.
  • The license is not a Production Edition license.
  • The Method Measure is a Java method.

When Hot Sensor Placement can't be performed, restart the Application Process to make the new Method Sensor Rule effective.

Explicit Method Sensor Rule for custom matching pattern required

When the matching pattern of the Method Rule is configured manually by selecting the Manually specify matching pattern check box, no Method Sensor Rule is created for this Method Measure. For the Method Measure to work, you must configure a Method Sensor Rule.

Placement, capture, and argument rules summary

In the Sensors item of the System Profile Preferences dialog box you decide for which classes or methods Sensors are instrumented. On the next levels you decide for which method and (how many) its arguments data are available.

The following is the hierarchy for Sensors on the System Profile level:

  • If Place is checked for a class, it is instrumented and data can be captured.
    • If Include is set on the method's Place column, it is instrumented and data can be captured.
    • If Inactive is set on the method's Place column, the Rule is inactive. If the method appears again lower in priority, then that rule applies. This allows you to test different scenarios.
      • If Active is set on the method's Capture column, data is captured for this method. (Active and start PurePaths ‐ additional variant as the name implies).
      • If Inactive is set on the method's Capture column, data is not captured for this method, but it's much easier to switch from Inactive to Active than from Not Placed (Not Instrumented) to Placed (Instrumented - byte-code injected). (In Java 1.5+ you alternatively can do Hot Sensor Placement, but that´s much harder on the system than Activate.)
        • If you choose Method with any Argument in the Method Rule dialog box, data for this method ‐ with any signature ‐ is captured.
        • If you choose Specify Method by Arguments in the Method Rule dialog box, data for selected arguments of this method ‐ with exactly that signature ‐ is captured.
          • If Capture is checked for an argument, data of this argument is captured.

In an Agent Group of the System Profile Preferences dialog box you decide which Sensor Packs are instrumented. On the next levels you decide for which method arguments data is captured.

The following is the hierarchy for Sensor Placement and Sensor Configuration on the Agent Group (Tier) level:

  • If Place is checked for a Sensor Pack in the Sensor Placement table it is instrumented and data can be captured. A golden star signifies that it is Hot Placeable.
    • If Active is set for a Sensor Pack's Capture column, data is captured for this Pack. (Active and start PurePaths ‐ additional variant as the name implies).
    • If Inactive is set for a Sensor Pack's Capture column, data is not captured for this Pack, but it is easier to switch from Inactive to Active, than from Not Placed (Not Instrumented) to Placed (Instrumented - byte-code injected). (In Java 1.5+ you can do Hot Sensor Placement, but that's much harder on the system than Activate.)
      • In the Options column you can set Properties for many Packs to better control which data is captured.

There can be more than one System Profile Configuration. A tab is created for each Sensor Configuration item in each Agent Group (Tier). See the screenshots below.