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 appd 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 downlaodImage(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)

Method Summary

static CallTracker	beginCall(boolean isStaticMethod, java.lang.String className, java.lang.String methodName, java.lang.Object... args) Report that an info point has started.
static CallTracker	beginCall(java.lang.String className, java.lang.String methodName, java.lang.Object... args) Report 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) Leave a breadcrumb that will appear in a crash report.
static void	reportMetric(java.lang.String name, long value) Report 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 NOTE: The name can contain only alphanumeric characters and spaces.
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

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 - New app 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 - Application key.

context - 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 - Application key.

context - Context of your application.

collectorURL - Valid app dynamics 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 - Application key.

context - Context of your application.

debugEnabled - true to enable agent logging.

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 - Application key.

context - Context of your application.

collectorURL - Valid app dynamics collector url.

debugEnabled - true to enable agent logging.

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 - 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)

Report metric value for the given name.

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

Parameters:

name - name of the metric key

value - long 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 - 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 - 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)

Report that an info point has started.

Parameters:

className - Class containing the info point method.

methodName - name of the method that started execution.

args - 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)

Report that an info point has started.

Parameters:

isStaticMethod - true if the method being reported is static.

className - Class containing the info point method.

methodName - name of the method that started execution.

args - 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)

Report that an info point has ended.

If tracker is null, this method does nothing.

Parameters:

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

returnValue - Value returned by the method invocation. (can be null)

endCall

public static void endCall(CallTracker tracker)

Deprecated. Instead, use: CallTracker.reportCallEnded()

Report that an info point has ended.

Parameters:

tracker - 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:

A tracking object.

Throws:

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

leaveBreadcrumb

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

Leave 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.

Parameters:

breadcrumb - A 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.

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 - true to persist through app destroys

Throws:

java.lang.NullPointerException - if key is null.

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