Customize the Xamarin Instrumentation

The following sections show you how to use the Xamarin SDK to customize your instrumentation.

Because the agent stores data about events in a local buffer before reporting the information, you are recommended to use the APIs with discretion.

Track Calls

You can instrument methods to see how often the instrumented a method is invoked and how long it takes to run. To do this, add a call at the beginning and end of the method you'd like to instrument.

In the example below, the code executed in the constructor for the class ShoppingCart will be tracked and reported. In your own code, start tracking calls by specifying the class and method in BeginCall and then complete the tracking and report the data by calling ReportCallEnded.

using AppDynamics.Agent;
...
public class ShoppingCart {
    public ShoppingCart() {
        
        // Code to create the shopping cart 
    }
    void CheckOut(int custId, int transactionId) {
      var tracker = Instrumentation.BeginCall("ShoppingCart", "CheckOut", custId, transactionId);
       // The code placed here will be tracked and reported.
       tracker.ReportCallEnded();
    }
}

Timing Events

Sometimes you want to time an event in your application that spans multiple methods. You can do this by calling StartTimerWithName when the event starts, and then StopTimerWithName when it ends. For example, to track the time a user spends viewing a screen, the instrumentation might look something like the following:

using AppDynamics.Agent;
...
async private void StartCapturePreview_Click(object sender, RoutedEventArgs e) {
    capturePreview.Source = captureManager;
    Instrumentation.StartTimerWithName("CapturePreview");
    await captureManager.StartPreviewAsync();
}
async private void StopCapturePreview_Click(object sender, RoutedEventArgs e) {
    await captureManager.StopPreviewAsync();
    Instrumentation.StopTimerWithName("CapturePreview");
} 

Report Metrics

To report other types of data, you can use a metric. The metric name should only contain alphanumeric characters and spaces. Illegal characters are replaced by their ASCII hex value. The metric value must be a long integer.

The snippet below shows how you might report a metric.

using AppDynamics.Agent;
...
Instrumentation.ReportMetricWithName("Database Rows", 5123);

Add Tracking to HTTP Requests

Semi-automatic HTTP Tracking

The HttpMessageHandler handles all the tracking and error handling. It can also include other inner handlers if you are already using a custom HttpMessageHandler for other purposes, such as for logging.

To add semi-automatic tracking, instantiate a HttpClient and pass the HttpRequestTrackerHandler:

var client = new HttpClient(new HttpRequestTrackerHandler());

Then, all the requests sent using the client will be already instrumented: 

 response = await client.GetAsync(uri); 

If you already have HttpMessageHandler passed to the HttpClient (for example, adding a logging handler), you must instantiate HttpRequestTrackerHandler and pass the existing handler to the constructor:

var loggingHandler = new MyLoggingHandler();
var client = new HttpClient(new HttpRequestTrackerHandler(loggingHandler)); 

C#

Manual HTTP Tracking 

You can manually report a network request using the AppDynamics.Agent.HTTPRequestTracker class.

The example below uses HTTPRequestTracker with the System.Net.Http.HttpClient class. The tracker object synchronously captures and reports the network request as well as any network errors.

using AppDynamics.Agent;
...
public async Task<string> Fetch(Uri uri) {
  var client = new HttpClient();
  // Create AppDynamics Tracker
  var tracker = HTTPRequestTracker.Create(uri);
  // Add AppDynamics Server Correlation Headers
  foreach (var header in ServerCorrelationHeaders.Generate) {
      // Each header could have multiple values
      foreach (var value in header.Value) {
          client.DefaultRequestHeaders.Add(header.Key, value);
      }
  }
  HttpResponseMessage response = null;
  try {
      response = await client.GetAsync(uri);
  } catch (Exception ex) {
      // Capture any network errors.
      tracker.Exception = ex;
      tracker.ReportDone();
      throw ex; //you decide to throw it or not
  }
  if (!response.Equals(null)) {
      // Capture request information such as the 
      // status code, status message, and headers.
      tracker.ResponseCode = (int)response.StatusCode;
      tracker.StatusLine = response.ReasonPhrase;
      tracker.ResponseHeaderFields = response.Headers;
      tracker.ReportDone();
      return await response.Content.ReadAsStringAsync();
   }
   return null;
}

Leave Breadcrumbs

You can leave breadcrumbs to mark interesting events. For example, if your application crashes, the breadcrumbs you left with be displayed in the crash report and could provide context. You can also configure the breadcrumb to appear in sessions.

The following is the method signature for leaving breadcrumbs:

static void AppDynamics.Agent.Instrumentation.LeaveBreadcrumb(string breadcrumb, BreadcrumbVisibility mode)

You use the mode to set the visibility of the breadcrumb. The visibility defines where you will see the breadcrumb in the Controller UI. The value of mode can be one of the following:

• BreadcrumbVisibility.CrashesOnly – The breadcrumb will only appear in crash snapshots.
• BreadcrumbVisibility.CrashesAndSessions  – The breadcrumb will appear in crash snapshots and sessions.

Thus, you would use the method below to set breadcrumbs that are only reported in crash reports:

using AppDynamics.Agent;
...
Instrumentation.LeaveBreadcrumb("GetUserInfo", BreadcrumbVisibility.CrashesOnly);

If you would like to see the breadcrumb in crash reports and sessions: 

using AppDynamics.Agent;
...
Instrumentation.LeaveBreadcrumb("GetUserInfo", BreadcrumbVisibility.CrashesAndSessions);

Change the App Key

You can use the Xamarin Agent API to dynamically change the EUM app key. You receive the EUM App Key when creating a mobile app in the Controller UI. See Set Up and Access Mobile RUM for information about getting the EUM App Key.

The API to change app keys is available through the Instrumentation class. 

Instrumentation.ChangeAppKey("NEW-APP-KEY");

Disable the Agent to Stop Sending User Data to the Collector

You can disable the agent to stop sending all data to the collector while the agent is initialized and running. For example, you can disable the agent if your app has an option for users to opt-out of monitoring for privacy reasons.

shutdownAgent

The shutdownAgent call stops outgoing data to the collector, and does not persist data on the device.

using AppDynamics.Agent; 
...
Instrumentation.shutdownAgent();

• The call only stops the traffic out of the agent.
• Once the agent has been initialized, the call cannot be removed, and a license will have been consumed.
• If you want to make this state permanent for a device, add code in UserDefaults to save the state and use that flag to conditionally initialize the agent in your code.

restartAgent

To re-enable the agent and reverse shutdownAgent, use restartAgent.

using AppDynamics.Agent; 
...
Instrumentation.restartAgent();

• This call will respect the server side calls that can remotely shutdown the agent in a similar way. 
• The call is only in effect while the app is running.
• The call will be ignored if the agent has been remotely disabled.
• If the call is removed from memory and the app restarts, or the device is rebooted, the agent will be initialized as

Report Errors and Exceptions

You can report exceptions using the method reportError from the Instrumentation class. Reported exceptions will appear in session details.

You can also set one of the severity levels below for an issue. With the severity level, you can filter errors in the Code Issues Dashboard or Code Issues Analyze.

• ErrorSeverityLevel.INFO
• ErrorSeverityLevel.WARNING

• ErrorSeverityLevel.CRITICAL

The example below uses the API to report possible exceptions and sets the severity level to ErrorSeverityLevel.CRITICAL (critical) when writing to a file

using AppDynamics.Agent;
...
try {
    // possible exception //
}
catch (Exception e){
    Instrumentation.ReportError(exception, ErrorSeverityLevel.CRITICAL);
}

Report Aggregate Exceptions as Crashes

You can configure the Xamarin Agent to report aggregate exceptions (handled and unhandled) as crashes by setting the boolean property EnableAggregateExceptionHandling to true. When the property is set to false, only unhandled exceptions are reported. The default value is false.

The following code example configures the Xamarin Agent to report aggregate exceptions (handled and unhandled) as crashes.

using AppDynamics.Agent;
...
var config = AppDynamics.Agent.AgentConfiguration.Create(<EUM_APP_KEY>);
AppDynamics.Agent.Instrumentation.EnableAggregateExceptionHandling = true;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
...

Disable Crash Reporting

Crash reporting is enabled by default, but you can manually disable crash reporting through the instrumentation configuration. If you are using other crash reporting tools, you might disable crash reporting to minimize conflicts and optimize the crash report results. 

You can disable crash reporting by configuring the instrumentation with the crashReportingEnabled property as shown in the following:

var config = AgentConfiguration.Create(<EUM_APP_KEY>);
config.CrashReportingEnabled = false;
Instrumentation.InitWithConfiguration(config);

Add a Crash Reporting Callback

You may want to make crash report information (that the Xamarin Agent collects) available to other parts of your code, such as to Google Analytics. To enable passing on summary crash information, you can set up a crash report runtime callback:

1. To get a callback when the Xamarin Agent detects and then reports a crash, subscribe to the following event that is a part of the IAgentConfiguration interface:

   event EventHandler<IEnumerable<CrashReportSummary>> OnCrash; 

   C#

   The OnCrash event is raised during the next initialization of the Xamarin Agent after a crash has occurred. This event is raised on your app's UI thread, so any work should be done on a separate work thread.

2. The Xamarin Agent sends a collection of crash report summaries instead of an individual callback in the event that there is more than one crash, producing multiple crash report summaries. Each CrashReportSummary has the following properties:

   • ExceptionName: useful for quick identification of the crash
   • ExceptionReason: useful for quick identification of the crash
   • ExceptionId: useful to look up the crash in the Controller UI
   

   If you are sending the information to another analytics tool, such as Google Analytics, we recommend to include all three properties:

   public class CrashReportSummary
   {
       public string ExceptionId { get; }
       public string ExceptionName { get; }
       public string ExceptionReason { get; }
   }

   C#

Example

For example, to print the crash information to the console, you could subscribe to the OnCrash event like this:

IAgentConfiguration config = AgentConfiguration.Create(appKey);
config.OnCrash += (sender, crashReportSummaries) =>
{
    foreach (var crashReportSummary in crashReportSummaries) {
        Console.WriteLine($"Crash Detected: {crashReportSummary.ExceptionName}: {crashReportSummary.ExceptionReason} ({crashReportSummary.ExceptionId})");
    }
};
Instrumentation.InitWithConfiguration(config); 

Programmatically Control Sessions 

By default, a mobile session ends after a period of user inactivity. For example, when a user opens your application, the session begins and only ends after the user stops using the app for a set period of time. When the user begins to use the application again, a new session begins. 

Instead of having a period of inactivity to define the duration of a session, however, you can use the following API to programmatically control when sessions begin and end:

static void AppDynamics.Agent.Instrumentation.StartNextSession()

Example of a Programmatically Controlled Session

In the example below, the current session ends and a new one begins when an item is bought.

using AppDynamics.Agent;
...
public async Task BuySaleItemAsync(SaleItem item)
{
    try 
    {
        bool buySucceeded = await this.MobileService.InvokeApiAsync<SaleItem, bool>("buy", item);
        if (buySucceeded)
        {
            await UserDialogs.Instance.AlertAsync("Thanks for buying this item");
            Instrumentation.StartNextSession();
        }
    }
    catch (Exception e)
    {
        Debug.WriteLine(@"Unexpected error {0}", e.Message);
    }
}

Start and End Session Frames

You can use the ISessionFrame API to create session frames that will appear in the session activity. Session frames provide context for what the user is doing during a session. With the API, you can improve the names of user screens and chronicle user flows within a business context. 

Use Cases

The following are common use cases for the ISessionFrame API:

• One screen performs multiple functions and you want more granular tracking of the individual functions.
• A user flow spans multiple screens or user interactions. For example, you could use the API to create the session frames "Login", "Product Selection", and "Purchase" to chronicle the user flow for purchases.
• You want to capture dynamic information based on user interactions to name session frames, such as an order ID.

ISessionFrame API

The table below lists the two methods and one property you can use with session frames. In short, you start a session frame with StartSessionFrame and then use the returned ISessionFrame object to rename and end the session frame. 

static ISessionFrame StartSessionFrame(string sessionFrameName)

string Name

static void End()

Session Frame Example

In the following example, the ISessionFrame API is used to track user activity during the checkout process.

using AppDynamics.Agent;
...
 
namespace ShoppingApp {
    public partial class ShoppingCart : ContentPage {
        private ISessionFrame sessionFrame;
        private string orderId;
        ...
        void checkoutCartButtonClicked(object sender, EventArgs e) {
            // The checkout starts when the user clicks the checkout button.
            // This may be after they have updated quantities of items in their cart, etc.
            sessionFrame = Instrumentation.StartSessionFrame("Checkout");
        }
        void confirmOrderButtonClicked(object sender, EventArgs e) {
            // Once they have confirmed payment info and shipping information, and they
            // are clicking the "Confirm" button to start the backend process of checking out,
            // we may know more information about the order itself, such as an order ID.
            sessionFrame.Name = $"Checkout: Order ID {this.orderId}";
        }
        void processOrderCompleted(object sender, EventArgs e) {
            // Once the order is processed, the user is done "checking out" so we end
            // the session frame.
            sessionFrame.End();
        }
        void checkoutCancelled(object sender, EventArgs e) {
            // If they cancel or go back, you'll want to end the session frame also, or else
            // it will be left open and appear to have never ended.
            sessionFrame.End();
        }
    }
}

Add User Data

You can set a key/value pair of strings to record important events or information. Below is the method signature for setting user data:

static void AppDynamics.Agent.Instrumentation.SetUserData(string key, string value)

using AppDynamics.Agent;
...
void LogInUser(UserCredentials) {
   // Log in user
   ...
   // Set user data with the user name.
   Instrumentation.SetUserData("user_id", UserCredentials.ID);
}

You can also set user data with values of other types (long, boolean, double, DateTime) using the following methods:

• SetUserDataBoolean

• SetUserDataDate

• SetUserDataDouble

• SetUserDataLong

To remove user data, use the following methods:

• RemoveUserData
• RemoveUserDataBoolean
• RemoveUserDataDate
• RemoveUserDataDouble
• RemoveUserDataLong

Set the Logging Level (Optional)

You can set the logging level with the configuration LoggingLevel as part of the class AgentConfiguration.

You can set LoggingLevel to one of the levels listed in the table below.

For example:

var config = AppDynamics.Agent.AgentConfiguration.Create("<#Your App Key#>");
config.LoggingLevel = AppDynamics.Agent.LoggingLevel.All;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config); 

Transform URLs for Network Requests

Implement the Network Request Callback

The callback that modifies or ignore specific URLs should be assigned to the Func delegate below. 

The callback method OnNetworkRequest is synchronous, so we recommend that you return from the function quickly.

public Func<IHttpRequestTracker, bool> OnNetworkRequest { get; set; } 

Transforming URLs

To transform URLs, the OnNetworkRequest method should:

1.  Identify specific URLs using techniques such as regex or pattern matching.

   

   This first step is optional because you can choose to transform the URLs of all network requests.

2. Modify the URL property of the IHttpRequestTracker object.
3. Assign a valid URL to the url property. Modifying other properties of the  IHttpRequestTracker object will be ignored.
4. Return true.

For example:

public static bool NetworkRequestCallback(IHttpRequestTracker tracker)
{
    var maskUrl = new Uri("http://networkrequest-mask.com/");
    tracker.Uri = maskUrl;
    return true;
}

Transforming Sensitive URLs

You may want to identify and transform URLs that contain sensitive information.

For example:

public static bool NetworkRequestCallback(IHttpRequestTracker tracker)
{
    var urlString = tracker.Uri.ToString();    
    if (urlString.Contains("accountInfo"))
    {
        tracker.Uri = new Uri("http://customer-account.com/"); 
    }
    return true; 
}

Ignoring URLs

If the onNetworkRequest method returns false, the beacon is dropped. Generally, the process for ignoring beacons is:

1. Identify specific URLs using techniques such as regex or pattern matching.
2. Return false.

To ignore specific URLs, you would identify network requests that you didn't want to monitor and return false to ignore the network request.

For example:

public static bool NetworkRequestCallback(IHttpRequestTracker tracker)
{
    if (tracker.Uri.ToString().Contains("avatar"))
    {
        //ignore calls for avatars
        return false; 
    }
    return true; 
}

To ignore all network requests, implement the following:

public static bool NetworkRequestCallback(IHttpRequestTracker tracker)
{
    return false; 
}

Register a Network Request Callback

To register a network request callback:

1. Define your own method to handle the callback:

   public static bool NetworkRequestCallback(IHttpRequestTracker tracker)
   {
       return true; 
   }

   C#

2. Pass it during the AgentConfiguration initialization phase:

   IAgentConfiguration config = AgentConfiguration.Create(appKey);
   config.OnNetworkRequest += NetworkRequestCallback; //Register the Callback
   Instrumentation.InitWithConfiguration(config);

   C#

3. Or you can use an anonymous function:

   IAgentConfiguration config = AgentConfiguration.Create(appKey);
   config.OnNetworkRequest += (IHttpRequestTracker tracker) =>
   {
       return true; 
   };
   Instrumentation.InitWithConfiguration(config);

   C#

Configure and Take Screenshots

By default, mobile screenshots are enabled on the agent-side but disabled on the Controller-side. These screenshots appear in the Controller in the Sessions Details dialog. To programmatically take manual screenshots, you must enable screenshots in the Controller UI and add the Screenshot API below. 

Instrumentation.TakeScreenshot();Disable Screenshots

The takeScreenshot() function limits screenshots to a maximum of 1 screenshot per 10 seconds.

Disable Screenshots

You can disable screenshots from the Controller UI or with the Xamarin SDK. To disable screenshots with the Xamarin SDK, set the property ScreenshotsEnabled of the IAgentConfiguration object to false:

IAgentConfiguration config = AgentConfiguration.Create(appKey); config.ScreenshotsEnabled = false; Instrumentation.InitWithConfiguration(config);

Block and Unblock Screenshots

You can also use the Xamarin SDK to block screenshots from being taken during the execution of a code block. This just temporarily blocks screenshots from being taken until you unblock screenshots. This enables you to stop taking screenshots in situations where users are entering personal data, such as on login and account screens.

The Instrumentation class provides the methods blockScreenshots() and unblockScreenshots() to block and unblock screenshots. 

If screenshots are disabled through the property ScreenshotsEnabled of the IAgentConfiguration object or through the Controller UI, these methods have no effect. You can also check the Instrumentation.ScreenshotsBlocked property to check if screenshots are being blocked.

public void LoginUser() 
{ 
	if (!Instrumentation.ScreenshotsBlocked) 
	{ 
		Instrumentation.BlockScreenshots(); 
	} 
	LoginCredentials credentials = UserLogin.GetCredentials(); 


	if (credentials.Authorized) 	
	{
		RedirectToProfile(credentials.user); 
		Instrumentation.UnblockScreenshots(); 
	} 
}

Xamarin SDK Documentation

For the complete SDK API documentation, see the latest Xamarin SDK documentation or the previous versions listed below:

• https://sdkdocs.appdynamics.com/xamarin-sdk/21.6/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/21.5/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/21.2/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/20.11/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/2020.10/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/2020.4/html/
• https://sdkdocs.appdynamics.com/xamarin-sdk/2020.3/html/