com.appdynamics.agent.api

Class AppdynamicsAgent

java.lang.Object

com.appdynamics.agent.api.AppdynamicsAgent

public class AppdynamicsAgent
extends java.lang.Object

AppdynamicsAgent is the entry point for access to the agent API. Transactions and segments are started directly from this class in a static fashion. Once created the Transactions and segments are managed via Transaction methods. It also provides access to metric and event reporting via their respective publisher classes.

Transaction Monitoring Example:

 
 public String foo(String bar) {
     return "Input was: " + bar;
 }
 
 

This method can be monitored as follows:

 
 public String foo(String bar) {
     Transaction transaction = null;
     try {
         transaction = AppdynamicsAgent.startTransaction("MyFooBT", null, false);

         return "Input was: " + bar;
     } finally {
         transaction.end();
     }
 }
 
 

Note: the try/finally block ensures the transaction ends even if the method ends with an exception.

This will create a Business Transaction named "MyFooBT" and will collect metrics and snapshots for the transaction. There is no second argument (correlation header) provided because this is an originating transaction.

Field Summary

Fields

Modifier and Type	Field and Description
static int	AGENT_API_LEVEL
static java.lang.String	TRANSACTION_CORRELATION_HEADER

Method Summary

Modifier and Type	Method and Description
static void	cancelHandoff(java.lang.Object commonObject) Cancels the tracking of an asynchronous handoff.
static ExitCall	fetchExitCall(java.lang.Object uniqueObject) Fetches an ExitCall that was previously stashed with ExitCall.stash(Object)
static EventPublisher	getEventPublisher() Gets the handle to the event publish API.
static ISDKLogger	getLogger() Gets a non-null logger that forwards messages to the Java agent logs.
static MetricPublisher	getMetricPublisher() Gets the handle to the metric publish API.
static Transaction	getTransaction() Gets the Transaction corresponding to the transaction pending on the current thread.
static Transaction	getTransaction(java.lang.String uniqueIdentifier) Gets the Transaction corresponding to the transaction with the matching UUID.
static Transaction	setCurrentTransactionName(java.lang.String name) Sets the name of the current transaction if no asynchronous hand-offs or exit calls have been made, or starts a new synchronous transaction if there is no current transaction.
static Transaction	startSegment(java.lang.Object commonObject) Starts an asynchronous segment.
static Transaction	startSegmentNoHandoff(java.lang.String uniqueIdentifier) Starts an asynchronous segment with no handoff.
static Transaction	startServletTransaction(ServletContext servletContext, java.lang.String entryType, java.lang.String correlationHeader, boolean isAsync) Starts a servlet transaction.
static Transaction	startTransaction(java.lang.String btName, java.lang.String correlationHeader, java.lang.String entryType, boolean isAsync) Starts a transaction.
static Transaction	startTransactionAndServiceEndPoint(java.lang.String btName, java.lang.String correlationHeader, java.lang.String serviceEndpointName, java.lang.String entryType, boolean isAsync) Starts a transaction and a service endpoint.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AGENT_API_LEVEL

public static final int AGENT_API_LEVEL

See Also:

Constant Field Values

TRANSACTION_CORRELATION_HEADER

public static final java.lang.String TRANSACTION_CORRELATION_HEADER

See Also:

Constant Field Values

Method Detail

startTransaction

public static Transaction startTransaction(java.lang.String btName,
                                           java.lang.String correlationHeader,
                                           java.lang.String entryType,
                                           boolean isAsync)

Starts a transaction. If there is a correlation header provided, it is used to continue the transaction that created the exit call. If not, a new transaction is created with the name btName. The agent generates a random UUID for this request. To start an asynchronous transaction, specify the isAsync flag. After all the tasks that include the current transaction context are done, for example, making an exit call and so on, ensure to invoke the endSegment call to end the context in this thread or use the try-with-resources construct that handles this internally.

Note: This returns a no-op transaction if the thread invoking it is in the context of a pending transaction, or if it is unable to start a transaction.

Parameters:

btName - The name of the Business Transaction, if not continuing

correlationHeader - The correlation header retrieved from the inbound request, used to continue a transaction

entryType - The entry type from EntryTypes to be used for the BT. For custom entry pass null or EntryTypes.POJO

isAsync - Boolean indicating if it is an asynchronous entry. If unsure, set the value as true.

Returns:

A new Transaction object corresponding to this Business Transaction request

startServletTransaction

public static Transaction startServletTransaction(ServletContext servletContext,
                                                  java.lang.String entryType,
                                                  java.lang.String correlationHeader,
                                                  boolean isAsync)

Starts a servlet transaction. If there is a correlation header provided, it is used to continue the transaction that created the exit call. If not, a new transaction is created with the default ootb servlet naming using servletContext. The agent will generate a random UUID for this request. To start an asynchronous transaction, specify the isAsync flag. After all the tasks that include the current transaction context are done, for example, making an exit call and so on, ensure to invoke the endSegment call to end the context in this thread or use the try-with-resources construct which handles this internally.

Note: This returns a no-op Transaction if the thread invoking it is already in the context of a pending transaction, or if it is unable to start a transaction.

Parameters:

servletContext - The context for this servlet transaction, used for ootb transaction naming

entryType - The entry type from EntryTypes to be used for the BT. For custom entry pass null or EntryTypes.POJO

correlationHeader - The correlation header retrieved from the inbound request, used to continue a transaction

isAsync - Boolean indicating if it is an asynchronous entry. If you are not sure, set the value to true.

Returns:

A new Transaction object corresponding to this Business Transaction request

startTransactionAndServiceEndPoint

public static Transaction startTransactionAndServiceEndPoint(java.lang.String btName,
                                                             java.lang.String correlationHeader,
                                                             java.lang.String serviceEndpointName,
                                                             java.lang.String entryType,
                                                             boolean isAsync)

Starts a transaction and a service endpoint. If there is a correlation header provided, it is used to continue the transaction that created the exit call. If not, a new transaction is created with name btName. The agent generates a random UUID for this request. A service endpoint is started with name sepName at this point, and ends when this transaction ends.

Note: This returns a no-op transaction if the thread invoking it is already in the context of a pending transaction, or if it is unable to start a transaction. An SEP is created only if the transaction is successfully created.

Parameters:

btName - The name of the Business Transaction, if not continuing

correlationHeader - The correlation header retrieved from the inbound request, used to continue a transaction

serviceEndpointName - The name assigned to the Service Endpoint created by this call

entryType - The entry type from EntryTypes to be used for the BT. For custom entry pass null or EntryTypes.POJO

isAsync - Boolean indicating if it is an asynchronous entry. If unsure set it as true.

Returns:

A new Transaction object corresponding to this Business Transaction request

getTransaction

public static Transaction getTransaction()

Gets the Transaction corresponding to the transaction pending on the current thread.

Returns:

A Transaction corresponding to the transaction pending on the current thread.

getTransaction

public static Transaction getTransaction(java.lang.String uniqueIdentifier)

Gets the Transaction corresponding to the transaction with the matching UUID.

Parameters:

uniqueIdentifier - The String to be used to look up the transaction to return

Returns:

A Transaction corresponding to the transaction with the matching uniqueIdentifier

setCurrentTransactionName

public static Transaction setCurrentTransactionName(java.lang.String name)

Sets the name of the current transaction if no asynchronous hand-offs or exit calls have been made, or starts a new synchronous transaction if there is no current transaction. Will show up as a new transaction on the controller while retaining timing.

Note: This will return a no-op transaction in case of the above reasons, or if the name is null.

Parameters:

name - The name this transaction is set to.

Returns:

A Transaction corresponding to the updated transaction.

startSegment

public static Transaction startSegment(java.lang.Object commonObject)

Starts an asynchronous segment. This method follows a preceding Transaction.markHandoff(Object) call. To end the segment, use Transaction.endSegment() from the same thread.

Parameters:

commonObject - The object used to match this call to the Transaction.markHandoff(Object) call.

Returns:

a Transaction object representing this asynchronous segment

startSegmentNoHandoff

public static Transaction startSegmentNoHandoff(java.lang.String uniqueIdentifier)

Starts an asynchronous segment with no handoff. This method is used only when it is not possible to mark the origin of the asynchronous task with Transaction.markHandoff(Object). The segment started with this asynchronous task is associated with the originating segment of the transaction. This method only succeeds if the originating segment is still alive at the time of this call.

Parameters:

uniqueIdentifier - The unique identifier for the transaction that is associated with this segment.

Returns:

a Transaction object representing this asynchronous segment

cancelHandoff

public static void cancelHandoff(java.lang.Object commonObject)

Cancels the tracking of an asynchronous handoff. This method follows a preceding Transaction.markHandoff(Object) call. Call this method if the asynchronous task is not run. If the task has not run, no tracking information is added to the transaction.

Parameters:

commonObject - object previously used to uniquely identify this async handoff

getMetricPublisher

public static MetricPublisher getMetricPublisher()

Gets the handle to the metric publish API. Returns a no-op proxy if the Java agent is not initialized on the current JVM (for example, -javaagent option is not added to the JVM startup command or agent failed to initialize).

Returns:

an implementation of MetricPublisher interface

See Also:

MetricPublisher

getEventPublisher

public static EventPublisher getEventPublisher()

Gets the handle to the event publish API. Returns a no-op proxy if the Java agent is not initialized on the current JVM (for example, -javaagent option is not added to the JVM startup command or agent failed to initialize).

Returns:

an implementation of EventPublisher interface

See Also:

EventPublisher

getLogger

public static ISDKLogger getLogger()

Gets a non-null logger that forwards messages to the Java agent logs.

Returns:

an ISDKLogger object

fetchExitCall

public static ExitCall fetchExitCall(java.lang.Object uniqueObject)

Fetches an ExitCall that was previously stashed with ExitCall.stash(Object)

Parameters:

uniqueObject - The unique object key that the exit call was stashed with

Returns:

a non-null ExitCall or NoOpExitCall object