New Relic iOS Agent

New Relic's mobile monitoring capabilities help you gain deeper visibility into how to analyze your iOS application performance and troubleshoot crashes. You can also examine HTTP and other network performance for unexpected lag, which will in turn help you collaborate more efficiently with your backend teams.

New Relic iOS Agent supports iOS 📱, tvOS 📺, watchOS ⌚️, and macOS (Catalyst) 💻.

This repository consists of an Xcode workspace containing the New Relic iOS Agent source code. The Agent is packaged as an XCFramework. The framework is available via Swift Package Manager (preferred installation method), Cocoapods, and as a zip file download.

See the XCFramework agent release notes for the latest release information. These release notes contain the link to the XCFramework zip file download.

Documentation

Public Documentation on docs.newrelic.com

Installation

From Xcode select File > Swift Packages > Add Package Dependency....
Add the Github URL of the Package file:
```
https://github.com/newrelic/newrelic-ios-agent
```
See Swift Package Manager agent installation instructions for more info.

View the docs for more installation methods.

Getting Started

If you have not created a Mobile Application in New Relic:

Click "+ Add data" in the top right,
In the Browser & Mobile section - please select the iOS tile, Select your Account
Name your app
Install the New Relic iOS Agent to your supported application. This should be an iOS, tvOS, or Catalyst app. Follow the instructions to install via the Swift Package Manager
You can also select the "+ Add data" option from the user menu in the upper right corner of the top navigation, then the iOS button to access the installation page.

If you have previously created a Mobile Application in New Relic:

Click the name of your mobile app,
Choose Installation from the Settings section in the left nav, and
Install the New Relic iOS Agent to your supported application. This should be an iOS, tvOS, or Catalyst app. Follow the instructions to install via the Swift Package Manager

Usage

An example app which demonstrates usage of the New Relic iOS Agent is included in the Agent workspace.

From Xcode change to the NRTestApp scheme to run the example app.
Add your New Relic application token to NRAPIInfo.plist as a String under the key NRAPIKey.
For more information see the README.md in the NRTestApp directory.

dSYM Upload Tools

By default, the New Relic iOS Agent will report crashes to New Relic. In order to view symbolicated crashes, your app must upload its debugging symbols to New Relic. The Agent contains the run-symbol-tool script for this purpose.

Xcode Run Script: Copy and paste the following line, replacing APP_TOKEN with your application token:

iOS agent 7.4.0 or higher:

ARTIFACT_DIR="${BUILD_DIR%Build/*}"
SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
/bin/sh "${SCRIPT}" "APP_TOKEN"

Add --debug as additional argument after the app token to write additional details to the upload_dsym_results.log file.

iOS agent 7.3.8 or lower:

SCRIPT=`/usr/bin/find "${SRCROOT}" -name newrelic_postbuild.sh | head -n 1`

if [ -z "${SCRIPT}"]; then
    ARTIFACT_DIR="${BUILD_DIR%Build/*}SourcePackages/artifacts"
    SCRIPT=`/usr/bin/find "${ARTIFACT_DIR}" -name newrelic_postbuild.sh | head -n 1`
fi

/bin/sh "${SCRIPT}" "APP_TOKEN"

OPTIONAL:

Add the following lines to your build script above the existing lines to skip symbol upload during debugging:

if [ ${CONFIGURATION} = "Debug" ]; then
    echo "Skipping DSYM upload CONFIGURATION: ${CONFIGURATION}"
    exit 0
fi

Note for Cocoapods or manual XCFramework integration:

With the 7.4.6 release the dsym-upload-tools are no longer included inside the XCFramework. The dsym-upload-tools are available in the dsym-upload-tools folder of the https://github.com/newrelic/newrelic-ios-agent-spm Swift Package Manager repository. Please copy this dsym-upload-tools directory to your applications source code directory if you are integrating the New Relic iOS Agent by copying XCFramework into project or using cocoapods.

The run-symbol-tool Run script must be added to your app's Xcode project build phases.

dsym-upload-tools/run-symbol-tool: Shell script which is used to bootstrap Swift script.
dsym-upload-tools/run-symbol-tool.swift: Swift script which converts dSYMs to map files and uploads to New Relic.

Building

To check out the code, run the following git command. Note the recursive submodule addition to make sure we get the repo's git submodules.
- git clone git@github.com:newrelic/newrelic-ios-agent.git --recurse-submodules
Open newrelic-ios-agent/Agent.xcworkspace using the Finder.
Option 1: Build using Xcode.
Option 2: Build using Fastlane
- bundle exec fastlane buildFramework
  - Run the above command to create the New Relic iOS Agent XCFramework.

Testing

Option 1: Run the Unit Tests using Xcode by selecting Agent-iOS scheme and Product -> Test
Option 2: Running tests using Fastlane
- bundle exec fastlane runIOSTests
  - Run above command to run tests on iOS. Upon completion, code coverage will be generated.
    - run brew install lcov to add lcov for code coverage.

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: Mobile topic on forum.newrelic.com

Contribute

We encourage your contributions to improve New Relic iOS 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 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. We also host a community project page dedicated to New Relic iOS agent.

License

New Relic iOS Agent is licensed under the Apache 2.0 License. The New Relic iOS 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.

newrelic / newrelic-ios-agent

readme