External API services

You can specify any Java / .NET / PHP method as an invocation of an external API service.

Configuration in Method Rule dialog box

To configure a method as an external API service call, you first need a method rule for that method. The configuration is done directly in System Profile Preferences > Sensors > Add / Edit Method Rule dialog box. Just select the This method rule denotes an External API Service call check box at the bottom and all subsequent method invocations matching this method rule is marked as external API service calls.

External API service calls can have optional service and instance names that are also configurable in the method rule configuration dialog box:

  • The service name is a user-chosen identifier string that becomes the caption of all collected calls in the transaction flow.
  • The instance name is also a user-chosen identifier string, but with some special features. It can be filled with captured arguments and return values, the method name and the service name.

Instance name syntax

This addresses use-cases where a call is made to some service and a username, a service name, or virtually anything of interest is passed as a method argument. To enable this feature, the user has to enable argument capturing for all arguments of interest, and/or return value capturing, if the return value is of interest, respectively.

In the instance name pattern string, each argument can be referred to with placeholders of the syntax {1}, {2} where the index inside braces is the 1-based argument index, {0} (zero) being reserved for the method return value.

The instance name, if not provided, falls back to the method name. Furthermore, special placeholders {method} and {service} evaluates to the method name and service name, respectively. It's possible to quote strings in single quotes, then they are not be evaluated with the logic described here.

The method rule configuration dialog box issues a warning, if an argument referred to by the pattern has capturing not enabled. It issues an error (and thus prevent the user from closing the dialog box), if the pattern has a syntax error (unclosed braces or quotations) or refers to non-existing arguments.

Screenshot 1: Method Rule configuration dialog box
Screenshot 1: Method Rule configuration dialog box

Business Transactions

To collect data of external API service calls, a method metric called External API Service Pattern Value is available for use as splitting and result measure for business transactions. It evaluates to the formatted pattern value of all calls that match the signature of the metric.

Screenshot 2: external API service pattern value method metric for Business Transactions
Screenshot 2: external API service pattern value method metric for Business Transactions

It's possible to configure business transactions that split per formatted pattern value of external API service calls, however, to have correct counts such as method invocation counts and times such as method execution duration, the business transaction must be carefully configured as follows:

  • If both Count and Time are of interest, the user has to create one BT for each respectively.
  • The Count business transaction must have its Calculate Results aggregate set to Count (see screenshot 3).
  • The Time business transaction must have it's Calculate Results aggregate set to Sum (see screenshot 4).
  • Both business transactions must use the same measure (created from subscribing the External API Service Pattern Value metric) as Calculate Results and Splitting measure. This must be the same measure instance per reference. Do not create it twice.
  • The underlying External API Service Pattern Value measure must be configured to have its Grouping Measurement set to Exec Time (see in screenshot 5).

The following screenshots show business transaction results split per pattern value and have method execution time and count series, respectively.

Screenshot 6: Business Transaction with Method Execution - Count series
Screenshot 6: Business Transaction with Method Execution - Count series
Screenshot 7: Business Transaction with Method Execution - Time series
Screenshot 7: Business Transaction with Method Execution - Time series

PurePath dashlet

In the PurePath dashlet, all external API service calls are marked with a special icon that looks the same as generic external services in transaction flow. Furthermore, the details dialog box shows the configured service and instance name, as well as the formatted instance name, with all placeholders replaced, as shown in transaction flow.

Screenshot 8: PurePath view of external API service calls
Screenshot 8: PurePath view of external API service calls

The easiest way to configure a business transaction for a specific method is to select the method node in PurePath dashlet, open the context menu and select New Business Transaction. This creates a business transaction for a method rule that is also newly created for the selected method node.

Transaction Flow

If an application contains external API service calls, those are shown as external service calls in the transaction flow as usual. The tier groups are named after the service name (falling back to external API service if not specified in the method rule). The individual tiers (nodes) are named after the corresponding formatted instance names (falling back to the method names if not specified in the method rule).
The transaction flow does not allow to expand groups that contain 100+ nodes to avoid unreadable dashboards. This can easily happen if a captured argument is simply an increasing number. The instance name pattern (especially the contributing arguments) must be chosen with care.

Screenshot 9: Transaction Flow view of external API service calls
Screenshot 9: Transaction Flow view of external API service calls

Leaf nodes

Only leaf nodes can be marked as external API service calls. So if a rule applies to a non-leaf node (node with child nodes), that node is not marked as such. However, if the child nodes are exception, allocation or logging nodes, this rule does not apply.