NewRelic.Xamarin.Plugin 1.0.1

<a href="https://opensource.newrelic.com/oss-category/#community-plus"><picture><source media="(prefers-color-scheme: dark)" srcset="https://github.com/newrelic/opensource-website/raw/main/src/images/categories/dark/Community_Plus.png"><source media="(prefers-color-scheme: light)" srcset="https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Community_Plus.png"><img alt="New Relic Open Source community plus project banner." src="https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Community_Plus.png"></picture></a>

New Relic Xamarin Plugin

This plugin allows you to instrument Xamarin Forms, iOS and Android apps with help of native New Relic Android and iOS Bindings. The New Relic SDKs collect crashes, network traffic, and other information for hybrid apps using native components.

Features

• Capture Android and iOS Crashes
• Network Request tracking
• Distributed Tracing
• Pass user information to New Relic to track user sessions
• Screen Tracking
• Offline Monitoring for Events and Exceptions
• Capture Background Events when app is in background

Current Support:

• Android API 24+
• iOS 10
• Depends on New Relic iOS/XCFramework and Android agents
• This plugin targets .NET standard 2.0 which means should also work with
  • Xamarin.Android 8.0 and newer
  • Xamarin.iOS 10.14 and newer

Installation

Install NewRelic plugin into your Xamarin project by adding as NuGet Package NewRelic.Xamarin.Plugin.

Open your solution, select the project you want to add NewRelic package to and open its context menu. Unfold "Add" and click "Add NuGet packages...".

On your iOS app, you will also need to add NuGet package NewRelic.Xamarin.iOS.Binding to the dependencies.

Xamarin Setup

1. Open your App.xaml.cs and add the following code to launch NewRelic Plugin (don't forget to put proper application tokens):

using NewRelic.Xamarin.Plugin;
...
    public App ()
    {
      InitializeComponent();

      MainPage = new MainPage();
      Application.Current.PageAppearing += OnPageAppearing;
      Application.Current.PageDisappearing += PageDisappearing;

      CrossNewRelicClient.Current.HandleUncaughtException();
      CrossNewRelicClient.Current.TrackShellNavigatedEvents()
      // Set optional agent configuration    
      // Options are: crashReportingEnabled, loggingEnabled, logLevel, collectorAddress, crashCollectorAddress,analyticsEventEnabled, networkErrorRequestEnabled, networkRequestEnabled, interactionTracingEnabled,webViewInstrumentation, fedRampEnabled,offlineStorageEnabled,newEventSystemEnabled,backgroundReportingEnabled
      // AgentStartConfiguration agentConfig = new AgentStartConfiguration(crashReportingEnabled:false);
      if (Device.RuntimePlatform == Device.Android) 
      {
        CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE>");
        // Start with optional agent configuration
        // CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE", agentConfig);
      } else if (Device.RuntimePlatform == Device.iOS)
      {
        CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE>");
        // Start with optional agent configuration 
        // CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE", agentConfig);
      }
    }

Android Setup

1. Open Properties/AndroidManifest.xml for your Android App and add the following permissions:

	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
	<uses-permission android:name="android.permission.INTERNET" />

Screen Tracking Events

The Xamarin mobile plugin allows you to track navigation events within the .NET MAUI Shell. In order to do so, you only need to call:

    CrossNewRelicClient.Current.TrackShellNavigatedEvents();

It is recommended to call this method along when starting the agent. These events will only be recorded after navigation is complete. You can find this data through the data explorer in MobileBreadcrumb under the name ShellNavigated or by query:

    SELECT * FROM MobileBreadcrumb WHERE name = 'ShellNavigated' SINCE 24 HOURS AGO

The breadcrumb will contain three attributes:

• Current: The URI of the current page.
• Source: The type of navigation that occurred.
• Previous: The URI of the previous page. Will not exist if previous page was null.

Usage

See the examples below, and for more detail, see New Relic iOS SDK doc or Android SDK .

CrashNow(string message = "") : void;

Throws a demo run-time exception on Android/iOS to test New Relic crash reporting.

    CrossNewRelicClient.Current.CrashNow();

CurrentSessionId() : string;

Returns ID for the current session.

    string sessionId = CrossNewRelicClient.Current.CurrentSessionId();

StartInteraction(string interactionName): string;

Track a method as an interaction.

EndInteraction(string interactionId): void;

End an interaction (Required). This uses the string ID for the interaction you want to end. This string is returned when you use startInteraction().

    HttpClient myClient = new HttpClient(CrossNewRelicClient.Current.GetHttpMessageHandler());
    
    string interactionId = CrossNewRelicClient.Current.StartInteraction("Getting data from service");

    var response = await myClient.GetAsync(new Uri("https://jsonplaceholder.typicode.com/todos/1"));
    if (response.IsSuccessStatusCode)
    {
        var content = await response.Content.ReadAsStringAsync();
    } else
    {
        Console.WriteLine("Unsuccessful response code");
    }

    CrossNewRelicClient.Current.EndInteraction(interactionId);

NoticeHttpTransaction(string url, string httpMethod, int statusCode, long startTime,long endTime, long bytesSent, long bytesReceived, string responseBody): void;

Tracks network requests manually. You can use this method to record HTTP transactions, with an option to also send a response body.

    CrossNewRelicClient.Current.NoticeHttpTransaction(
      "https://newrelic.com",
      "GET",
      200,
      DateTimeOffset.Now.ToUnixTimeMilliseconds(),
      DateTimeOffset.Now.ToUnixTimeMilliseconds() + 100,
      0,
      1000,
      ""
    );

NoticeNetworkFailure(string url, string httpMethod, int statusCode, long startTime,long endTime, long bytesSent, long bytesReceived, string responseBody): void;

Records network failures. If a network request fails, use this method to record details about the failure.

    CrossNewRelicClient.Current.NoticeNetworkFailure(
      "https://fakewebsite.com",
      "GET",
      DateTimeOffset.Now.ToUnixTimeMilliseconds(),
      DateTimeOffset.Now.ToUnixTimeMilliseconds() + 100,
      NetworkFailure.Unknown
    );

RecordBreadcrumb(string name, Dictionary<string, object> attributes): bool;

This call creates and records a MobileBreadcrumb event, which can be queried with NRQL and in the crash event trail.

    CrossNewRelicClient.Current.RecordBreadcrumb("XamarinExampleBreadcrumb", new Dictionary<string, object>()
        {
            {"BreadNumValue", 12.3 },
            {"BreadStrValue", "XamBread" },
            {"BreadBoolValue", true }
        }
    );

RecordCustomEvent(string eventType, string eventName, Dictionary<string, object> attributes): bool;

Creates and records a custom event for use in New Relic Insights.

    CrossNewRelicClient.Current.RecordCustomEvent("XamarinCustomEvent", "XamarinCustomEventCategory", new Dictionary<string, object>()
        {
            {"BreadNumValue", 12.3 },
            {"BreadStrValue", "XamBread" },
            {"BreadBoolValue", true }
        }
    );

RecordMetric(string name, string category) : void;

RecordMetric(string name, string category, double value) : void;

RecordMetric(string name, string category, double value, MetricUnit countUnit, MetricUnit valueUnit) : void;

Record custom metrics (arbitrary numerical data).

    CrossNewRelicClient.Current.RecordMetric("Agent start", "Lifecycle");
    CrossNewRelicClient.Current.RecordMetric("Login Auth Metric", "Network", 78.9);
    CrossNewRelicClient.Current.RecordMetric("Request Metric", "Network", 20, MetricUnit.SECONDS, MetricUnit.OPERATIONS);

SetAttribute(string name, string value) : bool;

SetAttribute(string name, double value) : bool;

SetAttribute(string name, bool value) : bool;

Creates a session-level attribute shared by multiple mobile event types. Overwrites its previous value and type each time it is called.

    CrossNewRelicClient.Current.SetAttribute("XamarinBoolAttr", false);
    CrossNewRelicClient.Current.SetAttribute("XamarinStrAttr", "Cat");
    CrossNewRelicClient.Current.SetAttribute("XamarinNumAttr", 13.5);

IncrementAttribute(string name, float value = 1) : bool;

Increments the count of an attriubte. Overwrites its previous value and type each time it is called.

    // Increment by 1
    CrossNewRelicClient.Current.IncrementAttribute("XamarinNumAttr");
    // Increment by value
    CrossNewRelicClient.Current.IncrementAttribute("XamarinNumAttr", 12.3);

RemoveAttribute(string name) : bool;

Removes an attribute.

    CrossNewRelicClient.Current.RemoveAttribute("XamarinNumAttr");

RemoveAllAttributes() : bool;

Removes all attributes from the session.

    CrossNewRelicClient.Current.RemoveAllAttributes();

SetMaxEventBufferTime(int maxBufferTimeInSec) void;

Sets the event harvest cycle length.

    CrossNewRelicClient.Current.SetMaxEventBufferTime(200);

SetMaxEventPoolSize(int maxPoolSize): void;

Sets the maximum size of the event pool.

    CrossNewRelicClient.Current.SetMaxEventPoolSize(1500);

SetUserId(string userId): bool;

Set a custom user identifier value to associate user sessions with analytics events and attributes.

    CrossNewRelicClient.Current.SetUserId("User123");

GetHttpMessageHandler() : HttpMessageHandler;

Provides a HttpMessageHandler to instrument http requests through HttpClient.

    HttpClient myClient = new HttpClient(CrossNewRelicClient.Current.GetHttpMessageHandler());

    var response = await myClient.GetAsync(new Uri("https://jsonplaceholder.typicode.com/todos/1"));
    if (response.IsSuccessStatusCode)
    {
        var content = await response.Content.ReadAsStringAsync();
    } else
    {
        Console.WriteLine("Http request failed");
    }

AnalyticsEventEnabled(bool enabled) : void;

FOR ANDROID ONLY. Enable or disable collection of event data.

    CrossNewRelicClient.Current.AnalyticsEventEnabled(true);

NetworkRequestEnabled(bool enabled) : void;

Enable or disable reporting successful HTTP requests to the MobileRequest event type.

    CrossNewRelicClient.Current.NetworkRequestEnabled(true);

NetworkErrorRequestEnabled(bool enabled) : void;

Enable or disable reporting network and HTTP request errors to the MobileRequestError event type.

    CrossNewRelicClient.Current.NetworkErrorRequestEnabled(true);

HttpResponseBodyCaptureEnabled(bool enabled) : void;

Enable or disable capture of HTTP response bodies for HTTP error traces, and MobileRequestError events.

    CrossNewRelicClient.Current.HttpResponseBodyCaptureEnabled(true);

Shutdown(): void;

Shut down the agent within the current application lifecycle during runtime.

    CrossNewRelicClient.Current.Shutdown();

SetMaxOfflineStorageSize(int megabytes) : void

Sets the maximum size of total data that can be stored for offline storage.By default, mobile monitoring can collect a maximum of 100 megaBytes of offline storage. When a data payload fails to send because the device doesn't have an internet connection, it can be stored in the file system until an internet connection has been made. After a typical harvest payload has been successfully sent, all offline data is sent to New Relic and cleared from storage.

    CrossNewRelicClient.Current.SetMaxOfflineStorageSize(200);

LogInfo(String message) : void

Logs an informational message to the New Relic log.

    CrossNewRelicClient.Current.LogInfo("This is an informational message");

LogError(String message) : void

Logs an error message to the New Relic log.

    CrossNewRelicClient.Current.LogError("This is an error message");

LogVerbose(String message) : void

Logs a verbose message to the New Relic log.

    CrossNewRelicClient.Current.LogVerbose("This is a verbose message");

LogWarning(String message) : void

Logs a warning message to the New Relic log.

    CrossNewRelicClient.Current.LogWarning("This is a warning message");

LogDebug(String message) : void

Logs a debug message to the New Relic log.

    CrossNewRelicClient.Current.LogDebug("This is a debug message");

Log(LogLevel level, String message) : void

Logs a message to the New Relic log with a specified log level.

    CrossNewRelicClient.Current.Log(LogLevel.Info, "This is an informational message");

LogAttributes(Dictionary<string, object> attributes) : void

Logs a message with attributes to the New Relic log.

    CrossNewRelicClient.Current.LogAttributes(new Dictionary<string, object>()
        {
            {"BreadNumValue", 12.3 },
            {"BreadStrValue", "XamBread" },
            {"BreadBoolValue", true },
            {"message", "This is a message with attributes" }
        }
    );

Error reporting

This plugin provides a handler to record unhandled exceptions to New Relic. It is recommended to initialize the handler prior to starting the agent.

HandleUncaughtException(bool shouldThrowFormattedException = true) : void;

    CrossNewRelicClient.Current.HandleUncaughtException();
    if (Device.RuntimePlatform == Device.iOS)
    {
        CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE>");
    } else if (Device.RuntimePlatform == Device.Android)
    {
        CrossNewRelicClient.Current.Start("<APP-TOKEN-HERE>");
    }

This plugin also provides a method to manually record any handled exceptions as well:

RecordException(System.Exception exception) : void;

    try {
      some_code_that_throws_error();
    } catch (Exception ex) {
      CrossNewRelicClient.Current.RecordException(ex);
    }

Troubleshooting

• No Http data appears:

  • To instrument http data, make sure to use the HttpMessageHandler in HttpClient

• iOS App Crashes on Null Pointer Exception Recording

Issue

The app may crash on iOS when recording a Null Pointer Exception.

Solution

Initialize the agent in AppDelegate.cs instead of App.xaml.cs.

Implementation

Add the following code to your AppDelegate.cs file:

public override bool FinishedLaunching(UIApplication app, NSDictionary options)
{
    Mono.Runtime.RemoveSignalHandlers();
    NRIosAgent.StartWithApplicationToken("<APP-TOKEN-HERE>");
    Mono.Runtime.InstallSignalHandlers();
    return base.FinishedLaunching(app, options);
}

Additional Information For more details on handling signals and third-party crash reporters, refer to the Mono documentation on Signals and third-party crash reporters."Mono Documentation"]

Support

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:

https://discuss.newrelic.com/tags/mobile

Contribute

We encourage your contributions to improve [project name]! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

If you would like to contribute to this project, review these guidelines.

To all contributors, we thank you! Without your contribution, this project would not be what it is today.

Support

New Relic hosts and moderates an online forum where customers, users, maintainers, contributors, and New Relic employees can discuss and collaborate:

forum.newrelic.com

License

Except as described below, the newrelic-xamarin-plugin is licensed under the Apache 2.0 License.

The [New Relic XCFramework agent] (/docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/get-started/introduction-new-relic-mobile-ios/) is licensed under the [New Relic Agent Software Notice] (/docs.newrelic.com/docs/licenses/license-information/distributed-licenses/new-relic-agent-software-notice/).

The [New Relic Android agent] (github.com/newrelic/newrelic-android-agent) is licensed under the Apache 2.0.

The New Relic Xamarin Plugin may use source code from third-party libraries. When used, these libraries will be outlined in THIRD_PARTY_NOTICES.md.