New Relic Android agents support distributed tracing. This lets you see how your mobile app activity connects to related services.
Requirements
To use distributed tracing, you need at least Android agent version 6.0.0. 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. Distributed tracing headers go out on every auto-instrumented request regardless of other settings.
If you prefer to turn it off, see Disable distributed tracing below.
To see the trace correlated with your app's network activity in New Relic (the reported MobileRequest or MobileRequestError event), you need AnalyticsEvents enabled — this is on by default, and it's a prerequisite for sending any of your app's analytics events, not something specific to distributed tracing.
Distributed tracing headers
Starting with Android agent version 7.8.3, 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 Android agent's Gradle plugin instruments your app's bytecode at build time, so distributed tracing headers are added automatically to requests made through:
OkHttp(versions 2 and 3)- Apache
HttpClient HttpURLConnection- Retrofit
Because this instrumentation weaves the call sites of those libraries directly, code that wraps them — including Kotlin coroutines and suspend functions — should also be covered, since the underlying call sites are woven regardless of what calls them.
The agent does not automatically add distributed tracing headers to:
- Volley. There's no Volley support in the agent at all, so Volley requests need manual propagation if you want them traced.
WebView. The agent'sWebViewinstrumentation covers page-load timing, not network request headers, so requests made from web content loaded in aWebViewaren't traced automatically.- Any other third-party networking library or custom transport that doesn't route through the libraries listed above.
For any of these, use manual propagation.
Manually propagate distributed tracing
If you make a request through a library the agent doesn't auto-instrument, you can still add distributed tracing headers and report the request yourself.
First, create a trace context and get its headers to attach to your outgoing request:
Language | Example |
|---|---|
Java | |
Kotlin | |
Then, when you report the completed request, pass traceContext.asTraceAttributes() as the trailing argument of noticeHttpTransaction or noticeNetworkFailure (select the Android tab for the full parameter reference) so the reported event is attributed to that trace:
Language | Example |
|---|---|
Java | |
Kotlin | |
Disable distributed tracing
NewRelic.disableFeature(FeatureFlag.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:
- 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.
- Query tips:
- Query by name by setting
mobileApp.nameto the mobile app name. - Query for traces containing at least one mobile app span with
mobileApp.name is not null. - Query for traces containing at least one backend app with
appName is not null. - Query for traces containing both mobile and backend spans by combining the two previous conditions.
- Query by name by setting
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
disableFeaturewithFeatureFlag.DistributedTracing. See How to set up distributed tracing. - AnalyticsEvents is disabled. Headers still go out, but the related
MobileRequest/MobileRequestErrorevent won't be sent. See How to set up distributed tracing. - The request isn't auto-instrumented. Requests made through Volley, a
WebView, or any library other thanOkHttp, ApacheHttpClient,HttpURLConnection, or Retrofit need 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.