com.appdynamics.eumagent.runtime

Class Instrumentation

java.lang.Object

com.appdynamics.eumagent.runtime.Instrumentation

public class Instrumentation
extends java.lang.Object

Interact with the AppDynamics Android Agent running in your application.

This class provides a number of methods to interact with the AppDynamics Android Agent including

• Initializing the agent with the right application key
• Reporting custom metrics/timers
• Reporting info points manually

Initializing AppDynamics Agent

The agent does not automatically start with your application. Using the app key shown in your controller UI, you can initialize the agent. This has to be done from your primary activity’s Activity.onCreate(android.os.Bundle).onCreate method before any other initialization routines in your application.

For example:

@Override
public void onCreate(Bundle savedInstanceState){
    Instrumentation.start("ABC-DEF-GHI", getApplicationContext());
    //your code here
}

where ABC-DEF-GHI is your application key. Once initialized, further calls to start(String, android.content.Context) has no effect on the agent.

Reporting custom timers and metrics

You can also report custom timers and metrics using the following API(s):

• reportMetric(String, long)
• startTimer(String) and stopTimer(String)

Custom Metrics

Custom metrics allows you to report numeric values associated with a ‘metric name’. For example, to track the number of times your users clicked the ‘checkout’ button, you can report it as easily as follows:

findViewById(R.id.checkout_button).setOnClickListener(new View.OnClickListener(){
     @Override
     public void onClick(View view){
         //run your checkout routine.
         Instrumentation.reportMetric("Checkout Count", 1);
     }
});

Custom Timers

Using Custom timers, we can time events in your applications that span across multiple threads/methods. For example, the code snippet below reports how long the user interacted with MyActivity.

public class MyActivity extends Activity {
    @Override
    protected void onStart(){
        Instrumentation.startTimer("Time Spent on MyActivity");
        //your code here.
    }

    @Override
    protected void onStop(){
        Instrumentation.stopTimer("Time Spent on MyActivity");
        //your code here.
    }
}

Note that, startTimer(String) and stopTimer(String) can be called from different threads.

Reporting info points

Info Points allows you to track execution of interesting methods in your application code. This includes reporting method arguments, return value and exception that was thrown by the method. For example, to report that method downloadImage executed with arguments can be easily done as follows:

private void downloadImage(URL url) {
    CallTracker tracker =
         Instrumentation.beginCall("com.example.android.awesomeapp.ImageDownloader", "downloadImage")
             .withArguments(url);
    try {
         //download image.
         tracker.reportCallEnded()
    } catch(Exception e) {
        //handle exception thrown
        tracker.reportCallEndedWithException(e);
    }
}

For more information please see:

• beginCall(boolean, String, String, Object...)
• CallTracker.reportCallEnded()
• CallTracker.reportCallEndedWithException(Exception)
• CallTracker.reportCallEndedWithReturnValue(Object)

Field Summary

Fields

Modifier and Type	Field and Description
static int	LOGGING_LEVEL_INFO Only sparse important logs are printed.
static int	LOGGING_LEVEL_NONE No logs printed.
static int	LOGGING_LEVEL_VERBOSE All logs are printed.
static int	VALID_INTERACTION_CAPTURE_MODES Valid capture modes for UI instrumentation.

Method Summary

Methods

Modifier and Type	Method and Description
static CallTracker	beginCall(boolean isStaticMethod, java.lang.String className, java.lang.String methodName, java.lang.Object... args) Reports that an info point has started.
static CallTracker	beginCall(java.lang.String className, java.lang.String methodName, java.lang.Object... args) Reports that an info point has started.
static HttpRequestTracker	beginHttpRequest(java.net.URL url) Begins tracking an HTTP request.
static void	changeAppKey(java.lang.String appKey) Change the app key.
static void	endCall(CallTracker tracker) Deprecated. Instead, use: CallTracker.reportCallEnded()
static void	endCall(CallTracker tracker, java.lang.Object returnValue) Deprecated. Instead, use CallTracker.reportCallEndedWithReturnValue(Object)
static void	leaveBreadcrumb(java.lang.String breadcrumb) Leaves a breadcrumb that will appear in a crash report.
static void	leaveBreadcrumb(java.lang.String breadcrumb, int mode) Leaves a breadcrumb that will appear in a crash report and, optionally, session.
static void	reportMetric(java.lang.String name, long value) Reports metric value for the given name.
static void	setUserData(java.lang.String key, java.lang.String value, boolean persist) Sets a key-value pair identifier that will be included in all snapshots.
static void	start(AgentConfiguration agentConfiguration) Initialize the agent with the given configuration.
static void	start(java.lang.String appKey, android.content.Context context) Initialize the agent with the given application key and Context.
static void	start(java.lang.String appKey, android.content.Context context, boolean debugEnabled) Initialize the agent with the given application key and Context.
static void	start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL) Initialize the agent with the given application key and Context.
static void	start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL, boolean debugEnabled) Initialize the agent with the given application key and Context.
static void	startTimer(java.lang.String name) Starts a global timer with the given name.
static void	stopTimer(java.lang.String name) Stops a global timer with the given name and reports it to the cloud.

Methods inherited from class java.lang.Object

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

Field Detail

LOGGING_LEVEL_NONE

public static final int LOGGING_LEVEL_NONE

No logs printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)

See Also:

Constant Field Values

LOGGING_LEVEL_INFO

public static final int LOGGING_LEVEL_INFO

Only sparse important logs are printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)

See Also:

Constant Field Values

LOGGING_LEVEL_VERBOSE

public static final int LOGGING_LEVEL_VERBOSE

All logs are printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)

See Also:

Constant Field Values

VALID_INTERACTION_CAPTURE_MODES

public static final int VALID_INTERACTION_CAPTURE_MODES

Valid capture modes for UI instrumentation.

See Also:

Constant Field Values

Method Detail

changeAppKey

public static void changeAppKey(java.lang.String appKey)

Change the app key. Older beacons/reports will be discarded when app key is changed.

NOTE: Invoking this method has no effect unless the agent was already initialized by calling one of the start methods.

Parameters:

appKey - The new application key to use for reporting beacons.

Throws:

java.lang.IllegalArgumentException - if appKey is null or empty.

start

public static void start(java.lang.String appKey,
         android.content.Context context)

Initialize the agent with the given application key and Context.

Parameters:

appKey - The application key.

context - The Context of your application.

Throws:

java.lang.IllegalArgumentException - if appKey is null or empty.

java.lang.IllegalArgumentException - if context is null.

java.lang.IllegalStateException - if AppDynamics compile-time instrumentation has not been added to the application.

start

public static void start(java.lang.String appKey,
         android.content.Context context,
         java.lang.String collectorURL)

Initialize the agent with the given application key and Context.

Parameters:

appKey - The application key.

context - The Context of your application.

collectorURL - The valid AppDynamics collector url.

Throws:

java.lang.IllegalArgumentException - if appKey is null or empty.

java.lang.IllegalArgumentException - if collectorURL is null or invalid.

java.lang.IllegalArgumentException - if context is null.

java.lang.IllegalStateException - if AppDynamics compile-time instrumentation has not been added to the application.

start

public static void start(java.lang.String appKey,
         android.content.Context context,
         boolean debugEnabled)

Initialize the agent with the given application key and Context.

Parameters:

appKey - The application key.

context - The Context of your application.

debugEnabled - Specifies if agent info logging should be enabled.

Throws:

java.lang.IllegalArgumentException - if appKey is null or empty.

java.lang.IllegalArgumentException - if context is null.

java.lang.IllegalStateException - if AppDynamics compile-time instrumentation has not been added to the application.

start

public static void start(java.lang.String appKey,
         android.content.Context context,
         java.lang.String collectorURL,
         boolean debugEnabled)

Initialize the agent with the given application key and Context.

Parameters:

appKey - The application key.

context - The Context of your application.

collectorURL - The valid app dynamics collector url.

debugEnabled - Specifies if agent info logging should be enabled.

Throws:

java.lang.IllegalArgumentException - if appKey is null or empty.

java.lang.IllegalArgumentException - if collectorURL is null or not a valid url.

java.lang.IllegalArgumentException - if context is null.

java.lang.IllegalStateException - if AppDynamics compile-time instrumentation has not been added to the application.

start

public static void start(AgentConfiguration agentConfiguration)

Initialize the agent with the given configuration.

Parameters:

agentConfiguration - The agent configuration to use.

Throws:

java.lang.IllegalArgumentException - if configuration is invalid.

java.lang.IllegalStateException - if AppDynamics compile-time instrumentation has not been added to the application.

reportMetric

public static void reportMetric(java.lang.String name,
                long value)

Reports metric value for the given name.

NOTE: The name can contain only alphanumeric characters and spaces.

Parameters:

name - The name of the metric key.

value - The value reported for the given key.

Throws:

java.lang.IllegalArgumentException - if the name is empty or malformed.

java.lang.NullPointerException - if the name is null.

startTimer

public static void startTimer(java.lang.String name)

Starts a global timer with the given name.

NOTE: The name can contain only alphanumeric characters and spaces.

Parameters:

name - The name of the timer.

Throws:

java.lang.IllegalArgumentException - if the name is empty or malformed.

java.lang.NullPointerException - if the name is null.

stopTimer

public static void stopTimer(java.lang.String name)

Stops a global timer with the given name and reports it to the cloud.

NOTE: The name can contain only alphanumeric characters and spaces.

Parameters:

name - The name of the timer.

Throws:

java.lang.IllegalArgumentException - if the name is empty or malformed.

java.lang.NullPointerException - if the name is null.

beginCall

public static CallTracker beginCall(java.lang.String className,
                    java.lang.String methodName,
                    java.lang.Object... args)

Reports that an info point has started.

Parameters:

className - The class containing the info point method.

methodName - The name of the method that started execution.

args - The arguments passed to this method.

Throws:

java.lang.IllegalArgumentException - if className is null or empty or if methodName is null or empty.

beginCall

public static CallTracker beginCall(boolean isStaticMethod,
                    java.lang.String className,
                    java.lang.String methodName,
                    java.lang.Object... args)

Reports that an info point has started.

Parameters:

isStaticMethod - If true, the method being reported is static.

className - The class containing the info point method.

methodName - The name of the method that started execution.

args - The arguments passed to this method.

Throws:

java.lang.IllegalArgumentException - if className is null or empty or if methodName is null or empty.

endCall

public static void endCall(CallTracker tracker,
           java.lang.Object returnValue)

Deprecated. Instead, use CallTracker.reportCallEndedWithReturnValue(Object)

Reports that an info point has ended.

If tracker is null, this method does nothing.

Parameters:

tracker - The tracker that was obtained by calling beginCall(boolean, String, String, Object...) / beginCall(String, String, Object...)

returnValue - The value returned by the method invocation - can be null.

endCall

public static void endCall(CallTracker tracker)

Deprecated. Instead, use: CallTracker.reportCallEnded()

Reports that an info point has ended.

Parameters:

tracker - The tracker that was obtained by calling beginCall(boolean, String, String, Object...) / beginCall(String, String, Object...)

beginHttpRequest

public static HttpRequestTracker beginHttpRequest(java.net.URL url)

Begins tracking an HTTP request.

Call this immediately before sending an HTTP request to track it manually.

Parameters:

url - The URL being requested.

Returns:

The tracking object.

Throws:

java.lang.NullPointerException - if the url is null.

leaveBreadcrumb

public static void leaveBreadcrumb(java.lang.String breadcrumb)

Leaves a breadcrumb that will appear in a crash report.

Call this when something interesting happens in your application. If your application crashes at some point in the future, the breadcrumb will be included in the crash report, to help you understand the problem. Each crash report displays the most recent 99 breadcrumbs.

If you would like it to appear also in sessions, use the method leaveBreadcrumb(String, int) instead.

Parameters:

breadcrumb - The string to include in the crash report. If it’s longer than 2048 characters, it will be truncated. If it’s empty, no breadcrumb will be recorded.

Throws:

java.lang.NullPointerException - if breadcrumb is null.

leaveBreadcrumb

public static void leaveBreadcrumb(java.lang.String breadcrumb,
                   int mode)

Leaves a breadcrumb that will appear in a crash report and, optionally, session.

Call this when something interesting happens in your application. The breadcrumb will be included in different reports depending on the mode. Each crash report displays the most recent 99 breadcrumbs.

Parameters:

breadcrumb - The string to include in the crash report and sessions. If it’s longer than 2048 characters, it will be truncated. If it’s empty, no breadcrumb will be recorded.

mode - A mode from BreadcrumbVisibility.

Throws:

java.lang.NullPointerException - if breadcrumb is null.

java.lang.IllegalArgumentException - if mode is not one from BreadcrumbVisibility.

setUserData

public static void setUserData(java.lang.String key,
               java.lang.String value,
               boolean persist)

Sets a key-value pair identifier that will be included in all snapshots. The identifier can be used to add any data you wish.

The key must be unique across your application. Re-using the same key overwrites the previous value. Both the key and the value are limited to 2048 characters.

A value of null will clear the data.

If persist is set to true, this data is stored across multiple app instances. If persist is set to false, this data is only sent during this app instance, and is removed when the instance is terminated.

Once the whole application is destroyed, the non-persisted data is removed.

Parameters:

key - Your unique key.

value - Your value, or null to clear this data.

persist - Specifies if the key-value pair should persist through app terminations.

Throws:

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key or value string is longer 2048 characters.