Custom Match Rules

A custom match rule is a type of transaction detection rule that enables you to define criteria for business transaction discovery, and naming for an entry point type.

There are two types of custom match rules:

• A custom include rule defines an entry point to use in a new transaction.
• A custom exclude rule lets you prevent AppDynamics from detecting business transactions you are not interested in tracking. For example, application framework services, administrative console requests, or heartbeat pings, and so on.

Use Live Preview to experiment with certain custom match rule configurations and identify potential business transaction entry points:

• During a Business Transaction Discovery Session, you can use the Classes/Methods browser or Uninstrumented Code to create POJO and POCO custom match rules.
• When you create or edit a POJO or Servlet entry point, you can use Live Preview for the individual rule you are creating.

Transaction Naming

When an app agent detects a request that matches a custom include rule, it names the business transaction based on the rule name. You can further refine the transaction name using transaction splitting for URI based rules, for POJOs, or for POCOs.

If a request matches more than one custom include rule, it applies the rule with the highest number priority. See Transaction Detection Rules.

Create a Custom Match Rule

1. Navigate to Configuration > Instrumentation and select the Transaction Detection subtab.

2. Select the Rules subtab.

   

   You can also add a rule within a specific scope on the Transaction Detection tab.

3. Select Add to open the Add Rule page with Custom Match Rule selected.

4. Select the Agent Type and the Entry Point Type and select Next.
5. On the Summary tab, make general rule configurations:
   • If you are creating a custom match exclude rule, click Exclude Transactions discovered by this rule. 

   • Enter the rule Name. The app agent names requests that match the rule for the rule name.

     

     To avoid errors, do not include these special characters in the rule name: less than sign (<) and greater than sign (>).

   • Optionally disable the rule, set the rule Priority and assign the rule to a Scope.
     For information on rule priorities, see Transaction Detection Rules.
     For information on scopes, see Scope Configuration Model.

6. On the Rule Configuration tab, configure the match criteria based upon the entry point type. The PHP web choices, for example, let you specify HTTP-oriented match criteria, such as those for HTTP method, URI, and query parameters.

   

   Servlet and POJO entry point types feature a Live Preview button to launch custom match rule live preview session. A live preview streams data from an active node so you can interactively experiment with rule configuration in the Add Rule window.

Custom Match Include Rule Example

This example shows a custom match include rule named cart.GET in a scope named MyCustomScope.

The "cart.GET" rule generates business transactions for Web Service GET requests where the URI begins with /cart/ followed by a number. AppDynamics names the resulting business transaction cart.GET:

You can add conditions to the rule to match based on specific HTTP parameters or hostnames.

For certain HTTP-based request types, such as Servlets or ASP.NET, a match rule can have more than one HTTP Parameter match condition. A request must match all HTTP Parameter conditions to match this rule. There is an implicit AND operator between the parameters rather than an OR operator.

You can use more complex regular expression matching. For example, the following request URLs: 

• example.com/aaa123.aspx
• example.com/b1.aspx

To match any incoming request URL to this business transaction, use:

example\.com/[a-zA-Z]]+?[0-9]+?

Any request to a URL that includes example.com followed by uppercase or lowercase letters and numbers would match this business transaction detection rule. A URL that has no digits after the letters, such as example.com/z.aspx does not match. 

See Using Regular Expressions for more information on using regular expressions in the UI.  

Transaction Splitting for URI Based Entry Points

You can configure business transaction splitting for these types of URI based entry points:

• Java Servlet
• ASP.NET
• PHP Web
• Node.js Web
• Python Web
• Web Server

When you enable transaction splitting, the agent resolves a subset of requests that match the custom include rule into a separate business transaction based on a dynamic part of a request. The app agent names the transaction:

<custom match rule name>.<name derived from the split configuration>.

Consider an application with incoming requests:

• http://nwtrader.com/checkout?category=electronics 
  

• http://nwtrader.com/checkout?category=clothing 

This example shows how to configure transaction splitting to resolve two requests into two different business transactions, named:

• Checkout.electronics
• Checkout.clothing

You can split servlet transactions based upon the payload. See Split Servlet Transaction by Payload Examples.

Default Custom Exclude Rules

AppDynamics includes default exclude rules for the entry points for frameworks that are not usually of interest. Navigate to Configuration > Instrumentation > Transaction Detection > Rules and filter on Rule Type: Custom Exclude to view or modify the default custom match exclude rules. See Custom Exclude Rule Examples.

To configure exclude rules for Service Endpoints, see Service Endpoints.