Introduction to New Relic Mobile (Unity)

Legacy
feature

This document is for historical reference. Unity is no longer supported for new customers.

Contents

Monitor mobile app performance

The New Relic Unity plugin allows Unity developers to embed a New Relic Mobile agent (iOS or Android) in a Unity app build for mobile devices to monitor your app's performance. The plugin is written in C#, but it includes the native iOS and Android agents that embed the appropriate files for your build.

Features
New Relic Mobile Features
Comprehensive performance data

View your mobile app's performance Overview page for summary information about active sessions, or drill down to detailed information, including (note limitations below):

Detailed network views
  • Available by using the API to track custom network requests
  • For iOS apps, receive automatic instrumentation for networking for any parts of the app that are native and non-Unity (using standard Apple networking components such as NSURLConnection)
  • Examine HTTP errors and network failures (such as DNS lookups, timeouts, SSL errors, etc.) and server error traces.
Usage details at a glance
  • Compare performance between versions of your app with detailed information for memory, CPU (iOS only), interaction speed, network requests per minute, and network failures.
  • View a monthly report with a bar chart tracking the number of devices running your app for each month over the last year.
Mobile SDK API options

Use the Unity API to:

  • Create and complete interactions
  • Record custom metrics
  • Send custom events to Insights
  • Track custom network requests
Known limitations
  • The New Relic Unity plugin does not automatically instrument interactions. You must use the Unity API to track specific interactions.
  • The New Relic Unity plugin does not automatically instrument network requests. You must use the Unity API to track network calls.
  • Android builds: Unity still generates an Eclipse project, but Android Studio can import the Eclipse project.

Install and configure

The Unity plugin includes iOS and Android agent files that will embed the appropriate files for your build. To instrument interactions and network requests, you must use the Unity API to manually instrument your code.

Install the Unity plugin

As part of the installation process, New Relic Mobile automatically generates an application token. This is a 40-character hexadecimal string for authenticating each mobile project you monitor in New Relic Mobile.

For Admins with existing New Relic accounts, follow these steps to install and configure your Unity application. (If you do not have a New Relic account, see New Relic Mobile.)

  1. Go to rpm.newrelic.com/mobile.
  2. From the mobile apps index, select Add a new app.
  3. From the Get started page, select Unity as the platform for mobile monitoring.
  4. Type a name for your mobile project, then select Continue.

Continue with the procedures to configure the Unity plugin.

Configure the Unity plugin

These procedures to configure your app also appear on the Get started page in the New Relic UI.

  1. Install NewRelic-Unity-Plugin.unitypackage into your project by going to Assets > Import package > Custom package... and selecting NewRelic-Unity-Plugin.unitypackage.
  2. Create a new GameObject in your project's initial scene by going to GameObject > Create empty and naming it NewRelicAgent.
  3. Add NewRelicAgent.cs script (located in Assets/Plugins) to the NewRelicAgent GameObject:

    • Drag it on top of NewRelicAgent in the Hierarchy tab.

      OR

    • Click Add Component button, then select New Relic Agent from the Scripts option.

  4. In the Inspector tab, set the iOS or Android application token from your New Relic Mobile apps. (Recommendation: Keep New Relic Mobile apps on separate platforms.)
  5. Build for your platform (iOS or Android), then open the resulting project (Xcode or Eclipse).

    • For Eclipse, import the generated project into Android Studio.
    • Android only: Ensure that your app requests the INTERNET permission through the Player Settings inspector window. In Other Settings, Configuration, ensure the Internet access dropdown is set to Required. This will result in the following permission added to the app's manifest: <uses-permission android:name="android.permission.INTERNET" />

  6. Run your app in an emulator or device to generate data.

  7. Check New Relic Mobile to ensure the data is reporting to your account.

Configure crash reporting

The New Relic Unity plugin cannot automatically upload dSYMs for iOS crash reporting. You must manually upload dSYMs once your iOS unity app is built for release. If the application is bitcode enabled, follow the procedures for bitcode enabled apps once the your iOS app is submitted to Apple.

If you are building an Android app with ProGuard enabled, you must follow similar steps. The ProGuard mapping must be uploaded to New Relic so crash reports can be de-obfuscated. For more information, see Android agent crash reporting.

Optional: Change the logging level

Six logging levels are available for mobile apps monitoring:

  • NONE
  • ERROR
  • WARNING
  • INFO
  • VERBOSE
  • DEBUG

Recommendation: Set the logging level from the Unity Inspector tab.

Use Unity SDK API

Use the New Relic Unity SDK API to further configure and extend the plugin's instrumentation.

Create and complete interactions

To start an interaction:

string interactionIdentifier = NewRelicAgent.StartInteractionWithName("new interaction");

To stop the current interaction:

NewRelicAgent.StopCurrentInteraction(interactionIdentifier);

Interactions work in conjuction with method tracing. To trace a method insert startTracingMethod, insert at the start of the method to trace, and insert endTracingMethodWithTimer at each exit point of the method.

To start tracing a method:

Timer methodTimer = new Timer();
NewRelicAgent.StartTracingMethod("MethodName","ClassName",methodTimer,NewRelicAgent.NRTraceType.None);

To end tracing a method, use the same timer as the startTracingMethod:>

NewRelicAgent.EndTracingMethodWithTimer(methodTimer);
Set a custom build identifier

Custom build identifiers are set as the Application Build property in the inspector pane for the NewRelicAgent game object, under the New Relic Agent (Script) settings.

Execute a demo crash

If you have trouble getting your project to crash, use the New Relic Unity plugin API to execute a demo crash. Recommendation: Add this line of code to a button click event handler as applicable:

NewRelicAgent.CrashNow("message")>
Record custom metrics

With the custom metric API, you can record arbitrary numerical data and named events. Custom metrics can help to track high level events specific to your application.

You can use several API calls to record custom metrics that provide different levels of detail. To create a custom metric, use this method:

NewRelicAgent.RecordMetricWithName(String name, String category)

The name parameter is the textual name of the metric that will appear in the user interface for New Relic Mobile. Using clear, concise metric names will help you get the most out of the metrics.

The guidelines for naming a custom metric include:

  • Use case and white space characters appropriate for display in the user interface. Metric names are rendered as-is.
  • Capitalize the metric name.
  • Avoid using the characters / ] [ | * when naming things.
  • Avoid multi-byte characters.

If you want to specify more details about a custom metric, three other API methods are available:

NewRelicAgent.RecordMetricWithName(String name, String category, double value)

NewRelicAgent.RecordMetricWithName(string name, string category, double value, string valueUnits)

NewRelicAgent.RecordMetricWithName(string name, string category, double value, string valueUnits, string countUnits)

With these methods, you can record additional details:

Parameter Description
count The number of times the event has happened
totalValue The total value of the recording
exclusiveValue The exclusive value of the recording; for example, if the total value contains measurements accounted for elsewhere
countUnit Unit of measurement for the metric count, including PERCENT, BYTES, SECONDS, BYTES_PER_SECOND, or OPERATIONS
valueUnit Unit of measurement for the metric value, including PERCENT, BYTES, SECONDS, BYTES_PER_SECOND, or OPERATIONS

To view the custom metrics you collect, follow standard procedures to create custom dashboards.

Send custom events and attributes to Insights

The SDK can store up to 64 user-defined attributes at a time. If you attempt to store more than 64 attributes, the SDK returns false.

Use the following static methods in the NewRelicAgent namespace to send custom attributes and events to New Relic Insights. Methods that return boolean results return true if they succeed, or false if the operation did not complete.

The following methods are available for custom attributes and events:

RecordEvent (name, attributes)
NewRelicAgent.RecordEvent (string name, string dictionary attributes)

Records a custom Insights event. Includes a list of attributes specified as a map.

SetAttribute (name, value)
NewRelicAgent.SetAttribute (string name, string value)
NewRelicAgent.SetAttribute (string name, double value)

Creates an attribute with the specified text name and text/float value. SetAttribute overwrites its previous value and type each time it is called.

Examples

boolean attributeSet = NewRelicAgent.SetAttribute("username", "SampleUserName");
boolean attributeSet = NewRelicAgent.SetAttribute("rate", 9999.99);
IncrementAttribute (name [, value])
public static boolean IncrementAttribute(String name);
public static boolean incrementAttribute(String name, double value)

If value is not specified, this method increments the count for the specified attribute by 1. If the attribute does not exist, it creates the attribute with a value of 1.

If value is specified, the method will increment the attribute by the specified amount.

Examples

boolean incremented = NewRelicAgent.IncrementAttribute("rate");
boolean incremented = NewRelicAgent.IncrementAttribute("rate", 9999.99, false);
RemoveAttribute (name)
NewRelicAgent.RemoveAttribute(String name)

Removes the specified attribute.

Example

boolean attributeRemoved = NewRelicAgent.RemoveAttribute("rate");
removeAllAttributes
NewRelicAgent.removeAllAttributes()

Removes all attributes from the session.

Example

boolean attributesRemoved = NewRelicAgent.RemoveAllAttributes();

Track custom network requests

New Relic Mobile's API provides several methods to track network requests and network failures. For example, use the noticeHttpTransaction family of methods to record HTTP transactions with several available levels of detail. If a network request fails, you can record details about the failure with noticeNetworkFailure.

NoticeNetworkRequest
NewRelicAgent.NoticeNetworkRequest ("http://newrelic.com", "GET", timer, null, 200, 1024, 8192, bytes, httpParameters);
Parameter Description
url The URL of the request
httpMethod The HTTP method used, such as GET or POST
statusCode The statusCode of the HTTP response, such as 200 for OK
timer A timer created when the network request was started
bytesSent The number of bytes sent in the request
bytesReceived The number of bytes received in the response
responseBody The response body of the HTTP response. The response body will be truncated and included in an HTTP Error metric if the HTTP transaction is an error.
params Additional parameters included in an HTTP Error metric if the HTTP transaction is an error.
NoticeNetworkFailure
NewRelicAgent.NoticeNetworkFailure(String url, String httpMethod, Timer timer, NewRelicAgent.NetworkFailureCode failureCode, String message)
Parameter Description
url The URL of the request
httpMethod The HTTP method used, such as GET or POST
timer A timer created when the network request was started
exception The exception that occurred. New Relic Mobile can automatically translate many common exceptions into network failure types.
failure The type of network failure that occurred. If an exception cannot be resolved to a network failure automatically, this method can be used to categorize the failure accurately. The values are defined by the NetworkFailure enum. Valid values include Unknown, BadURL, TimedOut, CannotConnectToHost, DNSLookupFailed, BadServerResponse, and SecureConnectionFailed.

Uninstall plugin

To uninstall the Unity plugin, use the project console to remove all related files and resources that were installed with the Unity package:

  1. Delete NewRelicAgent object from the Hierarchy pane of the Unity project console.
  2. From All Scripts, delete all the scripts that start with newrelic.

Then do the following as applicable:

  • From Assets > Plugin > iOS, delete the NewRelicIos, NewRelicUnityPlugin, post-build, and restore-framework files. Then remove the mod_pbxproj and NewRelicAgent.framework directories.
  • From Assets > Plugin > Android, delete the newrelic.android and NewRelicAndroid files. Then remove the LICENSE and README directories.

Unity release notes

These release notes are for historical reference. Unity is no longer supported for new customers.

Unity plugin 1.2.0

Released on: Monday, March 13, 2017 - 13:00

Download URL: https://download.newrelic.com/unity/NewRelic-Unity-Plugin_1.2.0.zip

Notes:

Updated Unity plugin to iOS agent 5.9.0 and Android agent 5.9.0

Unity plugin 1.1.0

Released on: Tuesday, September 6, 2016 - 14:53

Download URL: https://download.newrelic.com/unity/NewRelic-Unity-Plugin_1.1.0.zip

Notes:

Updated Unity plugin to iOS agent 5.8.0 and Android agent 5.7.1

Unity plugin 1.0.1

Released on: Monday, August 8, 2016 - 14:00

Download URL: https://download.newrelic.com/unity/NewRelic-Unity-Plugin_1.0.1.zip

Notes:

Bundle Android class rewriter JAR file (version 5.6.1) into the Unity package.

Unity plugin 1.0.0

Released on: Wednesday, May 25, 2016 - 14:00

Download URL: http://download.newrelic.com/unity/NewRelic-Unity-Plugin_1.0.0.zip

Notes:

  • This plugin provides New Relic Mobile agent support for iOS and Android applications built with Unity. It also gives Unity developers access to New Relic crash reporting.
  • It provides information about app performance, sessions, devices, operating systems, and more. It also includes APIs for custom instrumentation to gain deeper insights into specific areas of your app.

For more help

Recommendations for learning more: