Custom Instrumentation using Java Annotations 

Using Java annotations, APM Insight provides an easier way to custom instrument your application classes and methods. Usage of Java annotation enables you to define custom names for the transaction and also assign a custom component.

Prerequisites

• Download the apminsight-javaagent.zip file which includes agent jar with its associated files along with the apminsight-javaagent-api.jar
• Include the apminsight-javaagent-api.jar file to the project build path. Make sure the jar file is exported along with the application's libraries.
• Java agent API library provides two annotations which can be used in your application to track the performance of your custom classes and methods.
  • ApmTracker - Can be used upon any classes and methods, which will be instrumented and included in the traces.
  • ApmRootTracker - Can be used upon the methods which are likely to be starting point of transaction execution (background).

ApmTracker

This annotation can be used on Classes and Methods. When used upon a class, the attributes are applied for all the methods in that class. It will override the method-wise annotations.

Attributes:

• component - Optional attribute

  Defines the custom component for annotated classes/methods.

  Example:

  Case 1: Usage on Class
@ApmTracker
public class Category {
    ...
}

Case 2:
@ApmTracker(component="payment"
public class PaymentProcessor {
    ...
}

Case 3: Usage on Methods
public class Product {
    @ApmTracker
    public int getPrice(String product, String brand) {
        ...
    }
    ...
    @ApmTracker(component="FetchBrand")
    private List fetchAllBrandsList(String product) {
        ...
    }
}

• name - Optional attribute

  A custom name for the annotated element, which will be prepended to actual method name. Method parameters can be used for custom name by mentioning the argument index (starts at 1) with prefix '$'.

  The instrumented methods and its custom names can be viewed under Traces.

ApmRootTracker

This annotation can be used only on methods. If annotated method is the first method invoked on the server for processing the transaction, then the transaction is re-named using the value of the txnName attribute. Else, it is considered to be a normal method call and included in the traces.

Attributes:

• component - Optional attribute

  Defines the custom component for annotated methods.

• name - Optional attribute

  A custom name for the annotated element, which will be prepended to actual method name. Method parameters can be used for custom name by mentioning the argument index (starts at 1) with prefix '$'.

• txnName - Mandatory attribute

  Defines the name for the background transaction, only if the method is the entry point of the transaction else it will be tracked as generic method and added to the traces.

  The transaction is named according to the value specified for the attribute txnName.