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 |
Swift | Call prior to |
The agent does not automatically add distributed tracing headers to:
WKWebView. Web content loaded in aWKWebViewmakes its network requests from within the WebKit process, outside the app'sNSURLSession/NSURLConnectioninstrumentation, so those requests aren't traced automatically. (The agent's separateWKWebViewinstrumentation, on by default, covers page-load timing only, not network headers.)- Third-party networking libraries that don't route through
NSURLSessionorNSURLConnection. - 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 | |
Swift | |
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 | |
Swift | |
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 |
Swift | Call prior to |
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:
- You can find end-user-originating traces in any New Relic distributed tracing UI.
- In the distributed tracing UI, end-user spans are indicated with the
icon. - To see a span's attributes, select a span in the UI.
- Spans are reported as Span data, and can be queried in New Relic.
For example, to find mobile spans for a specific app:
SELECT count(*) FROM Span WHERE mobileApp.name = 'YOUR_APP_NAME' SINCE 1 day agoTo 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 agoTroubleshooting
If you don't see mobile spans where you expect them, check these possible causes:
- Distributed tracing is disabled. Confirm you haven't called
disableFeatureswithNRFeatureFlag_DistributedTracing. See How to set up distributed tracing. - The request isn't auto-instrumented. Requests made through anything other than
NSURLSessionorNSURLConnection— including Swiftasync/awaitURLSessioncalls — need eitherNRFeatureFlag_SwiftAsyncURLSessionSupportenabled 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
traceparentandtracestateunmodified. tracestateis 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 thetracestateentry may be ignored.
For broader distributed tracing issues, see Troubleshooting.