• /
  • EnglishEspañolFrançais日本語한국어Português
  • ログイン今すぐ開始

New Relic iOS mobile monitoring with distributed tracing

|View as Markdown (English)

Our iOS agent supports distributed tracing. This lets you see how your mobile app activity connects to related services.

Requirements

To use distributed tracing, you need iOS agent version 7.3.0 or higher. We recommend you use the most recent agent.

How to set up distributed tracing

Distributed tracing is enabled by default — you don't need to do anything to turn it on.

If you prefer to turn it off, see Distributed tracing in the mobile SDK API guide, or Disable distributed tracing below.

Distributed tracing headers go out on every instrumented request regardless of other settings. However, for the trace to be linked to a reported MobileRequest event (and so show up correlated with your app's network activity in the UI), you also need Network Request Events enabled. This is on by default, so it only matters if you've explicitly turned it off.

Distributed tracing headers

Starting with iOS agent version 7.7.8, the agent adds only the W3C Trace Context headers, traceparent and tracestate, to outgoing network requests. It no longer sends the proprietary newrelic header. Earlier agent versions send all three headers.

New Relic APM agents that support W3C Trace Context use these headers to continue the trace, so requests from your app stay connected to the backend services they call. W3C Trace Context is supported in these APM agent versions and higher:

APM agent

Minimum version

Go

3.1.0

Java

5.10.0

.NET

8.27.0

Node.js

6.4.0

Python

5.6.0

重要

If a service, proxy, or gateway between your app and your backend requires the newrelic header, update it to accept traceparent and tracestate instead. APM agents older than the versions above only recognize the newrelic header, and start a new trace instead of linking to the request from your app.

Which requests get distributed tracing automatically

The agent automatically instruments NSURLSession and NSURLConnection, so distributed tracing headers are added to requests made through either one with no setup required.

重要

If your app uses Swift's async/await URLSession APIs (for example, data(for:) or data(from:)), they are not covered by the default instrumentation. You must explicitly enable NRFeatureFlag_SwiftAsyncURLSessionSupport (disabled by default as of agent version 7.4.5) for the agent to add distributed tracing headers to those calls:

Language

Procedure

Objective-C

Call prior to [NewRelic startWithApplicationToken:...];

[NewRelic enableFeatures:NRFeatureFlag_SwiftAsyncURLSessionSupport];

Swift

Call prior to NewRelic.start(withApplicationToken:)

NewRelic.enableFeatures(NRMAFeatureFlags.NRFeatureFlag_SwiftAsyncURLSessionSupport)

The agent does not automatically add distributed tracing headers to:

  • WKWebView. Web content loaded in a WKWebView makes its network requests from within the WebKit process, outside the app's NSURLSession/NSURLConnection instrumentation, so those requests aren't traced automatically. (The agent's separate WKWebView instrumentation, on by default, covers page-load timing only, not network headers.)
  • Third-party networking libraries that don't route through NSURLSession or NSURLConnection.
  • WebSockets.
  • gRPC or other custom transports.

For any of these, use manual propagation.

Manually propagate distributed tracing

If you make a request through an API, the agent doesn't auto-instrument. You can still add distributed tracing headers and report the request manually.

If something else reports the request

Some frameworks (for example, a native networking library used by a hybrid framework) send the request and report it to New Relic separately. In this case, generate the headers and attach them yourself. Whatever reports the request will recover the trace identity from the W3C headers.

Language

Example

Objective-C

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
NSDictionary<NSString *, NSString *> *headers = [NewRelic generateDistributedTracingHeaders];
for (NSString *field in headers) {
[request setValue:headers[field] forHTTPHeaderField:field];
}

Swift

var request = URLRequest(url: url)
let headers = NewRelic.generateDistributedTracingHeaders()
for (field, value) in headers {
request.setValue(value, forHTTPHeaderField: field)
}

If you both send and report the request

If the same code sends the request and reports it to New Relic (for example, a cross-platform agent), use generateDistributedTracingContext instead. It returns one dictionary with the W3C headers to set on the request (traceparent, tracestate) plus the trace's identity (trace.id, id, guid) to hand back when you report the request, so the reported event is attributed to that trace rather than a new one.

Pass that same dictionary as the traceHeaders parameter of noticeNetworkRequestForURL: or noticeNetworkFailureForURL: (select the iOS tab) when you report the completed request — see those pages for the full parameter reference.

Language

Example

Objective-C

NSDictionary<NSString *, NSString *> *context = [NewRelic generateDistributedTracingContext];
// Add context[@"traceparent"] and context[@"tracestate"] to your outgoing request, then:
[NewRelic noticeNetworkRequestForURL:url
httpMethod:@"GET"
startTime:startTime
endTime:endTime
responseHeaders:responseHeaders
statusCode:statusCode
bytesSent:bytesSent
bytesReceived:bytesReceived
responseData:responseData
traceHeaders:context
andParams:nil];

Swift

let context = NewRelic.generateDistributedTracingContext()
// Add context["traceparent"] and context["tracestate"] to your outgoing request, then:
NewRelic.noticeNetworkRequest(for: url, httpMethod: "GET", startTime: startTime, endTime: endTime,
responseHeaders: responseHeaders, statusCode: statusCode,
bytesSent: bytesSent, bytesReceived: bytesReceived,
responseData: responseData, traceHeaders: context, andParams: nil)

Disable distributed tracing

If you need to turn distributed tracing off, call the appropriate method before you start the agent:

Language

Procedure

Objective-C

Call prior to [NewRelic startWithApplicationToken:...];

[NewRelic disableFeatures:NRFeatureFlag_DistributedTracing];

Swift

Call prior to NewRelic.start(withApplicationToken:)

NewRelic.disableFeatures(NRMAFeatureFlags.NRFeatureFlag_DistributedTracing)

Enable Infinite Tracing

If your mobile apps have some downstream services that use our tail-based distributed tracing called Infinite Tracing, you should enable this feature for your mobile apps. This ensures that your root span (the initiating mobile app) is included in the rest of the spans tracked by Infinite Tracing.

To set this up, see the Infinite Tracing steps to create a trace observer and to select which mobile apps (data sources) should report spans.

Find data

Mobile spans appear in any New Relic distributed tracing UI where those spans are part of a trace.

Here are some tips for finding and querying data:

For example, to find mobile spans for a specific app:

SELECT count(*) FROM Span WHERE mobileApp.name = 'YOUR_APP_NAME' SINCE 1 day ago

To find traces that connect a mobile span to a backend APM span:

SELECT * FROM Span WHERE mobileApp.name IS NOT NULL AND appName IS NOT NULL SINCE 1 day ago

Troubleshooting

If you don't see mobile spans where you expect them, check these possible causes:

  • Distributed tracing is disabled. Confirm you haven't called disableFeatures with NRFeatureFlag_DistributedTracing. See How to set up distributed tracing.
  • The request isn't auto-instrumented. Requests made through anything other than NSURLSession or NSURLConnection — including Swift async/await URLSession calls — need either NRFeatureFlag_SwiftAsyncURLSessionSupport enabled or manual propagation. See Which requests get distributed tracing automatically.
  • The backend APM agent is too old. If the receiving service's APM agent doesn't support W3C Trace Context yet, it starts a new trace instead of linking to your app's. Check the minimum APM agent versions.
  • A proxy or gateway strips the headers. Anything sitting between your app and the backend needs to pass through traceparent and tracestate unmodified.
  • tracestate is dropped because the trusted account key doesn't match. If a backend service belongs to a different New Relic account than your mobile app, confirm the account is in the same trust relationship, or the tracestate entry may be ignored.

For broader distributed tracing issues, see Troubleshooting.

Copyright © 2026 New Relic株式会社。

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.