RUM-11586: updating MIGRATION.MD by satween · Pull Request #2858 · DataDog/dd-sdk-android

satween · 2025-09-05T13:04:25Z

What does this PR do?

Updates MIGRATION.MD, adds more details

Review checklist (to be filled by reviewers)

Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
Make sure you discussed the feature or bugfix with the maintaining team in an Issue
Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

0xnm · 2025-09-05T13:07:02Z

@DataDog/documentation Can you please review the v2 to v3 migration documentation we added?

dd-sdk-android/MIGRATION.MD

Lines 1 to 181 in f351e48

# Migration from 2.x to 3.0

The main changes introduced in SDK 3.0 compared to 2.x are:

1. The `OpenTracing` dependency was removed because it is obsolete.

We replaced the `OpenTracing` classes with internal one. However we strongly encourage you to use the OTel version as the new tracing API standard.

### Trace product changes

#### Migrating tracing from `OpenTracing` to `OpenTelemetry` (recommended)

> [!WARNING]

> Note that the `OpenTelemetry` specification library [requires](https://github.com/open-telemetry/opentelemetry-java?tab=readme-ov-file#requirements) desugaring to be enabled for with projects that have a `minSdk` < 26. If this requirement cannot be met in your project see the following section.

1. Add the `OpenTelemetry` dependency to your `build.gradle.kts`:

```kotlin

implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x"))

```

2. Replace the `OpenTracing` configuration:

```kotlin

GlobalTracer.registerIfAbsent(

AndroidTracer.Builder()

.setService(BuildConfig.APPLICATION_ID)

.build()

)

```

with the `OpenTelemetry` configuration:

```kotlin

GlobalOpenTelemetry.set(object : OpenTelemetry {

private val tracerProvider = OtelTracerProvider.Builder()

.setService(BuildConfig.APPLICATION_ID)

.build()

override fun getTracerProvider(): TracerProvider {

return tracerProvider

}

override fun getPropagators(): ContextPropagators {

return ContextPropagators.noop()

}

})

```

> [!NOTE]

> You can use the default configuration to make it even shorter in case if don't provide any additional parameters:

```kotlin

GlobalOpenTelemetry.set(

DatadogOpenTelemetry(BuildConfig.APPLICATION_ID)

)

```

To access the tracer object for manual (custom) tracing, use `io.opentelemetry.api.GlobalOpenTelemetry.get()` instead of `io.opentracing.util.GlobalTracer.get()`.

For example:

```kotlin

val tracer: Tracer = GlobalOpenTelemetry

.get()

.getTracer("SampleApplicationTracer")

val span = tracer

.spanBuilder("Executing operation")

.startSpan()

// Code that should be instrumented

span.end()

```

Refer to the official `OpenTelemetry` [documentation](https://opentelemetry.io/docs/) for more details.

#### Migrating tracing from `OpenTracing` to `DatadogTracing` (transition period)

> [!WARNING]

> This option has been added for compatibility and to simplify the transition from `OpenTracing` to `OpenTelemetry`, but it may not be available in future major releases. We recommend using `OpenTelemetry` as the standard for tracing tasks. However, if it is not possible to enable desugaring in your project for some reason, you can use this method.

1. Add the `DatadogTracing` dependency to your `build.gradle.kts`:

```kotlin

implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x"))

```

2.Replace the `OpenTracing` configuration:

```kotlin

GlobalTracer.registerIfAbsent(

AndroidTracer.Builder()

.setService(BuildConfig.APPLICATION_ID)

.build()

)

```

with the `DatadogTracing` configuration:

```kotlin

GlobalDatadogTracer.registerIfAbsent(

DatadogTracing.newTracerBuilder()

.build()

)

```

For manual (custom) tracing use `com.datadog.android.trace.GlobalDatadogTracer.get()` instead of `io.opentracing.util.GlobalTracer.get()` to access the tracer object.

For example:

```kotlin

val tracer = GlobalDatadogTracer.get()

val span = tracer

.buildSpan(operationName)

.start()

// Code that should be instrumented

span.finish()

```

Refer to the Datadog [documentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/android?tab=kotlin) for more details.

API changes:

|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`|

|---|---|---|

|`io.opentracing.util.GlobalTracer`|`io.opentelemetry.api.GlobalOpenTelemetry`|`com.datadog.android.trace.GlobalDatadogTracer`|

|`com.datadog.android.trace.AndroidTracer`|`io.opentelemetry.api.trace.Tracer`|`com.datadog.android.trace.api.tracer.DatadogTracer`|

|`io.opentracing.Span`|`io.opentelemetry.api.trace.Span`|`com.datadog.android.trace.api.span.DatadogSpan`|

|`io.opentracing.Scope`|`io.opentelemetry.context.Scope`|`com.datadog.android.trace.api.scope.DatadogScope`|

|`io.opentracing.SpanContext`|`io.opentelemetry.api.trace.SpanContext`|`com.datadog.android.trace.api.span.DatadogSpanContext`|

Replacement hints:

|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`|

|---|---|---|

|`AndroidTracer.Builder().build()`||`DatadogTracing.newTracerBuilder().build()`|

|`AndroidTracer#setPartialFlushThreshold(Int)`|`OtelTracerProvider#setPartialFlushThreshold()`|`DatadogTracerBuilder#withPartialFlushMinSpans()`|

|`io.opentracing.SpanContext#toTraceId()`|`io.opentelemetry.api.trace.SpanContext#getTraceId()`|`DatadogSpanContext.traceId.toString()`|

|`io.opentracing.Span#setError()`|`io.opentelemetry.api.trace#recordException()`|`DatadogSpan#addThrowable()`|

### OkHttp instrumentation changes

The OkHttp instrumentation (`com.datadoghq:dd-sdk-android-okhttp:x.x.x`) doesn't require desugaring support. However few migration actions may be necessary.

API changes:

|`2.x`|`3.0`|

|--|--|

|`TracingInterceptor(String, List<String>, TracedRequestListener,Sampler)`| Use `TracingInterceptor.Builder()` instead.|

|`TracingInterceptor(String?,Map<String, Set<TracingHeaderType>>, TracedRequestListener, Sampler)`| Use `TracingInterceptor.Builder()` instead.|

|`TracingInterceptor(String?,TracedRequestListener,Sampler)`|Use `TracingInterceptor.Builder()` instead.|

|`DatadogInterceptor(String?, Map<String, Set<TracingHeaderType>>,TracedRequestListener, RumResourceAttributesProvider, Sampler)`|Use `DatadogInterceptor.Builder()` instead. |

|`DatadogInterceptor(String?,List<String>,TracedRequestListener,RumResourceAttributesProvider,Sampler)`|Use `DatadogInterceptor.Builder()` instead.|

| `DatadogInterceptor(String?,TracedRequestListener,RumResourceAttributesProvider,Sampler) ` | Use `DatadogInterceptor.Builder()` instead. |

### Core product changes

API changes:

|`2.x`| `3.0` |

|--|------------------------------------------------------------------|

|`Datadog#setUserInfo(String?, ...)`| User info ID is now mandatory `Datadog.setUserInfo(String, ...)` |

### RUM product changes

API changes:

|`2.x`| `3.0` |

|--|-------------------------------------------------------------------------------------|

|`DatadogRumMonitor#startResource(String, String, String,Map<String, Any?>)`| Use `startResource` method which takes `RumHttpMethod` as `method` parameter instead |

|`com.datadog.android.rum.GlobalRum`|`GlobalRum` object was renamed to `com.datadog.android.rum.GlobalRumMonitor` |

|`com.datadog.android.rum.RumMonitor#addAction()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.RumMonitor#startAction()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.RumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.RumMonitor#addError()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.RumMonitor#addErrorWithStacktrace()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional |

|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional |

Co-authored-by: Nikita Ogorodnikov <[email protected]>

codecov-commenter · 2025-09-05T13:36:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.81%. Comparing base (6e78b75) to head (f17ca5d).
⚠️ Report is 1526 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2858      +/-   ##
===========================================
- Coverage    70.91%   70.81%   -0.10%     
===========================================
  Files          809      809              
  Lines        29460    29463       +3     
  Branches      4937     4937              
===========================================
- Hits         20889    20863      -26     
- Misses        7236     7258      +22     
- Partials      1335     1342       +7

see 30 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

rtrieu

Left some minor feedback for your consideration!

Co-authored-by: Rosa Trieu <[email protected]>

Co-authored-by: Nikita Ogorodnikov <[email protected]>

Co-authored-by: Jonathan Moskovich <[email protected]>

RUM-11586: updating MIGRATION.MD

4ff9265

satween requested review from a team as code owners September 5, 2025 13:04

0xnm previously approved these changes Sep 5, 2025

View reviewed changes

Update MIGRATION.MD

36ef107

Co-authored-by: Nikita Ogorodnikov <[email protected]>

satween dismissed 0xnm’s stale review via 36ef107 September 5, 2025 13:07

simaoseica-dd requested a review from a team September 5, 2025 13:21

rtrieu previously approved these changes Sep 5, 2025

View reviewed changes

Comment thread MIGRATION.MD Outdated

Comment thread MIGRATION.MD Outdated

Comment thread MIGRATION.MD Outdated

Comment thread MIGRATION.MD Outdated

Apply suggestions from code review

d47322f

Co-authored-by: Rosa Trieu <[email protected]>

satween dismissed rtrieu’s stale review via d47322f September 5, 2025 14:33

satween requested a review from rtrieu September 5, 2025 14:37

rtrieu previously approved these changes Sep 5, 2025

View reviewed changes

0xnm previously approved these changes Sep 5, 2025

View reviewed changes

Comment thread MIGRATION.MD Outdated

Update MIGRATION.MD

d5a4f06

Co-authored-by: Nikita Ogorodnikov <[email protected]>

satween dismissed stale reviews from 0xnm and rtrieu via d5a4f06 September 5, 2025 15:51

satween requested a review from 0xnm September 5, 2025 15:52

0xnm previously approved these changes Sep 5, 2025

View reviewed changes

RUM-11586: updating MIGRATION.MD

873d15a

satween dismissed 0xnm’s stale review via 873d15a September 5, 2025 16:59

RUM-11586: updating MIGRATION.MD

5f173aa

0xnm previously approved these changes Sep 8, 2025

View reviewed changes

jonathanmos previously approved these changes Sep 8, 2025

View reviewed changes

Comment thread MIGRATION.MD Outdated

Update MIGRATION.MD

810deef

Co-authored-by: Jonathan Moskovich <[email protected]>

satween dismissed stale reviews from jonathanmos and 0xnm via 810deef September 8, 2025 08:53

satween requested a review from jonathanmos September 8, 2025 08:53

jonathanmos previously approved these changes Sep 8, 2025

View reviewed changes

Comment thread MIGRATION.MD Outdated

Update MIGRATION.MD

5ded6b2

Co-authored-by: Jonathan Moskovich <[email protected]>

satween dismissed jonathanmos’s stale review via 5ded6b2 September 8, 2025 13:40

satween requested a review from jonathanmos September 8, 2025 13:40

Merge branch 'develop' into tvaleev/feature/RUM-11586-updating-migration

f17ca5d

0xnm approved these changes Sep 9, 2025

View reviewed changes

jonathanmos approved these changes Sep 9, 2025

View reviewed changes

satween merged commit 5616002 into develop Sep 9, 2025
25 checks passed

satween deleted the tvaleev/feature/RUM-11586-updating-migration branch September 9, 2025 15:13

ncreated restored the tvaleev/feature/RUM-11586-updating-migration branch April 9, 2026 10:21

0xnm deleted the tvaleev/feature/RUM-11586-updating-migration branch April 24, 2026 09:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

RUM-11586: updating MIGRATION.MD#2858

RUM-11586: updating MIGRATION.MD#2858
satween merged 9 commits into
developfrom
tvaleev/feature/RUM-11586-updating-migration

satween commented Sep 5, 2025 •

edited

Loading

Uh oh!

Uh oh!

0xnm Sep 5, 2025

Uh oh!

codecov-commenter commented Sep 5, 2025 •

edited

Loading

Uh oh!

rtrieu left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	# Migration from 2.x to 3.0

	The main changes introduced in SDK 3.0 compared to 2.x are:

	1. The `OpenTracing` dependency was removed because it is obsolete.


	We replaced the `OpenTracing` classes with internal one. However we strongly encourage you to use the OTel version as the new tracing API standard.


	### Trace product changes

	#### Migrating tracing from `OpenTracing` to `OpenTelemetry` (recommended)

	> [!WARNING]
	> Note that the `OpenTelemetry` specification library [requires](https://github.com/open-telemetry/opentelemetry-java?tab=readme-ov-file#requirements) desugaring to be enabled for with projects that have a `minSdk` < 26. If this requirement cannot be met in your project see the following section.


	1. Add the `OpenTelemetry` dependency to your `build.gradle.kts`:

	```kotlin
	implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x"))
	```

	2. Replace the `OpenTracing` configuration:
	```kotlin
	GlobalTracer.registerIfAbsent(
	AndroidTracer.Builder()
	.setService(BuildConfig.APPLICATION_ID)
	.build()
	)
	```

	with the `OpenTelemetry` configuration:
	```kotlin
	GlobalOpenTelemetry.set(object : OpenTelemetry {
	private val tracerProvider = OtelTracerProvider.Builder()
	.setService(BuildConfig.APPLICATION_ID)
	.build()

	override fun getTracerProvider(): TracerProvider {
	return tracerProvider
	}

	override fun getPropagators(): ContextPropagators {
	return ContextPropagators.noop()
	}
	})
	```

	> [!NOTE]
	> You can use the default configuration to make it even shorter in case if don't provide any additional parameters:
	```kotlin
	GlobalOpenTelemetry.set(
	DatadogOpenTelemetry(BuildConfig.APPLICATION_ID)
	)
	```

	To access the tracer object for manual (custom) tracing, use `io.opentelemetry.api.GlobalOpenTelemetry.get()` instead of `io.opentracing.util.GlobalTracer.get()`.
	For example:
	```kotlin
	val tracer: Tracer = GlobalOpenTelemetry
	.get()
	.getTracer("SampleApplicationTracer")

	val span = tracer
	.spanBuilder("Executing operation")
	.startSpan()

	// Code that should be instrumented

	span.end()
	```

	Refer to the official `OpenTelemetry` [documentation](https://opentelemetry.io/docs/) for more details.

	#### Migrating tracing from `OpenTracing` to `DatadogTracing` (transition period)

	> [!WARNING]
	> This option has been added for compatibility and to simplify the transition from `OpenTracing` to `OpenTelemetry`, but it may not be available in future major releases. We recommend using `OpenTelemetry` as the standard for tracing tasks. However, if it is not possible to enable desugaring in your project for some reason, you can use this method.

	1. Add the `DatadogTracing` dependency to your `build.gradle.kts`:

	```kotlin
	implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x"))
	```


	2.Replace the `OpenTracing` configuration:
	```kotlin
	GlobalTracer.registerIfAbsent(
	AndroidTracer.Builder()
	.setService(BuildConfig.APPLICATION_ID)
	.build()
	)
	```

	with the `DatadogTracing` configuration:
	```kotlin
	GlobalDatadogTracer.registerIfAbsent(
	DatadogTracing.newTracerBuilder()
	.build()
	)
	```


	For manual (custom) tracing use `com.datadog.android.trace.GlobalDatadogTracer.get()` instead of `io.opentracing.util.GlobalTracer.get()` to access the tracer object.
	For example:
	```kotlin
	val tracer = GlobalDatadogTracer.get()

	val span = tracer
	.buildSpan(operationName)
	.start()

	// Code that should be instrumented

	span.finish()
	```
	Refer to the Datadog [documentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/android?tab=kotlin) for more details.

	API changes:

	\|`2.x`\|`3.0` `OpenTelemetry`\|`3.0` `DatadogTracing`\|
	\|---\|---\|---\|
	\|`io.opentracing.util.GlobalTracer`\|`io.opentelemetry.api.GlobalOpenTelemetry`\|`com.datadog.android.trace.GlobalDatadogTracer`\|
	\|`com.datadog.android.trace.AndroidTracer`\|`io.opentelemetry.api.trace.Tracer`\|`com.datadog.android.trace.api.tracer.DatadogTracer`\|
	\|`io.opentracing.Span`\|`io.opentelemetry.api.trace.Span`\|`com.datadog.android.trace.api.span.DatadogSpan`\|
	\|`io.opentracing.Scope`\|`io.opentelemetry.context.Scope`\|`com.datadog.android.trace.api.scope.DatadogScope`\|
	\|`io.opentracing.SpanContext`\|`io.opentelemetry.api.trace.SpanContext`\|`com.datadog.android.trace.api.span.DatadogSpanContext`\|

	Replacement hints:

	\|`2.x`\|`3.0` `OpenTelemetry`\|`3.0` `DatadogTracing`\|
	\|---\|---\|---\|
	\|`AndroidTracer.Builder().build()`\|\|`DatadogTracing.newTracerBuilder().build()`\|
	\|`AndroidTracer#setPartialFlushThreshold(Int)`\|`OtelTracerProvider#setPartialFlushThreshold()`\|`DatadogTracerBuilder#withPartialFlushMinSpans()`\|
	\|`io.opentracing.SpanContext#toTraceId()`\|`io.opentelemetry.api.trace.SpanContext#getTraceId()`\|`DatadogSpanContext.traceId.toString()`\|
	\|`io.opentracing.Span#setError()`\|`io.opentelemetry.api.trace#recordException()`\|`DatadogSpan#addThrowable()`\|

	### OkHttp instrumentation changes

	The OkHttp instrumentation (`com.datadoghq:dd-sdk-android-okhttp:x.x.x`) doesn't require desugaring support. However few migration actions may be necessary.


	API changes:

	\|`2.x`\|`3.0`\|
	\|--\|--\|
	\|`TracingInterceptor(String, List<String>, TracedRequestListener,Sampler<Span>)`\| Use `TracingInterceptor.Builder()` instead.\|
	\|`TracingInterceptor(String?,Map<String, Set<TracingHeaderType>>, TracedRequestListener, Sampler<Span>)`\| Use `TracingInterceptor.Builder()` instead.\|
	\|`TracingInterceptor(String?,TracedRequestListener,Sampler<Span>)`\|Use `TracingInterceptor.Builder()` instead.\|
	\|`DatadogInterceptor(String?, Map<String, Set<TracingHeaderType>>,TracedRequestListener, RumResourceAttributesProvider, Sampler<Span>)`\|Use `DatadogInterceptor.Builder()` instead. \|
	\|`DatadogInterceptor(String?,List<String>,TracedRequestListener,RumResourceAttributesProvider,Sampler<Span>)`\|Use `DatadogInterceptor.Builder()` instead.\|
	\| `DatadogInterceptor(String?,TracedRequestListener,RumResourceAttributesProvider,Sampler<Span>) ` \| Use `DatadogInterceptor.Builder()` instead. \|


	### Core product changes

	API changes:

	\|`2.x`\| `3.0` \|
	\|--\|------------------------------------------------------------------\|
	\|`Datadog#setUserInfo(String?, ...)`\| User info ID is now mandatory `Datadog.setUserInfo(String, ...)` \|


	### RUM product changes

	API changes:

	\|`2.x`\| `3.0` \|
	\|--\|-------------------------------------------------------------------------------------\|
	\|`DatadogRumMonitor#startResource(String, String, String,Map<String, Any?>)`\| Use `startResource` method which takes `RumHttpMethod` as `method` parameter instead \|
	\|`com.datadog.android.rum.GlobalRum`\|`GlobalRum` object was renamed to `com.datadog.android.rum.GlobalRumMonitor` \|
	\|`com.datadog.android.rum.RumMonitor#addAction()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.RumMonitor#startAction()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.RumMonitor#stopResource()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.RumMonitor#addError()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.RumMonitor#addErrorWithStacktrace()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`\| Parameter `attributes: Map<String, Any?>` is now optional \|
	\|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`\| Parameter `attributes: Map<String, Any?>` is now optional \|

Uh oh!

Conversation

satween commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Review checklist (to be filled by reviewers)

Uh oh!

Uh oh!

0xnm Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

rtrieu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

satween commented Sep 5, 2025 •

edited

Loading

codecov-commenter commented Sep 5, 2025 •

edited

Loading