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

About on-premise deployments: Some of the features described here require a minimum EUM server deployment version. Please refer to the following page for more information: https://docs.appdynamics.com/display/latest/Mobile+Agent+Version+and+Deployment+Support+Matrix

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) have 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	MAX_USER_DATA_STRING_LENGTH Maximum accepted length of user data strings, applies to both keys and values.
static int	VALID_INTERACTION_CAPTURE_MODES Valid capture modes for UI instrumentation.

Method Summary

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	blockScreenshots() Blocks screenshot capture if it is currently unblocked.
static void	changeAppKey(java.lang.String appKey) Change the app key.
static int	createCrashReport(java.lang.String crashDump, java.lang.String type) Creates a crash report of the given crash dump.
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	reportError(java.lang.Throwable throwable) Deprecated. Report error without specifying severity level is deprecated. Instead, please use reportError(Throwable, int)
static void	reportError(java.lang.Throwable throwable, int severityLevel) Reports an error that was caught.
static void	reportMetric(java.lang.String name, long value) Reports metric value for the given name.
static boolean	screenshotsBlocked() See blockScreenshots().
static void	setUserData(java.lang.String key, java.lang.String value) Sets a key-value pair identifier that will be included in all snapshots.
static void	setUserDataBoolean(java.lang.String key, java.lang.Boolean value) Sets a key-value pair identifier that will be included in all snapshots.
static void	setUserDataDate(java.lang.String key, java.util.Date value) Sets a key-value pair identifier that will be included in all snapshots.
static void	setUserDataDouble(java.lang.String key, java.lang.Double value) Sets a key-value pair identifier that will be included in all snapshots.
static void	setUserDataLong(java.lang.String key, java.lang.Long value) 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) Deprecated. Instead, use start(AgentConfiguration)
static void	start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL) Deprecated. Instead, use start(AgentConfiguration)
static void	start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL, boolean debugEnabled) Deprecated. Instead, use start(AgentConfiguration)
static void	startNextSession() Starts next session and ends the current session.
static SessionFrame	startSessionFrame(java.lang.String sessionFrameName) Starts a Session Frame.
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.
static void	takeScreenshot() Asynchronously takes a screenshot of the current Activity’s window.
static void	unblockScreenshots() Unblocks screenshot capture if it is currently blocked.

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

MAX_USER_DATA_STRING_LENGTH

public static final int MAX_USER_DATA_STRING_LENGTH

Maximum accepted length of user data strings, applies to both keys and values.

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

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

Deprecated. Instead, use start(AgentConfiguration)

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

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

Deprecated. Instead, use start(AgentConfiguration)

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

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

Deprecated. Instead, use start(AgentConfiguration)

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.

The name should contain only alphanumeric characters and spaces.

Illegal characters shall be replaced by their ASCII hex value.

WARNING: pre-4.3 agents threw an exception on illegal characters.

Parameters:

name - The name of the metric key.

value - The value reported for the given key.

reportError

@Deprecated
public static void reportError(java.lang.Throwable throwable)

Deprecated. Report error without specifying severity level is deprecated. Instead, please use reportError(Throwable, int)

Reports an error that was caught.

This can be called in catch blocks to report interesting errors that you want to track.

ErrorSeverityLevel.WARNING will be used as default severity level.

WARNING: Throwables are mutable, and the data is extracted from the throwable asynchronously, so any modifications to the throwable after calling this method will likely be reported.

Parameters:

throwable - the throwable to report

reportError

public static void reportError(java.lang.Throwable throwable,
                               int severityLevel)

Reports an error that was caught.

This can be called in catch blocks to report interesting errors that you want to track.

WARNING: Throwables are mutable, and the data is extracted from the throwable asynchronously, so any modifications to the throwable after calling this method will likely be reported.

WARNING: SeverityLevel can only be following levels. Error will reported with ErrorSeverityLevel.WARNING when passing an invalid severity level.

Valid severity levels:

• ErrorSeverityLevel.INFO
• ErrorSeverityLevel.WARNING
• ErrorSeverityLevel.CRITICAL

Parameters:

throwable - the throwable to report

startTimer

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

Starts a global timer with the given name.

The name should contain only alphanumeric characters and spaces.

Illegal characters shall be replaced by their ASCII hex value.

WARNING: pre-4.3 agents threw an exception on illegal characters.

Parameters:

name - The name of the timer.

stopTimer

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

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

The name should contain only alphanumeric characters and spaces.

Illegal characters shall be replaced by their ASCII hex value.

WARNING: pre-4.3 agents threw an exception on illegal characters.

Parameters:

name - The name of the timer.

startSessionFrame

public static SessionFrame startSessionFrame(java.lang.String sessionFrameName)

Starts a Session Frame.

Parameters:

sessionFrameName - The name of the session frame that will appear in the UI.

Returns:

A SessionFrame object is returned which should be retained for further operations.

Since:

5.1

startNextSession

public static void startNextSession()

Starts next session and ends the current session.

The session started using this API may be ended by inactivity timeout set in the Application Configuration, before the next call to this API.

This API makes some practical assumptions about session lengths among end users. Excessive use of this API will cause sessions to be throttled (excessive use is >10 calls per minute per agent, subject to change)

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.

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.

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.

NOTE: If URL is null, no request will be reported

Parameters:

url - The URL being requested.

Returns:

The tracking object.

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.

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. If invalid, defaults to BreadcrumbVisibility.CRASHES_ONLY

unblockScreenshots

public static void unblockScreenshots()

Unblocks screenshot capture if it is currently blocked. Otherwise, this has no effect.

If screenshots are disabled through AgentConfiguration.Builder.withScreenshotsEnabled(boolean) or through the controller UI, this method has no effect.

If screenshots are set to manual mode in the controller UI, this method unblocks for manual mode only.

WARNING: This will unblock capture for the entire app.

The user is expected to manage any possible nesting issues that may occur if blocking and unblocking occur in different code paths.

See blockScreenshots()

blockScreenshots

public static void blockScreenshots()

Blocks screenshot capture if it is currently unblocked. Otherwise, this has no effect..

If screenshots are disabled through AgentConfiguration.Builder.withScreenshotsEnabled(boolean) or through the controller UI, this method has no effect.

WARNING: This will block capture for the entire app.

The user is expected to manage any possible nesting issues that may occur if blocking and unblocking occur in different code paths.

See unblockScreenshots()

screenshotsBlocked

public static boolean screenshotsBlocked()

See blockScreenshots().

Returns:

boolean whether screenshot capture is blocked

takeScreenshot

public static void takeScreenshot()

Asynchronously takes a screenshot of the current Activity’s window.

If screenshots are disabled through AgentConfiguration.Builder.withScreenshotsEnabled(boolean) or through the controller UI, this method does nothing.

This will capture everything, including personal information, so you must be cautious of when to take the screenshot.

These screenshots will show up in the Sessions screen for this user.

The screenshots are taken on a background thread, compressed, and only non-redundant parts are uploaded, so it is safe to take many of these without impacting performance of your application.

createCrashReport

public static int createCrashReport(java.lang.String crashDump,
                                    java.lang.String type)

Creates a crash report of the given crash dump. This crash report will be reported to collector when application restarts.

This is an internal API and subject to change without notice.

Parameters:

crashDump - Json string of the crash dump.

type - crash report type.

Returns:

status, 0 for success, anything else indicates an error.

setUserData

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

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. The key namespace is distinct for each user data type. Re-using the same key overwrites the previous value. The key is limited to MAX_USER_DATA_STRING_LENGTH characters.

A value of null will clear the data. The value is limited to MAX_USER_DATA_STRING_LENGTH characters.

This information is not persisted across application runs. Once the application is destroyed, the user data is cleared.

Parameters:

key - Your unique key.

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

setUserDataLong

public static void setUserDataLong(java.lang.String key,
                                   java.lang.Long value)

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. The key namespace is distinct for each user data type. Re-using the same key overwrites the previous value. The key is limited to MAX_USER_DATA_STRING_LENGTH characters.

A value of null will clear the data.

This information is not persisted across application runs. Once the application is destroyed, the user data is cleared.

Parameters:

key - Your unique key.

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

setUserDataBoolean

public static void setUserDataBoolean(java.lang.String key,
                                      java.lang.Boolean value)

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. The key namespace is distinct for each user data type. Re-using the same key overwrites the previous value. The key is limited to MAX_USER_DATA_STRING_LENGTH characters.

A value of null will clear the data.

This information is not persisted across application runs. Once the application is destroyed, the user data is cleared.

Parameters:

key - Your unique key.

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

setUserDataDouble

public static void setUserDataDouble(java.lang.String key,
                                     java.lang.Double value)

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. The key namespace is distinct for each user data type. Re-using the same key overwrites the previous value. The key is limited to MAX_USER_DATA_STRING_LENGTH characters.

A value of null will clear the data.

The value has to be finite. Attempting to set infinite or NaN value, will clear the data.

This information is not persisted across application runs. Once the application is destroyed, the user data is cleared.

Parameters:

key - Your unique key.

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

setUserDataDate

public static void setUserDataDate(java.lang.String key,
                                   java.util.Date value)

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. The key namespace is distinct for each user data type. Re-using the same key overwrites the previous value. The key is limited to MAX_USER_DATA_STRING_LENGTH characters.

A value of null will clear the data.

This information is not persisted across application runs. Once the application is destroyed, the user data is cleared.

Parameters:

key - Your unique key.

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