|
| 1 | +# Migration from 2.x to 3.0 |
| 2 | + |
| 3 | +The main changes introduced in SDK 3.0 compared to 2.x are: |
| 4 | + |
| 5 | +1. The `OpenTracing` dependency was removed because it is obsolete. |
| 6 | + |
| 7 | + |
| 8 | +We replaced the `OpenTracing` classes with internal one. However we strongly encourage you to use the OTel version as the new tracing API standard. |
| 9 | + |
| 10 | + |
| 11 | +### Trace product changes |
| 12 | + |
| 13 | +#### Migrating tracing from `OpenTracing` to `OpenTelemetry` (recommended) |
| 14 | + |
| 15 | +> [!WARNING] |
| 16 | +> 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. |
| 17 | +
|
| 18 | + |
| 19 | +1. Add the `OpenTelemetry` dependency to your `build.gradle.kts`: |
| 20 | + |
| 21 | +```kotlin |
| 22 | +implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x")) |
| 23 | +``` |
| 24 | + |
| 25 | +2. Replace the `OpenTracing` configuration: |
| 26 | +```kotlin |
| 27 | + GlobalTracer.registerIfAbsent( |
| 28 | + AndroidTracer.Builder() |
| 29 | + .setService(BuildConfig.APPLICATION_ID) |
| 30 | + .build() |
| 31 | + ) |
| 32 | +``` |
| 33 | + |
| 34 | +with the `OpenTelemetry` configuration: |
| 35 | +```kotlin |
| 36 | + GlobalOpenTelemetry.set(object : OpenTelemetry { |
| 37 | + private val tracerProvider = OtelTracerProvider.Builder() |
| 38 | + .setService(BuildConfig.APPLICATION_ID) |
| 39 | + .build() |
| 40 | + |
| 41 | + override fun getTracerProvider(): TracerProvider { |
| 42 | + return tracerProvider |
| 43 | + } |
| 44 | + |
| 45 | + override fun getPropagators(): ContextPropagators { |
| 46 | + return ContextPropagators.noop() |
| 47 | + } |
| 48 | + }) |
| 49 | +``` |
| 50 | + |
| 51 | +> [!NOTE] |
| 52 | +> You can use the default configuration to make it even shorter in case if don't provide any additional parameters: |
| 53 | +```kotlin |
| 54 | + GlobalOpenTelemetry.set( |
| 55 | + DatadogOpenTelemetry(BuildConfig.APPLICATION_ID) |
| 56 | + ) |
| 57 | +``` |
| 58 | + |
| 59 | +To access the tracer object for manual (custom) tracing, use `io.opentelemetry.api.GlobalOpenTelemetry.get()` instead of `io.opentracing.util.GlobalTracer.get()`. |
| 60 | +For example: |
| 61 | +```kotlin |
| 62 | + val tracer: Tracer = GlobalOpenTelemetry |
| 63 | + .get() |
| 64 | + .getTracer("SampleApplicationTracer") |
| 65 | + |
| 66 | + val span = tracer |
| 67 | + .spanBuilder("Executing operation") |
| 68 | + .startSpan() |
| 69 | + |
| 70 | + // Code that should be instrumented |
| 71 | + |
| 72 | + span.end() |
| 73 | +``` |
| 74 | + |
| 75 | +Refer to the official `OpenTelemetry` [documentation](https://opentelemetry.io/docs/) for more details. |
| 76 | + |
| 77 | +#### Migrating tracing from `OpenTracing` to `DatadogTracing` (transition period) |
| 78 | + |
| 79 | +> [!WARNING] |
| 80 | +> 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. |
| 81 | +
|
| 82 | +1. Add the `DatadogTracing` dependency to your `build.gradle.kts`: |
| 83 | + |
| 84 | +```kotlin |
| 85 | +implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x")) |
| 86 | +``` |
| 87 | + |
| 88 | + |
| 89 | +2.Replace the `OpenTracing` configuration: |
| 90 | +```kotlin |
| 91 | + GlobalTracer.registerIfAbsent( |
| 92 | + AndroidTracer.Builder() |
| 93 | + .setService(BuildConfig.APPLICATION_ID) |
| 94 | + .build() |
| 95 | + ) |
| 96 | +``` |
| 97 | + |
| 98 | +with the `DatadogTracing` configuration: |
| 99 | +```kotlin |
| 100 | + GlobalDatadogTracer.registerIfAbsent( |
| 101 | + DatadogTracing.newTracerBuilder() |
| 102 | + .build() |
| 103 | + ) |
| 104 | +``` |
| 105 | + |
| 106 | + |
| 107 | +For manual (custom) tracing use `com.datadog.android.trace.GlobalDatadogTracer.get()` instead of `io.opentracing.util.GlobalTracer.get()` to access the tracer object. |
| 108 | +For example: |
| 109 | +```kotlin |
| 110 | + val tracer = GlobalDatadogTracer.get() |
| 111 | + |
| 112 | + val span = tracer |
| 113 | + .buildSpan(operationName) |
| 114 | + .start() |
| 115 | + |
| 116 | + // Code that should be instrumented |
| 117 | + |
| 118 | + span.finish() |
| 119 | +``` |
| 120 | +Refer to the Datadog [documentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/android?tab=kotlin) for more details. |
| 121 | + |
| 122 | +API changes: |
| 123 | + |
| 124 | +|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`| |
| 125 | +|---|---|---| |
| 126 | +|`io.opentracing.util.GlobalTracer`|`io.opentelemetry.api.GlobalOpenTelemetry`|`com.datadog.android.trace.GlobalDatadogTracer`| |
| 127 | +|`com.datadog.android.trace.AndroidTracer`|`io.opentelemetry.api.trace.Tracer`|`com.datadog.android.trace.api.tracer.DatadogTracer`| |
| 128 | +|`io.opentracing.Span`|`io.opentelemetry.api.trace.Span`|`com.datadog.android.trace.api.span.DatadogSpan`| |
| 129 | +|`io.opentracing.Scope`|`io.opentelemetry.context.Scope`|`com.datadog.android.trace.api.scope.DatadogScope`| |
| 130 | +|`io.opentracing.SpanContext`|`io.opentelemetry.api.trace.SpanContext`|`com.datadog.android.trace.api.span.DatadogSpanContext`| |
| 131 | + |
| 132 | +Replacement hints: |
| 133 | + |
| 134 | +|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`| |
| 135 | +|---|---|---| |
| 136 | +|`AndroidTracer.Builder().build()`||`DatadogTracing.newTracerBuilder().build()`| |
| 137 | +|`AndroidTracer#setPartialFlushThreshold(Int)`|`OtelTracerProvider#setPartialFlushThreshold()`|`DatadogTracerBuilder#withPartialFlushMinSpans()`| |
| 138 | +|`io.opentracing.SpanContext#toTraceId()`|`io.opentelemetry.api.trace.SpanContext#getTraceId()`|`DatadogSpanContext.traceId.toString()`| |
| 139 | +|`io.opentracing.Span#setError()`|`io.opentelemetry.api.trace#recordException()`|`DatadogSpan#addThrowable()`| |
| 140 | + |
| 141 | +### OkHttp instrumentation changes |
| 142 | + |
| 143 | +The OkHttp instrumentation (`com.datadoghq:dd-sdk-android-okhttp:x.x.x`) doesn't require desugaring support. However few migration actions may be necessary. |
| 144 | + |
| 145 | + |
| 146 | +API changes: |
| 147 | + |
| 148 | +|`2.x`|`3.0`| |
| 149 | +|--|--| |
| 150 | +|`TracingInterceptor(String, List<String>, TracedRequestListener,Sampler<Span>)`| Use `TracingInterceptor.Builder()` instead.| |
| 151 | +|`TracingInterceptor(String?,Map<String, Set<TracingHeaderType>>, TracedRequestListener, Sampler<Span>)`| Use `TracingInterceptor.Builder()` instead.| |
| 152 | +|`TracingInterceptor(String?,TracedRequestListener,Sampler<Span>)`|Use `TracingInterceptor.Builder()` instead.| |
| 153 | +|`DatadogInterceptor(String?, Map<String, Set<TracingHeaderType>>,TracedRequestListener, RumResourceAttributesProvider, Sampler<Span>)`|Use `DatadogInterceptor.Builder()` instead. | |
| 154 | +|`DatadogInterceptor(String?,List<String>,TracedRequestListener,RumResourceAttributesProvider,Sampler<Span>)`|Use `DatadogInterceptor.Builder()` instead.| |
| 155 | +| `DatadogInterceptor(String?,TracedRequestListener,RumResourceAttributesProvider,Sampler<Span>) ` | Use `DatadogInterceptor.Builder()` instead. | |
| 156 | + |
| 157 | + |
| 158 | +### Core product changes |
| 159 | + |
| 160 | +API changes: |
| 161 | + |
| 162 | +|`2.x`| `3.0` | |
| 163 | +|--|------------------------------------------------------------------| |
| 164 | +|`Datadog#setUserInfo(String?, ...)`| User info ID is now mandatory `Datadog.setUserInfo(String, ...)` | |
| 165 | + |
| 166 | + |
| 167 | +### RUM product changes |
| 168 | + |
| 169 | +API changes: |
| 170 | + |
| 171 | +|`2.x`| `3.0` | |
| 172 | +|--|-------------------------------------------------------------------------------------| |
| 173 | +|`DatadogRumMonitor#startResource(String, String, String,Map<String, Any?>)`| Use `startResource` method which takes `RumHttpMethod` as `method` parameter instead | |
| 174 | +|`com.datadog.android.rum.GlobalRum`|`GlobalRum` object was renamed to `com.datadog.android.rum.GlobalRumMonitor` | |
| 175 | +|`com.datadog.android.rum.RumMonitor#addAction()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 176 | +|`com.datadog.android.rum.RumMonitor#startAction()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 177 | +|`com.datadog.android.rum.RumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 178 | +|`com.datadog.android.rum.RumMonitor#addError()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 179 | +|`com.datadog.android.rum.RumMonitor#addErrorWithStacktrace()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 180 | +|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 181 | +|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map<String, Any?>` is now optional | |
| 182 | + |
1 | 183 | # Migration from 1.x to 2.0 |
2 | 184 |
|
3 | 185 | The main changes introduced in SDK 2.0 compared to 1.x are: |
|
0 commit comments