Sensor rules migration

Before switching the Agent Platform to the AppMon Agent, you have to make sure that all of your Java and .NET Sensor Rules are supported. The majority of Sensor Rules can be used on both Classic and AppMon Agent platforms without any modification. However some rules may need manual migration before you can switch the Agent Platform from Classic to AppMon Agent. These are rules containing regular expressions and super methods inheritance.

Check for unsupported rules

In the Sensors item of the System Profile Preferences dialog box, click the tab of the required Agent Group, and then click Migrate Rules. If there are any incompatibilities, the Manage Migration of Sensor Rules dialog box will show them. Find the evaluation code in the table below to learn about possible alternatives.

Migrate sensor rules
Errors of sensor rules migration

Regular expression

Some regular expressions constructs are not supported on the AppMon Agent platform. There are also some complexity restrictions for the regular expressions. Before switching to the AppMon Agent platform you have to either alternate unsupported constructs or remove Sensor Rules containing them.

Regular expression usage

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

AppMon 2018 April

Regular expressions are not allowed in AppMon 2018 April. Existing rules, however, still work. If you need to reuse them, you can copy-and-paste an existing rule with regular expression.

Unsupported features

The following table lists all constructs, supported on Classic Agents but not supported on AppMon Agents.

Evaluation code Construct Alternatives
u1 Possessive quantifiers. Independent, non-capturing groups.

(*+, ++, ?+), (?>X).
Use greedy quantifiers and simple capturing groups.

Semantic is slightly different. In case of possessive quantifiers and non-capturing groups, once a character has been matched, it remains in possession of the quantifier, even if this prevents other parts of the expression from matching. It doesn't apply to greedy quantifiers and capturing groups.

Examples:
A* instead of A*+
A+ instead of A++
A? instead of A?+
(A) instead of (?>X)
u2 Unicode scripts, blocks, categories and binary properties with \\p and \\P, including POSIX character classes and java.lang.Character classes.

\p{ASCII}, \p{Alpha}, \p{Digit}, etc.
For some categories you can use character classes.

Examples:
[\x00-\x7F] instead of \p{ASCII}
[0-9] instead of \p{Digit}
u3 Back references.

\1, \2
No alternatives.
u4 Octal escape sequences.

\0n, \0nn, \0mnn
Use equivalent hexadecimal notation (\uhhhh) instead.

Example:
\u000B instead of \013
u5 Beginning of the input; an alternative to ^ .

\A
Use ^ instead.
u6 End of the input and the end of the input but for the final terminator, if any.

\z, \Z
Use $ where applicable.
u7 The end of the previous match \G. No alternatives.
u8 Horizontal white space \h.

No horizontal white space \H.
Use the following alternative for horizontal white space:
[\t\u0020\u00A0\u1680\u2000\u2001\u2002\u2003\u2004\
u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000]

Use the following alternative for no horizontal white space:
[^\t\u0020\u00A0\u1680\u2000\u2001\u2002\u2003\u2004\
u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000]
u9 Any Unicode line break sequence \R. Use the following alternative:
(\u000D\u000A|[\u000A\u000B\u000C\u000D\u0085\u2028\u2029])
u10 A non vertical white space \V. Use the following alternative:
[^\u000B\n\r\u0085\u2028\u2029]
u11 Named capturing groups and references.

(?&<name>), (\k<name>)
No alternatives.
u12 Inlined match flags.

(?xxx:)
Case-insensitive matching: duplicate your sensor rule and use all possible combinations of capital and small letters.
u13 Character class (Intersection)

[a-z&&[aeiou]]
Specify intersection of character set in a single character class.

Example:
[aeiou] instead of [a-z&&[aeiou]]
u14 Character class (Union)

[a-d[m-p]]
Use an alternation of multiple character classes.

Example:
([a-d]|[m-p]) instead of [a-d[m-p]]
u15 Quotation sequences. Nothing, but quotes all characters between \Q and \E. Quote every single special character between \Q and \E with \ instead.

Special characters are:
<([{\^-=$!|]})?*+.>
u16 Zero-width positive lookbehind match a string that is preceded by X.

(?<=X)
This construct allows to search for sub strings within a longer string. This is not applicable for sensor rules. A sensor rule either matches a complete method/class/package name or not.

If you have a regular expression with this construct the corresponding sensor rule doesn't work.
u17 Zero-width negative lookbehind match a string that is not preceded by X.

(?<!X)
This construct allows to search for sub strings within a longer string. This is not applicable for sensor rules. A sensor rule either matches a complete method/class/package name or not.

If you have a regular expression with this construct the corresponding sensor rule doesn't work.
u18 Exact quantifiers with zeros only.

{0,0}, x{0}
Although the syntax itself allows quantifiers with zeros only, such constructs are always ignored, and sensor rule doesn't work. If you have a regular expression with zeroes only construct, you can remove the quantified group, character or character class.

You can't use quantifiers with zeros only to get the does not contain X behavior. Negative lookaheads may be an a good alternative in this case.

Complexity restrictions

To minimize overhead Java and .NET Agents on AppMon Agent platform have additional restrictions on the complexity of regular expressions in Sensor Rules. Regular expression with one of the following properties or combinations of constructs are not supported on AppMon Agent platform.

Evaluation code Restriction rule Description
c1 A quantified groups containing another quantified tokens. Greedy quantifiers ( *,+ and {m,n}) within a group are not allowed if the group itself already has a greedy quantifier. This combination can cause an explosion of the matching time, especially when a long string does not match.

Groups within an independent group are ignored.

Examples of not allowed expressions:
(A+)*
^(.*?,){11}P
(?:\\D+|0(?!1))*
(.*a){11}
c2 More than two consecutive quantified but not mutually exclusive tokens. You can use a maximum of two contiguous quantified non-mutually exclusive tokens. More can easily lead to an explosion of matching time, especially with long strings that do not match.

Examples:
.*.* (allowed)
\d+\d*\d+ (not allowed)
c3 More than two levels of nested groups. You can use a maximum of two levels of nested groups. More can easily lead to an explosion of matching time, especially with long strings that do not match.

Examples:
(a(b(c)))(allowed)
a(b(c(d(e))) (not allowed)
c4 Expression with more than 10,000 characters. Reduce the length of your regular expression by removing redundancy or split the expression to multiple sensor rules.

Super methods inheritance

Java and .NET Agents on AppMon Agent platform don't support Method Rules with super methods inheritance. These rules instrument matching methods from classes of their parent Class Rule, and also from super classes of the parent Class Rule.

See the workaround below to migrate such rules to the AppMon Agent platform.

1. Verify the need of the rule

At first make sure that you still really need the rule with the super methods inheritance. You can remove the rule completely in following cases:

  • The rule only matches native methods. It is technically impossible to instrument native methods.
  • The referenced class or method name does not exist anymore.
  • The rule is inactive and is not intended for later use.

2. Create semantically equal rules

If you still need the rule with the super methods inheritance, you have to create a separate Class Rule for each super class of the original rule, and add a Method Rule to instrument the required method in each of those Class Rules.

  1. In the original method rule, change the Inheritance to this method.
  2. Look for the class from the original Class Rule in the Class Browser.
    The Super Classes column displays all the super classes of it.
  3. In the Class Browser, look for the super class you discovered in the previous step.
  4. Select the class and the method you want to instrument, and click OK.
  5. Double click the newly created Method Rule, and set the inheritance as this method.
  6. Repeat steps from 3 to 5 for all super classes of the original Class Rule.