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
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
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.
You can also report custom timers and metrics using the following API(s):
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);
}
});
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.
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:
Modifier and Type | Field and Description |
---|---|
static com.appdynamics.eumagent.runtime.beacons.HybridAgentInfo |
hybridAgentInfo |
static boolean |
initializationStarted |
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.
|
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 |
disableInstrumentation(long disableUntil) |
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 void |
restartAgent() |
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 |
shutdownAgent() |
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 |
startFromHybrid(AgentConfiguration agentConfiguration,
java.lang.String hat,
java.lang.String hav)
This method is called from a hybrid agent and calls the main start method below after setting the hybrid agent type and version
|
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.
|
public static com.appdynamics.eumagent.runtime.beacons.HybridAgentInfo hybridAgentInfo
public static final int LOGGING_LEVEL_NONE
No logs printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)
public static final int LOGGING_LEVEL_INFO
Only sparse important logs are printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)
public static final int LOGGING_LEVEL_VERBOSE
All logs are printed. Used in AgentConfiguration.Builder.withLoggingLevel(int)
public static final int MAX_USER_DATA_STRING_LENGTH
Maximum accepted length of user data strings, applies to both keys and values.
public static final int VALID_INTERACTION_CAPTURE_MODES
Valid capture modes for UI instrumentation.
public static volatile boolean initializationStarted
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.
appKey
- The new application key to use for reporting beacons.java.lang.IllegalArgumentException
- if appKey is null or empty.public static void start(java.lang.String appKey, android.content.Context context)
Initialize the agent with the given application key and Context
.
appKey
- The application key.context
- The Context
of your application.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.@Deprecated public static void start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL)
start(AgentConfiguration)
Initialize the agent with the given application key and Context
.
appKey
- The application key.context
- The Context
of your application.collectorURL
- The valid AppDynamics collector url.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.@Deprecated public static void start(java.lang.String appKey, android.content.Context context, boolean debugEnabled)
start(AgentConfiguration)
Initialize the agent with the given application key and Context
.
appKey
- The application key.context
- The Context
of your application.debugEnabled
- Specifies if agent info logging should be enabled.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.@Deprecated public static void start(java.lang.String appKey, android.content.Context context, java.lang.String collectorURL, boolean debugEnabled)
start(AgentConfiguration)
Initialize the agent with the given application key and Context
.
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.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.public static void startFromHybrid(AgentConfiguration agentConfiguration, java.lang.String hat, java.lang.String hav)
This method is called from a hybrid agent and calls the main start method below after setting the hybrid agent type and version
public static void start(AgentConfiguration agentConfiguration)
Initialize the agent with the given configuration.
agentConfiguration
- The agent configuration to use.java.lang.IllegalArgumentException
- if configuration is invalid.java.lang.IllegalStateException
- if AppDynamics compile-time instrumentation has not been added to the application.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.
name
- The name of the metric key.value
- The value reported for the given key.@Deprecated public static void reportError(java.lang.Throwable throwable)
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.
throwable
- the throwable to reportpublic 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:
throwable
- the throwable to reportpublic 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.
name
- The name of the timer.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.
name
- The name of the timer.public static SessionFrame startSessionFrame(java.lang.String sessionFrameName)
Starts a Session Frame.
sessionFrameName
- The name of the session frame that will appear in the UI.SessionFrame
object is returned which should be retained for further operations.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)
public static CallTracker beginCall(java.lang.String className, java.lang.String methodName, java.lang.Object... args)
Reports that an info point has started.
className
- The class containing the info point method.methodName
- The name of the method that started execution.args
- The arguments passed to this method.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.
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.public static void endCall(CallTracker tracker, java.lang.Object returnValue)
CallTracker.reportCallEndedWithReturnValue(Object)
Reports that an info point has ended.
If tracker is null, this method does nothing.
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.public static void endCall(CallTracker tracker)
CallTracker.reportCallEnded()
Reports that an info point has ended.
tracker
- The tracker that was obtained by calling beginCall(boolean, String, String, Object...)
/ beginCall(String, String, Object...)
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
url
- The URL being requested.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.
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.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.
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
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.
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.
public static boolean screenshotsBlocked()
See blockScreenshots()
.
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.
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.
crashDump
- Json string of the crash dump.type
- crash report type.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.
key
- Your unique key.value
- Your value, or null
to clear this data.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.
key
- Your unique key.value
- Your value, or null
to clear this data.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.
key
- Your unique key.value
- Your value, or null
to clear this data.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.
key
- Your unique key.value
- Your value, or null
to clear this data.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.
key
- Your unique key.value
- Your value, or null
to clear this data.public static void shutdownAgent()
public static void restartAgent()
public static void disableInstrumentation(long disableUntil)