Sensor Rules: Define the classes and methods that should be instrumented. Sensor Rules can be either:
- Method Sensor Rules: These rules relate to the Java/.NET Method Sensor, and collect PurePath method related information.
- Memory Sensor Rules: These rules relate to the Java/.NET Memory Sensor, and collect PurePath object allocation information and Selective Memory Dumps.
- Sensors: Each Sensor consists of a set of Sensor Rules. Sensors are divided into the following:
- Sensor Groups: Sensors stored and available only in a specific System Profile.
- Sensor Packs: Sensors deployed on an AppMon Server and available in all System Profiles on this AppMon Server. Sensor Packs are created and maintained by AppMon users.
- Knowledge Sensor Packs: Sensor Packs created and maintained by AppMon or by the Dynatrace Community.
By default, AppMon places Knowledge Sensor Packs on all important component interfaces.
Use Method Sensor Rules to diagnose performance issues deeper in the application at the package/namespace, class or method levels.
AppMon provides a Discovery Run to discover what packages/namespaces, classes and methods are available to instrument. It locates all packages/namespaces of the application. The Method Sensor Rule configuration is used to gather information about specific packages/namespaces, classes and methods. Additionally, AppMon Method Sensor Rules capture specific method arguments and return values which are very useful in diagnosing issues.
System Profile Preferences > Sensors
Single Method Sensor Rules can be specified and grouped into a Sensor Group. Method Sensor Rules which are added to a Sensor Group are prioritized by their order. As traffic passes through the Sensor Group the rule that matches first is the first and only one applied to that traffic. Method Sensor Rules priority can be specified, also method rules within a class rule can be prioritized.
If a PurePath is not started automatically by a built-in sensor, the Entrypoint for recording the PurePath must be specified by setting the Capture setting to active and start PurePaths.
A Sensor Pack can be generated out of one or more Class Rules or Method Rules with the Create Sensor Pack context menu option. The new Sensor Packs listed within the Sensor Packs dialog box in the AppMon Server preferences and is available for all Agent Groups in all System Profiles.
The Class Browser provides a convenient way to define Class Rules and Method Rules. See Class Browser for more information.
Sensor Groups are available in the Sensor Placement and Sensor Configuration dialog boxes for all Agent Groups within the System Profile. Modify Sensor Groups using these dialog boxes in the same way as you would modify predefined Sensor Packs.
Each new System Profile is created with two default Sensor Groups per technology type.
- Default Method Sensor Group
- One default Memory Sensor Group.
See System Profile - Sensors for more information on handling Sensor Groups.
Group Sensor Rules logically into corresponding Sensor Groups for better maintainability.
Add only packages/namespaces, classes or methods which are really critical in terms of performance to a Sensor Group. Avoid processing too much non-essential information.
A Class Rule defines the container for a number of Method Rules. These Method Rules are evaluated with respect to the Class Rule they are defined within. A Class Rule with an empty pattern affects all classes. A Class Rule whose selection pattern ends with a dot is a package/namespace rule. It matches all classes within the specified package/namespace. The run time technology (Java or .NET) of a Class Rule is defined by add either a Java or a .NET Sensor Group.
System Profile Preferences > Sensors > select class > Edit. Double-click or select Add Class.
Class and Method Rules do not necessarily specify concrete names of classes/methods. Instead they use patterns which are evaluated when the names of the current class and method are available. 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,
ClassName[0-9]+specifies all classes that start with
ClassNamefollowed by any number.
Use a regular expression only when necessary, because it’s “costly” on the CPU. Above a
starts may be good enough if the classes are named efficiently.
Empty Class Rules that result in
<all classes> are ignored by the instrumentation engine due to possible performance penalties.
Specify Class Pattern: Class Rules are specified by patterns that reflect the fully qualified class name and can also define interfaces or packages/namespaces.
Specify Classes by Annotations/.NET Attributes: You can use Java Annotations/.NET Attributes as selection criteria for classes. You can specify one or more Annotations/.NET Attributes per Class Rule.
An Annotation/.NET Attribute specification consists of a mandatory type, which defines the full package/namespace name of the Annotation/.NET Attributes, an optional property, and a value.
A specified Property with an omitted value results in only the Property being is evaluated. If both Property and Value are specified, the actual Values of Annotation/.NET Attribute Properties are compared with the specified Property Values. The specified Annotations/.NET Attributes are conjugated. For example, a Class must provide all Annotations/.NET Attributes specified by a Class Rule to match said Rule.
Switch Evaluation of Annotations/.NET Attributes on and off with the Specify Classes by Annotations/Attributes check box. To define a Class Rule that is based only on Annotations/.NET Attributes, leave the Class Pattern blank and switch the comparison mode to “starts”.
Pattern declares a package: This check box determines if the Class Rule matches single classes or a whole package/namespace. A Class Rule defined for a package/namespace matches all Classes in the package/namespace.
If you specify a package/namespace with mode equals, only classes contained in that package/namespace are processed, sub-packages are ignored.
Place: Enable or disable a Class Rule. Delegation Suppression: When Delegation Suppression is turned on, the Method Rules contained in that Class Rule are combined to one logical group. Each time one method matching one of these rules calls another method matching these rules, only the first call is shown in the corresponding PurePath. A method such as method read() should be instrumented in one specific class and all of its super-classes (this could be done by using inheritance modes, described below) and this method makes a call to the method read() of its super-classes. As a result, there would be a chain of read() method calls in the PurePath.
To get a clearer PurePath, one could use Delegation Suppression to make all the following calls to read() disappear in the PurePath.
System Profile Preferences > Sensors > select method > Edit. Double-click or select > Add Method.
Method Rules define one or more methods and how they should be instrumented. A Method Rule with an empty pattern affects all methods.
Constructors are excluded by default.
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.
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
java.lang.Objectto 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
java.lang.Stringto be instrumented with super methods, the method
java.lang.Objectalso is instrumented.
- automatic: If the pattern of the corresponding Class Rule is an interface, the mode inherited methods is used, otherwise this method is applied.
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. In this case, restart the System under Diagnosis to solve the problem because the AppMon Collector remembers the inheritance hierarchy of introspected applications.
- You can specify Method Rules in a Class Rule, although no methods that match these Method Rules are contained in a matching class. For example, you can create a Method Rule with pattern
substring()for a Class Rule with pattern
java.lang.Object. This does not seem to make sense, but when you use this Method Rule in mode “inherited methods”, the method
java.lang.Stringis instrumented, because
- If the inheritance mode “inherited methods” is combined with a pattern matching multiple methods or a blank pattern to select all methods, then the pattern applies to the inheriting classes’ methods. For example, a Method Rule with a blank method pattern, selecting all methods, for the class
java.lang.Object, and the inheritance mode set to inherited methods instruments all methods of classes inheriting from
java.lang.Object, not just the subset of methods inherited from
- Use the mode inherited methods or super methods, so that the methods of the matching class are always included. If the methods of the matching class should be excluded from instrumentation, you must prepend a Method Rule that excludes the methods from the specified class in the this method mode.
Arguments: 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 method arguments table. For the return value, there is a dedicated text field.
Suppose there are some business transaction methods to be grouped by customer. The methods have signatures like
addToCart(SessionState s, Item newItem). Customer information is in a
Customer object inside the
SessionState object. Using only method argument capturing without deep object access, you can capture the
SessionState, but not the
Customer inside it. Deep object access can define an accessor that specifies how to reach an object deep inside, and capture that object. In this example, a suitable accessor might be
getCustomer().getId(). If this accessor is defined for the
SessionState s argument, it is not
s that is captured, but
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.
- 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/.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.
Place: The current 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 currently inactive.
- globalexclude: Methods affected by this rule should not get instrumented and even include rules in custom Knowledge Sensor Packs are overwritten.
executePlugins() methods are instrumented, because the second, lower priority occurrence in the package is evaluated by the instrumentation engine and the Rule says Include.
Be careful when use
globalexclude, because this rule can even override
include rules defined in custom Knowledge Sensor Packs. The impact of such a rule is not limited to the containing Sensor.
globalexclude does and does not impact:
Anybody can create Sensor Packs that are installed on the AppMon Server to share it across System Profiles. An example is the Knowledge Sensor Pack for SharePoint that you can download on the Community Portal. If you use that Sensor Pack, a global exclusion rule would impact it. However, global exclusion rules do not impact the core functionality of out-of-the-box Sensor Packs.
You can’t change out-of-the-box Sensor Packs such as ADO.NET by specifying your own custom exclusion rules. These Sensor Packs instrument certain methods, such as
getConnection to get a connection string.
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.
Method return values will be recorded: Records and shows the return value in the corresponding PurePath every time a matching method is called.
Automatic method sensor rules management
When you create a Method Measure, a method is selected via 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 current user has the permission to perform Hot Sensor Placement.
- The current 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.
Rule execution order
To create adequate Sensor Groups, it is important to understand the way AppMon evaluates these rules:
- 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.
Placement, capture, and argument rules summary
In System Profile <profile_name> > Sensors 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 System Profile <profile_name> > Agent Group <name> you decide which Sensor Packs are instrumented. On the next levels you decide for which method, arguments data will be 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.
Memory sensor rules
Use AppMon to monitor instantiations of specific classes and deserialization events of instances of specific classes. The classes that are included in Memory Monitoring are selected by Memory Sensor Rules. Memory Sensor Rules are configured similar to Class Rules. The Select Memory dashlet displays the Memory Monitoring data of the selected classes. See Class Rules for more information.
Use the class browser to define Memory Sensor Rules in the same way as Class Rules.
Memory sensor rules
You can specify Memory Sensor Rules for a class or a package/namespace similar to Class Rules, with patterns and Java Annotations as described in Method Sensor Rules. You can active or deactivate the Sensors associated to a Memory Sensor Rule at runtime by toggling the Activated check box of the Memory Rule. If you enable the Include Inherited Classes check box, memory monitoring Sensors are placed in classes that match the selection pattern of the rule and in all direct or indirect base classes of that class.