AppDynamics switched from Semantic Versioning to Calendar Versioning starting in February 2020 for some agents and March 2020 for the entire product suite.


    Skip to end of metadata
    Go to start of metadata

    Related Pages

    Your Rating:
    Results:
    1 Star2 Star3 Star4 Star5 Star
    8 rates

    This section provides examples that describe how common use cases for the Agent API can be implemented.  For reference information, see the javadoc at https://sdkdocs.appdynamics.com/javadocs/java-agent-api/v4.5/.

    Common Use Cases

    The following are the common use cases for the Agent API.

    Starting and Ending a Synchronous Business Transaction

    The following example shows code that starts a Business Transaction called 'Checkout' whenever the method checkout() is called. The Business Transaction ends when the method returns. Encapsulating the method body in a try or finally block ensures that you end the Business Transaction even if the method itself throws an exception or otherwise terminates without reaching the end.

    public String checkout(List<ItemOrders> orders) {
       Transaction transaction = null;
       try {
            transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
     
            /*******************
             * Method Body Here
             *******************/
        } finally {
            if (transaction != null) {
               transaction.end();
            }
        }
    }


    Alternatively, you can use try-with-resources pattern:

    public String checkout(List<ItemOrders> orders) {
       try (Transaction transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false)) {
            /*******************
             * Method Body Here
             *******************/
        }
    }

    In this case, the Business Transaction ends when the try block closes.

    Starting and Ending an Asynchronous Business Transaction

    This example shows code that starts a Business Transaction called 'CheckoutAsync' whenever the method checkoutAsync() is called.  The originating segment created for the Business Transaction ends when the method endSegment() is called on the Business Transaction, or when it is closed if used in a try-with-resources construct.  Encapsulating the method body in a try/finally block ensures that we end the segment even if the method itself throws an exception or otherwise terminates without reaching the end.

    //The thread where the Business Transaction starts
    public String checkoutAsync(List<ItemOrders> orders) {
       Transaction transaction = null;
       try {
            transaction = AppdynamicsAgent.startTransaction("CheckoutAsync", null, EntryTypes.POJO, true);
    		//mark handoff to link this segment with the end segment
    		transaction.markHandoff(commonPayload);
    
            /*******************
             * Method Body Here
             *******************/
        } finally {
            if (transaction != null) {
               transaction.endSegment();
            }
        }
    }


    Alternatively, the try-with-resources pattern is supported:

    //The thread where the Business Transaction starts
    public String checkoutAsync(List<ItemOrders> orders) {
       try (Transaction transaction = AppdynamicsAgent.startTransaction("CheckoutAsync", null, EntryTypes.POJO, true)) {
    		//mark handoff to link this segment with the end segment
    		transaction.markHandoff(commonPayload);
    
            /*******************
             * Method Body Here
             *******************/
        }
    }


    This ends the segment in the thread where the Business Transaction was started when the try block closes. The Business Transaction itself needs to be ended in the method where the asynchronous Business Transaction ends:

    //The thread where the Business Transaction ends
    public String checkoutAsyncEnd(List<ItemOrders> orders, Transaction transaction, Object commonPayload) {
       //link to the originating segment
       Transaction transactionSegment = AppdynamicsAgent.startSegment(commonPayload);
    
       /*******************
       * Method Body Here
       *******************/
       if (transactionSegment != null) {
          transactionSegment.endSegment();
       }
       if (transaction != null) {
          transaction.end();
       }
    }

    Setting the Transaction Name After a Start

    The following example shows how to set the transaction name after it has been started. This is useful if you want to split transactions based on events that happen in your application:

    Transaction name can only be set after a start on the originating segment, and if no async hand-offs or exits have been made.

    public String checkout(List<ItemOrders> orders) {
       AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
       /*******************
        * Method Body Here
        *******************/
       if (orders.isEmpty()) {
       	   AppdynamicsAgent.setCurrentTransactionName("Empty Cart");
       }
       AppdynamicsAgent.getTransaction().end();
    }

    Starting a Transaction Using OOTB Servlet Naming Rules

    The following example shows how to leverage automatic servlet naming rules to name a transaction:

    public String checkout(List<ItemOrders> orders) {
    	Map<String, String> headers = new HashMap<String, String>();
    	headers.put("header1", "headerValue1");
    	Map<String, String[]> parameters = new HashMap<String, String[]>();
    	Map<String, Object> cookies = new HashMap<String, Object>();
    	cookies.put("chip", "ahoy");
    	ServletContext.ServletContextBuilder contextBuilder = new ServletContext.ServletContextBuilder()
            .withURL(new URL("https://www.yourstore.com/endpoint/to/checkout"))
            .withParameters(parameters)
            .withHeaders(headers)
            .withCookies(cookies)
            .withSessionAttributes(new HashMap<String, Object>())
            .withRequestMethod("GET")
            .withHostValue("hostValue")
            .withHostOriginatingAddress("hostOriginatingAddress");
    	Transaction t = AppdynamicsAgent.startServletTransaction(contextBuilder.build(), EntryTypes.HTTP, null, false);
       /*******************
        * Method Body Here
        *******************/
       t.end();
    }

    Defining an Exit Call

    For an inventoryServer.verifyQuantities(orders), which makes a request to another process, you can monitor that request as an Exit Call. This helps to continue monitoring the Business Transaction through the call to the downstream server and identify the time spent in the remote service. You can do this by modifying the method as follows:

    public void verifyQuantities(List<ItemOrders> orders) {
        ExitCall exitCall = null;
        try {
            exitCall = AppdynamicsAgent.getTransaction().startExitCall("Quantity Check", "Inventory Server", ExitTypes.HTTP, false);
             
           /*******************
            * Method Body
            *******************/
        } finally {
            if (exitCall != null) {
                exitCall.end();
            }
        }
    }


    The above code modifications define the Exit Call that manifests it as a remote service in the controller.  To tag and follow the request into an instrumented downstream tier, add a correlation header:

    public void verifyQuantities(List<ItemOrders> orders) {
        ExitCall exitCall = null;
        try {
            exitCall = AppdynamicsAgent.getTransaction().startExitCall("Quantity Check", "Inventory Server", ExitTypes.HTTP, false);
     
            // Generate the appdynamics correlation header
            String correlationHeader = exitCall.getCorrelationHeader();
     
            // ... Method code including request creation
     
            // Modify the request/payload to include the correlation header
            inventoryRequest.addHeader(AppdynamicsAgent.TRANSACTION_CORRELATION_HEADER, correlationHeader);
         
        } finally {
            if (exitCall != null) {
                exitCall.end();
            }
        }
    }

    Defining an Asynchronous Thread Handoff

    If your checkout method also does a thread handoff and executes some business logic that you want to monitor in a separate thread, register the worker thread with the Business Transaction:

    public String checkout(List<ItemOrders> orders) {
        Transaction transaction = null;
        try {
            transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
     
            // ... Method code
     
            // Custom thread handoff using custom queue
            asyncTaskQueue.add(task);
             
        } finally {
            if (transaction != null) {
               transaction.end();
            }
        }
    }


    To instrument this, modify the add method to mark a thread handoff and then start a new segment where the thread begins running:

    public class AsyncTaskQueue {
        public void add(Task task) {
            AppdynamicsAgent.getTransaction().markHandoff(task);
             
            /*******************
             * Method Body
             *******************/
    }
    public class Task {
        public void run() {
            Transaction transaction = null;
            try {
                transaction = AppdynamicsAgent.startSegment(this);
     
                /*******************
                 * Method Body
                 *******************/
            } finally {
                if (transaction != null) {
                    transaction.endSegment();
                }
            }
        }
     
        public void cancel() {
            AppdynamicsAgent.cancelHandoff(this);
     
            /*******************
             * Method Body
             *******************/
        }
    }


    The task object is used by the agent to link the segments. Correlating thread segments using the agent API requires that the agent is running in the Executor mode.

    Adding Data to Snapshot or Analytics

    In many instances, there are values of interest in the code that are helpful to add to the snapshot. This aids in the root cause diagnosis of issues or to send to the AppDynamics Business Transaction analytics to help answer real-time business-oriented questions about your application.  Data reported using this API appears in the same way as it had been collected with a Method Invocation Data collector.

    To report a total checkout amount to Business Transaction analytics and have it presented in the APM snapshots, use the following code:

    private static final Set<DataScope> dataScopeSet = new HashSet(Arrays.asList(DataScope.ANALYTICS, DataScope.SNAPSHOTS));
     
    public String checkout(List<ItemOrders> orders) {
        Transaction transaction = null;
        try {
            transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
     
            // ... Method code
     
            double shoppingCartTotal = total(orders);
            transaction.collectData("cart total", Double.toString(shoppingCartTotal), dataScopeSet);
             
        } finally {
            if (transaction != null) {
               transaction.end();
            }
        }
    }

    Defining a Custom Metric or Event

    It can also be useful to report a value as a custom metric:

    public String checkout(List<ItemOrders> orders) {
     
        // ... Method code
     
        double shoppingCartTotal = total(orders);
        AppdynamicsAgent.getMetricPublisher().reportSumMetric("Cart Total", (long) shoppingCartTotal);
     
    }


    Reporting custom metrics and events is possible irrespective of the Business Transaction context.


    • No labels