New Relic Unity Agent

This agent utilizes the native New Relic Android and iOS agents to instrument Unity apps. The New Relic SDKs gather data such as crashes, network traffic, and other relevant information to help monitor and assess the performance of Unity apps.

Features

• Record and Capture C# errors
• Network Instrumentation
• Distributed Tracing
• Tracking UnityEngine Debug log, assert and error
• Handled Exception
• Capture interactions and the sequence in which they were created
• Pass user information to New Relic to track user sessions
• Scene Navigation as Interactions
• Capture Native C++ Errors
• offline monitoring of events and exceptions
• Capture Background Events when app is in background

Current Support:

• Android API 24+ (AGP 7 and Higher)
• iOS 10
• Depends on New Relic iOS/XCFramework and Android agents

Installation

1. Scoped Registries allow Unity to communicate the location of any custom package registry server to the Package Manager so that the user has access to several collections of packages at the same time. NewRelic uses Scoped Registries to allow our users to manage, download and install our SDK using the built-in Unity Package Manager.

   In the Package Manager in the Unity IDE, download the NewRelic SDK using add package from git url

   https://github.com/newrelic/newrelic-unity-agent.git
   
   

2. Open the NewRelic editor

In your Unity IDE, click Tools → NewRelic → Getting Started to open the NewRelic editor window.

3. Update your app information on the editor Select Android and enter the App token:

   AppToken is platform-specific. You need to generate the seprate token for Android and iOS apps to get better Visibility at app level.

4. External Dependency Manager support (do not skip this step!) If using the Unity External Dependency Manager plug-in, disable the your dependency resolver at the root level in launcherTemplate.gradle:

 apply plugin: 'com.android.application'
 apply plugin: 'newrelic' // <-- add this
dependencies {
    implementation project(':unityLibrary')
    implementation 'com.newrelic.agent.android:agent-ndk:1.+' 
    implementation 'com.newrelic.agent.android:android-agent:7.5.0' 
    }

android {
    compileSdkVersion **APIVERSION**
    buildToolsVersion '**BUILDTOOLS**'

5. Customize Gradle Templates If using Unity 2019 or later, add the following to your Gradle files:

   1.Include the New Relic Maven repository URL in the Gradle build settings. To do this, open your mainTemplate.gradle file (usually located in Assets/Plugins/Android folder) and add the New Relic Maven URL like this:

   allprojects {
    buildscript {
        repositories {**ARTIFACTORYREPOSITORY**
            google()
            jcenter()
            mavenCentral()
        }

2. Add the New Relic classpath to your project-level baseProjectTemplate.gradle file (typically located in the android folder in your Unity project):

      dependencies {
          // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
          // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
          // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
          // To specify a custom Gradle version in Unity, go to "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
          classpath 'com.newrelic.agent.android:agent-gradle-plugin:7.5.0'
          **BUILD_SCRIPT_DEPS**
      }
  }


If you are utilizing an older version of Unity Studio, you can incorporate a lower version of the classpath as a dependency which supports AGP7 and lower version of Gradle.

```groovy
      dependencies {
          // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
          // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
          // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
          // To specify a custom Gradle version in Unity, go to "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
          classpath 'com.newrelic.agent.android:agent-gradle-plugin:6.11.0'
          **BUILD_SCRIPT_DEPS**
      }
  }

By making these changes in your Gradle files, you will ensure that the New Relic artifacts are properly downloaded and included in your Unity project.

6.Make sure your app requests INTERNET and ACCESS_NETWORK_STATE permissions by adding these lines to your AndroidManifest.xml

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

7. Please ensure that your External Dependency Manager settings match the following configuration. In your Unity IDE, navigate to Assets → External Dependency Manager → iOS Resolver → Settings:

   1. Add use_frameworks! to Podfile is unchecked.
   2. Always add the main target to Podfile box is checked.

8. If the Podfile is not being used for iOS dependency management, you can proceed with the following steps.

   1. Download and unzip the New Relic XCFramework SDK Download the latest iOS agent from our iOS agent release notes
   2. Add the New Relic XCFramework to your Xcode project Unzip the SDK download, drag the “NewRelicAgent.xcframework” folder from the Finder into your Xcode project (dropping it onto your Targets Frameworks pane). Select “Embed & Sign” under the Embed column.

Usage

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

startInteractionWithName(string name): <InteractionId>;

Track a method as an interaction.

InteractionId is string.

stopCurrentInteraction(string interactionIdentifier): 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().

      string interActionId = NewRelicAgent.StartInteractionWithName("Unity InterAction Example");

      for(int i =0; i < 4;i++)
      {
          Thread.Sleep(1000);
      }

      NewRelicAgent.StopCurrentInteraction(interActionId);

setAttribute(string name, string|double value): void;

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

   NewRelicAgent.setAttribute('UnityCustomAttrNumber', 37);

removeAttribute(string name): void;

This method removes the attribute specified by the name string..

   NewRelicAgent.removeAttribute('UnityCustomAttrNumber');

incrementAttribute(string name, double amount): void;

Increments the count of an attribute with a specified name. Overwrites its previous value and type each time it is called. If the attribute does not exists, it creates a new attribute. If no value is given, it increments the value by 1.

    NewRelicAgent.incrementAttribute('UnityCustomAttrNumber');
    NewRelicAgent.incrementAttribute('UnityCustomAttrNumber', 5);

setUserId(string userId): void;

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

   NewRelicAgent.setUserId("Unity12934");

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

Track app activity/screen that may be helpful for troubleshooting crashes.

      Dictionary<string, object> dic = new Dictionary<string, object>();
      dic.Add("Unity Attribute", "Data1");

      NewRelicAgent.RecordBreadCrumb("Unity BreadCrumb Example", dic);

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

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

      Dictionary<string, object> dic = new Dictionary<string, object>();
      dic.Add("Unity Custom Attribute", "Data2");

      NewRelicAgent.RecordCustomEvent("Unity Custom Event Example", dic);

currentSessionId(): string;

Returns the current session ID. This method is useful for consolidating monitoring of app data (not just New Relic data) based on a single session definition and identifier.

    string sessionId =  NewRelicAgent.currentSessionId();

noticeHttpTransaction(string httpMethod, int statusCode,long startTime,long endTime,long bytesSent,long bytesReceived,string responseBody, Dictionary<string,object> dtHeaders): void;

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

    NewRelicAgent.noticeHttpTransaction('https://github.com', 'GET', 200, DateTimeOffset.Now.ToUnixTimeMilliseconds(), DateTimeOffset.Now.ToUnixTimeMilliseconds()+1000, 100, 101, "response body",null);

noticeNetworkFailure(string url,string httpMethod,long startTime,long endTime,NewRelicAgent.NetworkFailureCode failureCode,string message): void; or (string url,string httpMethod,Timer timer,NewRelicAgent.NetworkFailureCode failureCode,string message): void;

Records network failures. If a network request fails, use this method to record details about the failures. In most cases, place this call inside exception handlers, such as catch blocks.

    long startTime = DateTimeOffset.Now.ToUnixTimeMilliseconds();
    NewRelic.noticeNetworkFailure('https://github.com', 'GET', startTime, endTime, NewRelic.NetworkFailure.BadURL);

    Timer timer = new();
    NewRelic.noticeNetworkFailure('https://github.com', 'GET',timer , NewRelic.NetworkFailure.BadURL);

recordMetric(string name, string category,double value, NewRelicAgent.MetricUnit valueUnits,NewRelicAgent.MetricUnit countUnits): void;

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If using countUnit or valueUnit, then all of value, countUnit, and valueUnit must all be set.

    NewRelicAgent.recordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory');
    NewRelicAgent.recordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory', 12);
    NewRelicAgent.recordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory', 13, NewRelicAgent.MetricUnit.PERCENT, NewRelicAgent.MetricUnit.SECONDS);

removeAllAttributes(): void;

Removes all attributes from the session

    NewRelicAgent.RemoveAllAttributes();

recordError(e: string|error): void;

Records C# errors for Unity.

    try {
      string foo;
      foo.Length;
    } catch (Exception e)
    {
        NewRelicAgent.RecordException(e);
    }

setMaxEventBufferTime(uint seconds): void;

Sets the event harvest cycle length. Default is 600 seconds (10 minutes). Minimum value can not be less than 60 seconds. Maximum value should not be greater than 600 seconds.

    NewRelicAgent.setMaxEventBufferTime(60);

setMaxEventPoolSize(uint size): void;

Sets the maximum size of the event pool stored in memory until the next harvest cycle. Default is a maximum of 1000 events per event harvest cycle. When the pool size limit is reached, the agent will start sampling events, discarding some new and old, until the pool of events is sent in the next harvest cycle.

    NewRelicAgent.setMaxEventPoolSize(2000);

setMaxOfflineStorageSize(uint 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.

    NewRelicAgent.setMaxOfflineStorageSize(200);

LogInfo(String message) : void

Logs an informational message to the New Relic log.

    NewRelicAgent.LogInfo("This is an informational message");

LogError(String message) : void

Logs an error message to the New Relic log.

    NewRelicAgent.LogError("This is an error message");

LogVerbose(String message) : void

Logs a verbose message to the New Relic log.

    NewRelicAgent.LogVerbose("This is a verbose message");

LogWarning(String message) : void

Logs a warning message to the New Relic log.

    NewRelicAgent.LogWarning("This is a warning message");

LogDebug(String message) : void

Logs a debug message to the New Relic log.

    NewRelicAgent.LogDebug("This is a debug message");

Log(NewRelicAgent.AgentLogLevel level, String message) : void

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

    NewRelicAgent.LogNewRelic.NewRelicAgent.AgentLogLevel.INFO, "This is an informational message");

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

Logs a message with attributes to the New Relic log.

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

How to see C# Errors(Fatal/Non Fatal) in NewRelic One?

C# errors and handled exceptions can be seen in the Handled Exceptions tab in New Relic One. You will be able to see the event trail, attributes, and stack trace for each C# error recorded.

You can also build a dashboard for these errors using this query:

SELECT * FROM MobileHandledException SINCE 24 hours ago

Query Unity log data [#logs]

New Relic stores your Unity logs as custom events. You can query these logs and build dashboards for them using this NRQL query:

 SELECT * FROM `Mobile Unity Logs` SINCE 30 MINUTES AGO

For more information on NRQL queries, see Introduction to NRQL.

Contribute

We encourage your contributions to improve newrelic-unity-agent! 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 [email protected].

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 our bug bounty program.

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. We also host a community project page dedicated to Project Name.

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

newrelic-unity-agent is licensed under the Apache 2.0 License.

[If applicable: newrelic-unity-agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third-party notices document.]