Overview

Native mobile tracing gives you precise control over what operations are measured by manually instrumenting spans in your iOS or Android app code. This approach works independently of Datadog RUM, but can also be used alongside it for deeper visibility into user experiences, code level performance, and backend interactions. You can also use OpenTelemetry for iOS or OpenTelemetry for Android for custom instrumentation.

Datadog’s Trace SDK for iOS and Android lets you add APM spans to your mobile apps. This guide covers usage, key use cases, and sampling rates, with or without using the Datadog RUM SDK.

Note: When using the Trace SDK independently (without the RUM SDK), root spans for outgoing network requests do not get automatically created. Therefore, you need to manually start and stop spans on the client side to create frontend-to-backend distributed APM traces.

This guide focuses on native iOS and Android apps. For other mobile platforms, see the following documentation:

• React Native RUM and APM
• Flutter RUM and APM
• Kotlin Multiplatform RUM and APM
• Unity RUM and APM

For a comprehensive overview of correlating RUM with other telemetry data, see Correlate RUM with other telemetry data.

Use cases

Wrap a frontend-to-backend distributed trace under a native span

You can create distributed traces that span from your mobile frontend to your backend services. The RUM SDK provides an automated way to produce client spans for outgoing network requests. Datadog’s Trace SDK provides similar capability, but also allows you to wrap one or more frontend-to-backend traces under manually created spans.

Note: Wrapping RUM resource spans under a native span works automatically if the parent span is on the same thread as the network call. Otherwise, use the provided helpers to set the parent span manually.

Profiling native application performance

Instrumenting multiple native spans and linking them (using setActive on iOS or activateSpan on Android) allows you to profile key parts of your app. This helps you:

• Understand how different methods and components interact
• Break down performance bottlenecks
• Gain actionable insights into app behavior

Here’s how to manually instrument a span in your mobile app using the Trace SDK:

let span = tracer.startSpan(operationName: "<span_name>")
// ... code to measure ...
span.finish()

val span = tracer.buildSpan("<span_name>").start()
// ... code to measure ...
span.finish()

Sampling

Sampling in native mobile tracing controls which spans and traces are ingested in Datadog, helping you balance visibility with data volume. When you manually instrument spans in your app, the ones that are sampled in go through the APM retention filters which determine which ones end up being displayed for analysis in the Datadog interface.

How sampling works

Sampling affects different types of spans you create in your mobile app:

Note: The sampling behavior described below applies to iOS SDK v2.9.0+ and Android SDK v1.18.0+. For earlier versions, see the respective SDK documentation for platform-specific sampling behavior.

• Local span sampling applies to manually instrumented spans (like performance profiling spans). It’s controlled by the Trace.sampleRate parameter. For example, if you set this rate to 50, the Trace SD produces spans in 50% of the cases, and sends all of those to Datadog. Visibility of those spans in the UI depends on your APM retention filters. Each span event includes the _dd.agent_psr field (the sampling rate) and metrics._sampling_priority_v1 (1 for sampled, 0 for not sampled).

• Distributed trace sampling applies to traces that cross service boundaries, such as network requests to your backend (relevant for the “Wrap a frontend-to-backend distributed trace” use case). This is controlled by the urlSessionTracking.firstPartyHostsTracing.sampleRate parameter for iOS and DatadogInterceptor.Builder.setTraceSampler parameter for Android. If set to 50, only half of backend requests have the sampled flag set to true, as indicated by the W3C trace context. All Datadog Agents honor this decision, so you see 50% of distributed traces in the UI.

Sampling rates are applied independently. The most restrictive rate determines what data is visible in the UI for a given session or trace. For example:

• If you set a low RUM session sample rate (for example, 1%), only 1% of user sessions are recorded for RUM, but you can still trace all network requests within those sessions by setting the network tracing sample rate to 100%.
• If you set a high trace sample rate but a low RUM sample rate, you may see traces without corresponding RUM data.

Example scenario:
To sample 1% of all app sessions and trace all API network requests within those sessions:

• Set RUM.sessionSampleRate = 1 (controls RUM session sampling only)
• Set urlSessionTracking.firstPartyHostsTracing.sampleRate = 100 (controls trace sampling for network requests)

Sampling decisions are communicated through trace headers, ensuring all services in a distributed trace use the same sampling choice.

Sampling parameters

The following sampling rate parameters control different aspects of data collection:

Further reading

Additional helpful documentation, links, and articles:

Connect RUM and TracesDOCUMENTATION iOS Trace SDKDOCUMENTATION Android Trace SDKDOCUMENTATION OpenTelemetry for iOSDOCUMENTATION OpenTelemetry for AndroidDOCUMENTATION