com.appdynamics.apm.appagent.api
Interface ITransactionDemarcator

public interface ITransactionDemarcator

This interface provides an API for java applications to integrate with AppDynamics business transaction management. This can be accessed by all classes in the application as it will be on the bootstrap classpath.

The api allows users to programmatically control transaction boundaries with single and multi threaded applications across distributed tiers.

Since:

1.0

Field Summary

static java.lang.String

APPDYNAMICS_TRANSACTION_CORRELATION_HEADER Key name to retrieve AppDynamics Transaction Correlation Header from JMS Message Header properties

Method Summary

boolean	addCurrentThreadToTransaction(java.lang.String uniqueIdentifierForTransaction, java.lang.String activityName, java.util.Map<java.lang.String,java.lang.String> activityProperties) Method to add a thread's activity to a currently executing global transaction activity on a JVM.
boolean	addPropertiesForCurrentThread(java.util.Map<java.lang.String,java.lang.String> properties) Method to add properties for the current thread's activity.
boolean	addPropertyForCurrentThread(java.lang.String name, java.lang.String value) Method to add a property for the current thread's activity.
java.lang.String	beginContinuingTransaction(java.lang.String appDynamicsTransactionHeader, java.lang.String uniqueIdentifierForTransaction) Marks begin of a multi threaded transaction originating from a remote JVM and identified by the correlation id 'appDynamicsTransactionHeader'.
java.lang.String	beginContinuingTransactionAndAddCurrentThread(java.lang.String appDynamicsTransactionHeader, java.lang.String uniqueIdentifierForTransaction) Marks begin of a transaction on cuerrent thread identified by the correlation id 'appDynamicsTransactionHeader' originating from a remote JVM .
java.lang.String	beginExternalCall(java.util.Map<java.lang.String,java.lang.String> invokedServiceIdentifyingProperties, java.lang.String invokedServiceDisplayName, boolean synchronous) Marks the beginning of an external service call uniquely identified by the service identifying properties.
java.lang.String	beginExternalCall(java.lang.String invokedServiceIdentifyingName, java.lang.String invokedServiceDisplayName, boolean synchronous) Marks the beginning of an external service call uniquely identified by the 'service identifying name' parameter.
java.lang.String	beginOriginatingTransaction(java.lang.String transactionName, java.lang.String uniqueIdentifierForTransaction) Method to start a new multi-threaded transaction on this JVM by name 'transactionName'.
java.lang.String	beginOriginatingTransactionAndAddCurrentThread(java.lang.String transactionName, java.lang.String uniqueIdentifierForTransaction) Method to start a new transaction on current thread by name 'transactionName'.
boolean	endContinuingTransaction(java.lang.String uniqueIdentifierForTransaction) Method to end multi-threaded transaction activity tracking on a JVM.
boolean	endContinuingTransactionAndRemoveCurrentThread() Method to end transaction activity tracking on a JVM for a continuing transaction.
void	endExternalCall(boolean error, java.lang.String errorDetail) Marks the end of an external service call.
boolean	endOriginatingTransaction(java.lang.String uniqueIdentifierForTransaction) Method to end multi-threaded activity tracking on a JVM for a transaction originating in the same JVM.
boolean	endOriginatingTransactionAndRemoveCurrentThread() Method to end transaction activity tracking on a JVM for a transaction originating in the current thread.
java.lang.String	extractTransactionHeaderFromJMSMessage(java.lang.Object jmsMessage) Method to extract appdynamics transaction correlation header from a JMS Message.
java.lang.String	getUniqueIdentifierForTransaction() Returns the unique transaction instance identifier for the transaction associated with the current thread or NULL if transaction is not intialized yet.
boolean	removeCurrentThreadFromTransaction() Method to remove the current thread activity from the transaction.
boolean	setActivityNameForCurrentThread(java.lang.String activityName) Method to set the logical name for the current thread activity.
boolean	setUniqueIdentifierForTransaction(java.lang.String uniqueIdentifierForTransaction) Sets the unique transaction instance identifier for the transaction to the user defined id.

Field Detail

APPDYNAMICS_TRANSACTION_CORRELATION_HEADER

static final java.lang.String APPDYNAMICS_TRANSACTION_CORRELATION_HEADER

Key name to retrieve AppDynamics Transaction Correlation Header from JMS Message Header properties

See Also:

Constant Field Values

Method Detail

beginExternalCall

java.lang.String beginExternalCall(java.lang.String invokedServiceIdentifyingName,
                                   java.lang.String invokedServiceDisplayName,
                                   boolean synchronous)
                                   throws java.lang.IllegalArgumentException

Marks the beginning of an external service call uniquely identified by the 'service identifying name' parameter. The external call is associated with the business transaction executed by the current thread. This method starts the timer for measuring the execution time of the external call.

Refer Sample code SyncClient. On server side use beginContinuingTransactionAndAddCurrentThread api to continue the transaction.

If the caller is not waiting for external call invocation to complete (e.g. has a semantics similar to JMS send(Message msg) api) the synchronous boolean should be set to false.

Refer Sample code AsyncClient. On server side use beginContinuingTransaction api to continue the transaction.

Parameters:

invokedServiceIdentifyingName - the name uniquely identifying the service being called

invokedServiceDisplayName - the display name of the service being called

synchronous - if the caller is waiting for external call to respond before proceeding

Returns:

the string containing the appdynamics transaction header to be propagated

Throws:

java.lang.IllegalArgumentException - if invokedServiceIdentifyingName is null

beginExternalCall

java.lang.String beginExternalCall(java.util.Map<java.lang.String,java.lang.String> invokedServiceIdentifyingProperties,
                                   java.lang.String invokedServiceDisplayName,
                                   boolean synchronous)

Marks the beginning of an external service call uniquely identified by the service identifying properties. The external call is associated with the business transaction executed by the current thread. This method starts the timer for measuring the execution time for the external call

Refer Sample code SyncClient

On server side use beginContinuingTransactionAndAddCurrentThread api to continue the transaction.

If the caller is not waiting for external call invocation to complete (e.g. has a semantics similar to JMS send(Message msg) api) the synchronous boolean should be set to false.

Refer Sample code AsyncClient

On server side use beginContinuingTransaction api to continue the transaction.

Parameters:

invokedServiceIdentifyingProperties - mandatory, the properties uniquely identifying the service being called

invokedServiceDisplayName - mandatory, the display name of the service being called

synchronous - if the caller is waiting for invoked service to complete execution before invoking

Returns:

the string containing the appdynamics transaction header to be propagated

Throws:

java.lang.IllegalArgumentException - if invokedServiceIdentifyingProperties is null orm empty

endExternalCall

void endExternalCall(boolean error,
                     java.lang.String errorDetail)

Marks the end of an external service call. It records the total execution time and error details if any for the call.

Parameters:

error - if any error occurred during the execution of the external call

errorDetail - string containing a detailed message about the error

beginContinuingTransactionAndAddCurrentThread

java.lang.String beginContinuingTransactionAndAddCurrentThread(java.lang.String appDynamicsTransactionHeader,
                                                               java.lang.String uniqueIdentifierForTransaction)

Marks begin of a transaction on cuerrent thread identified by the correlation id 'appDynamicsTransactionHeader' originating from a remote JVM . If the transaction is begins and ends on different threads then prefer to use beginContinuingTransaction api instead.

This method starts measuring time for the transaction activity on this JVM and records the total time till endContinuingTransactionAndRemoveCurrentThread is called on the current thread. This method also starts capturing the call graph of the caller thread. If additional threads need to participate in this global transaction they need to invoke addCurrentThreadToTransaction and removeCurrentThreadFromTransaction with the transaction instance identifier.

This method should be called only once for a given 'appDynamicsTransactionHeader'.

Refer Sample code SyncServer

Parameters:

appDynamicsTransactionHeader - the appdynamics transaction correlation header propagated from remote JVM

uniqueIdentifierForTransaction - unique transaction instance identifier for all threads which are a part of this transaction, if null system generates a new id and returns it.

Returns:

the string containing the unique transaction instance identifier. returns null if transaction was not started successfully

endContinuingTransactionAndRemoveCurrentThread

boolean endContinuingTransactionAndRemoveCurrentThread()

Method to end transaction activity tracking on a JVM for a continuing transaction. This must be invoked in the same thread as beginContinuingTransactionAndAddCurrentThread. It will record the total time for the transaction activity.

Returns:

if the transaction ended successfully, false if no current thread has no active transaction. All internal errors are logged in agent log files

getUniqueIdentifierForTransaction

java.lang.String getUniqueIdentifierForTransaction()

Returns the unique transaction instance identifier for the transaction associated with the current thread or NULL if transaction is not intialized yet. To associated a worker thread with the global transaction addCurrentThreadToTransaction api should be invoked by the worker thread with this transaction instance id.

See sample MultiThreadServer The identifier should not be used for correlating transactions across different tiers.

Returns:

transaction id for current thread

setUniqueIdentifierForTransaction

boolean setUniqueIdentifierForTransaction(java.lang.String uniqueIdentifierForTransaction)
                                          throws java.lang.IllegalArgumentException

Sets the unique transaction instance identifier for the transaction to the user defined id. This api should be called only from the thread that begins the transaction using api or transaction match rules (controller ui / agent xml) and before any threaded activity is initiated with this transaction i.e. before addCurrentThread api is invoked with the unique transaction instance identifier.

Parameters:

uniqueIdentifierForTransaction - user defined unique transaction instance identifier

Returns:

true if the new transaction id was set successfully

Throws:

java.lang.IllegalArgumentException - if uniqueIdentifierForTransaction is null

addCurrentThreadToTransaction

boolean addCurrentThreadToTransaction(java.lang.String uniqueIdentifierForTransaction,
                                      java.lang.String activityName,
                                      java.util.Map<java.lang.String,java.lang.String> activityProperties)

Method to add a thread's activity to a currently executing global transaction activity on a JVM. This method starts measuring the execution time for this particular thread's activity and also starts capturing call graph information and should preferably be called before the thread starts processing any business logic.

The total execution time is recorded when the removeCurrentThreadFromTransaction is called.

See sample MutiThreadedExecutor

Parameters:

uniqueIdentifierForTransaction - the identification information for the transaction this thread is a part of

activityName - the logical name for this activity visible in call graph user interface, this is an optional information and can be set later using the setActivityNameForCurrentThread.

activityProperties - any properties for this activity that need to be viewed in the visualization for the call graph for this thread , this is an optional information for this call and can be set later using the addPropertiesForCurrentThread

Returns:

if current thread was successfully added to the mult-threaded transaction, all internal errors are logged in agent log files

removeCurrentThreadFromTransaction

boolean removeCurrentThreadFromTransaction()

Method to remove the current thread activity from the transaction.

This should be called after the thread has finished processing all of the business logic This stops capturing the call graph information and records the total time for this activity.

Returns:

if current thread was removed from the multi threaded transaction. returns false if current thread has no active transaction

setActivityNameForCurrentThread

boolean setActivityNameForCurrentThread(java.lang.String activityName)

Method to set the logical name for the current thread activity. This should be called only after the current thread has been added to the transaction.

This will overwrite any previous activity name, if set.

Parameters:

activityName - the logical name for this activity, easy way to identify the activity in call graph ui

Returns:

if activity name was successfully set to the current thread, returns false if no active transaction for current thread

addPropertyForCurrentThread

boolean addPropertyForCurrentThread(java.lang.String name,
                                    java.lang.String value)

Method to add a property for the current thread's activity. This should be called only after the current thread has been added to the transaction.

Parameters:

name - the name for the property

value - the value for the property

Returns:

property was set to current thread, returns false if if no active transaction for current thread

addPropertiesForCurrentThread

boolean addPropertiesForCurrentThread(java.util.Map<java.lang.String,java.lang.String> properties)

Method to add properties for the current thread's activity. This should be called only after the current thread has been added with a transaction , these will be added to any previously set properties fro the current activity.

Parameters:

properties - properties to be added.

Returns:

property map was set to current thread, returns false if if no active transaction for current thread

extractTransactionHeaderFromJMSMessage

java.lang.String extractTransactionHeaderFromJMSMessage(java.lang.Object jmsMessage)
                                                        throws java.lang.IllegalArgumentException

Method to extract appdynamics transaction correlation header from a JMS Message. This identifier is a part of the JMS header property of the message payload, set by appdynamics agent in the JMS message sender JVM. The correlation header is input to beginContinuingTransaction api.

The header can also be extracted by using javax.jms.Message.getStringProperty(String APPDYNAMICS_KEY) api

Parameters:

jmsMessage - the javax.jms.Message received on this tier

Returns:

String representing the appdynamics transaction header for the transaction. Returns NULL if any errors were encountered while processing the message object. All errors are logged in agent.log file

Throws:

java.lang.IllegalArgumentException - if the object passed is not an instance of javax.jms.Message.

beginContinuingTransaction

java.lang.String beginContinuingTransaction(java.lang.String appDynamicsTransactionHeader,
                                            java.lang.String uniqueIdentifierForTransaction)

Marks begin of a multi threaded transaction originating from a remote JVM and identified by the correlation id 'appDynamicsTransactionHeader'. If the transaction begins and ends on same thread then prefer to use beginContinuingTransactionAndAddCurrentThread api instead.

The second parameter is a unique transaction instance id shared by all threads that participate in this global transaction. This method starts measuring time for the multi threaded transaction activity on this JVM and records the total time when the endContinuingTransaction is called with the transaction instance identifier.

The calling thread is not associated with the transaction, hence if the calling thread's activity needs to be captured then addCurrentThreadToTransaction and removeCurrentThreadFromTransaction must be invoked explicitly on current thread.

To mark the end of the transaction endContinuingTransaction needs to be invoked. (from any thread) with the transaction instance identifier.

This method should be called only once for a given 'appDynamicsTransactionHeader'.

Refer Sample code AsyncServer

Parameters:

appDynamicsTransactionHeader - the appdynamics transaction correlation header propagated from remote JVM

uniqueIdentifierForTransaction - unique transaction instance identifier for all threads which are a part of this transaction, if null system generates a new id and returns it.

Returns:

the string containing the unique transaction instance identifier. returns null if transaction was not started successfully

endContinuingTransaction

boolean endContinuingTransaction(java.lang.String uniqueIdentifierForTransaction)

Method to end multi-threaded transaction activity tracking on a JVM. This will record the total time for the transaction activity.

Parameters:

uniqueIdentifierForTransaction - the identification for this transaction

Returns:

if the mult-threaded transaction was successfully ended; all internal errors are logged in agent log files

beginOriginatingTransaction

java.lang.String beginOriginatingTransaction(java.lang.String transactionName,
                                             java.lang.String uniqueIdentifierForTransaction)
                                             throws java.lang.IllegalArgumentException

Method to start a new multi-threaded transaction on this JVM by name 'transactionName'.

This signals the start of a multi-threaded transaction and the transaction instance identifer will be the common identification for all threads that intend to participate in this global transaction. This method starts measuring time for the transaction activity on this JVM and records the total time when the endOriginatingTransaction is called with the transaction instance identifier.

The calling thread is not associated with the transaction, hence if the calling thread's activity needs to be captured then addCurrentThreadToTransaction and removeCurrentThreadFromTransaction must be invoked explicitly on current thread.

Refer Sample code MultiThreadServer

Parameters:

transactionName - the name of the business transaction

uniqueIdentifierForTransaction - unique transaction instance identifier for all threads which are a part of this transaction, if null system generates a new id that can be retrieved using getUniqueIdentifierForTransaction.

Returns:

the string containing the unique transaction instance identifier. returns null if transaction was not started successfully

Throws:

java.lang.IllegalArgumentException - if transactionName is empty

endOriginatingTransaction

boolean endOriginatingTransaction(java.lang.String uniqueIdentifierForTransaction)

Method to end multi-threaded activity tracking on a JVM for a transaction originating in the same JVM. This will record the total time for the transaction activity.

Parameters:

uniqueIdentifierForTransaction - the identification for this transaction

Returns:

if the mult-threaded transaction was successfully ended, all internal errors are logged in agent log files

beginOriginatingTransactionAndAddCurrentThread

java.lang.String beginOriginatingTransactionAndAddCurrentThread(java.lang.String transactionName,
                                                                java.lang.String uniqueIdentifierForTransaction)

Method to start a new transaction on current thread by name 'transactionName'. The name will be visible as the business transaction name in controller dashboards

The unique transaction instance identifer will be the common identification information for all threads that participate in this unit of work. The transaction is associated with the current thread. This method starts measuring time for the transaction activity on this JVM and records the total time when the endOriginatingTransactionAndRemoveCurrentThread is called. on the same thread. This method also starts capturing the call graph of the caller thread if applicable. The addCurrentThreadToTransaction method needs to be called from all threads whose execution time and activity call graphs need to be captured adn associated with the this transaction.

Refer Sample code MultiThreadServer

Parameters:

transactionName - the name of the business transaction

uniqueIdentifierForTransaction - unique transaction instance identifier for all threads which are a part of this transaction, if null system generates a new id that can be retrieved using getUniqueIdentifierForTransaction.

Returns:

the string containing the unique transaction instance identifier. returns null if transaction was not started successfully

Throws:

java.lang.IllegalArgumentException - if transactionName is empty

endOriginatingTransactionAndRemoveCurrentThread

boolean endOriginatingTransactionAndRemoveCurrentThread()

Method to end transaction activity tracking on a JVM for a transaction originating in the current thread. This will record the total time for the transaction activity. This must be invoked in the same thread as beginOriginatingTransactionAndAddCurrentThread.

Returns:

if the transaction ended successfully, false if no current thread has no active transaction. All internal errors are logged in agent log files